diff --git a/README.md b/README.md index 280d8090..fc108b63 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,111 @@ -# Xyph +# XYPH -A planning compiler and coordination foundation for humans and agents. Xyph replaces scattered tickets and chat threads with a single, deterministic WARP graph that tracks the genealogy of intent from "why" to "shipped." +A sovereign agentic planning substrate and Edict execution runtime designed for the [Continuum](https://github.com/flyingrobots/continuum) post-Unix platform. -Xyph is designed for the high-output team that demands geometric lawfulness in their coordination. It scales from solo offline-first planning to multi-agent orchestrated execution with cryptographic settlement. +XYPH replaces traditional central-database ticketing systems with a distributed network of **Continuum Participants** that materialize project planning coordinates (Intents, Quests, Scrolls, and Policies) directly from an immutable, verifiable causal history. -![Xyph demo](docs/assets/title-screen.gif) +> [!WARNING] +> **ROADMAP ALIGNMENT** +> While XYPH currently operates as a local-first TypeScript CLI and TUI over git-warp graphs, it is actively transitioning to a native Continuum Participant. The Edict compilation, capability-bound execution lanes, and peer-to-peer Continuum sync protocols described below represent our target architecture. -## Why Xyph? +--- -Unlike traditional trackers that store status, Xyph computes reality from a shared, immutable history. +## Why XYPH? -- **The Graph _is_ the Plan**: Coordination happens through **stigmergy**—participants modify the graph, and others observe the changes. The environment *is* the communication medium. -- **Causal Sovereignty**: Every unit of work (Quest) must trace back to an authoritative declaration (Intent). AI agents cannot "hallucinate" work; they must be authorized by the genealogy of intent. -- **Deterministic Convergence**: Built on [WARP (Structural Worldline Memory)](https://github.com/git-stunts/git-warp), Xyph ensures that all writers compute the same final state, even after weeks of offline work. -- **Cryptographic Settlement**: Completed work is sealed with Ed25519 Guild Seals. Trust is mathematical, not administrative. +In a post-Unix architecture, files are not fundamental; they are bounded, materialized readings over causal history. XYPH applies this tenet to coordination: -## Quick Start +* **Verifiable Causal Sovereignty**: Every quest or backlog item is linked back to a human-authorized root node through the **Genealogy of Intent**. AI agents cannot hallucinate work; they can only claim and act on cryptographically signed, authorized tasks. +* **Edict Execution Sandbox**: Planning changes and graph mutations are written as **Edict Intents**—safe, statically verified operations. Edict contains the authority blast radius of prompt injections by proving exactly which graph nodes can be touched before code runs. +* **Coordination-Free Concurrency**: Built on [git-warp](https://github.com/git-stunts/git-warp), XYPH coordinates concurrent agent claims offline-first. Diverging worldlines are converged deterministically by Last-Write-Wins (LWW) CRDT semantics, or reconciled via explicit sequenced admission. +* **Cryptographic Settlement**: Quests are sealed with **Scrolls**—cryptographically signed Boundary Transition Records (BTRs). Peer participants or human operators verify quest resolution by inspecting the Scroll's self-contained signature envelope, without needing to walk or download the full repository history. + +--- -### 1. Local Setup +## System Architecture + +XYPH functions as a tiered planning and execution runtime: + +```text + ┌───────────────────────────────────────────────────┐ + │ Surface / Interface │ + │ Bijou TUI Cockpit · Actuator CLI · TUI API │ + └─────────────────────────┬─────────────────────────┘ + ▼ + ┌───────────────────────────────────────────────────┐ + │ Versioned JSONL Control Plane (XYPH) │ + │ Canonical interface for queries and commands │ + └─────────────────────────┬─────────────────────────┘ + ▼ + ┌───────────────────────────────────────────────────┐ + │ Edict Execution Runtime │ + │ Evaluates capability-bound lanes in WASM │ + │ (continuum.lane.lawful-autonomous/v1) │ + └─────────────────────────┬─────────────────────────┘ + ▼ + ┌───────────────────────────────────────────────────┐ + │ git-warp Causal History Substrate │ + │ Exchanges causal cones P2P via Continuum │ + └───────────────────────────────────────────────────┘ +``` + +* **The Cold Path (Authoring)**: Edict source code is statically compiled and verified against target profiles, generating a certified contract bundle stored in the Pre-Admitted Operation Registry. +* **The Hot Path (Execution)**: Autonomous agents or TUI actions invoke the pre-admitted registry using a scoped `CapabilityRef`, a basis coordinate, and an idempotency key. -Install dependencies and initialize your first project. +--- + +## Quick Start + +### 1. Bootstrap Participant +Initialize your local participant node and register your Ed25519 identity keypair: ```bash npm install +npx tsx xyph-actuator.ts generate-key npx tsx xyph-actuator.ts login human.ada ``` -### 2. Fast Coordination - -Declare an intent and create a quest. +### 2. Declare and Claim Intent +Wire a new planning requirement back to a sovereign human intent and volunteer for the quest: ```bash -# Declare why work should exist +# Declare the root intent (Why the work exists) npx tsx xyph-actuator.ts intent intent:setup \ - --title "Repository needs industrial-grade docs" \ + --title "Repository needs Edict verification targets" \ --requested-by human.ada -# Create a unit of work -npx tsx xyph-actuator.ts quest task:docs-001 \ - --title "Overhaul root README and signposts" \ +# Create a scoped quest linked to the intent +npx tsx xyph-actuator.ts quest task:setup-001 \ + --title "Implement git-warp target profile schema" \ --intent intent:setup -``` -### 3. TUI Cockpit +# Claim the quest (Locks state to IN_PROGRESS under your capability) +npx tsx xyph-actuator.ts claim task:setup-001 +``` -Open the Bijou-powered interactive dashboard to navigate the roadmap. +### 3. Open the Cockpit +Boot the interactive Bijou-powered cockpit to manage work streams and inspect active suggestion lanes: ```bash npm run tui ``` -![XYPH](./docs/assets/xyph.png) +--- + +## Documentation Map -## Documentation +To orient yourself, follow the authoritative manifests in order: -- **[Guide](./GUIDE.md)**: Orientation, the fast path, and Digital Guild nouns. -- **[Advanced Guide](./ADVANCED_GUIDE.md)**: Deep dives into worldlines, braiding, and settlement. -- **[Architecture](./ARCHITECTURE.md)**: The authoritative structural reference (Hexagonal, Ports, WARP). -- **[Vision](./docs/VISION.md)**: Core tenets and the stigmergic mission. -- **[Method](./design/METHOD.md)**: Repo work doctrine and the cycle loop. -- **[Contributing](./CONTRIBUTING.md)**: Topic-based contract-graph documentation rules, self-hosting dogfooding loop, quality gates, and initiate glossary. +1. **The Entrance**: + * [GUIDE.md](./GUIDE.md) — Orientation, Digital Guild nouns, and quick checklist. +2. **The Bedrock**: + * [ARCHITECTURE.md](./docs/canonical/ARCHITECTURE.md) — Authoritative structural references (Hexagonal, Ports, WARP). + * [docs/VISION.md](./docs/VISION.md) — Stigmergic tenets and the mission. + * [METHOD.md](./docs/canonical/METHOD.md) — Work doctrine and cycle loops. +3. **The Direction**: + * [docs/BEARING.md](./docs/BEARING.md) — Current release posture and strategic target. + * [docs/topics/git-warp-evolution/README.md](./docs/topics/git-warp-evolution/README.md) — Optical query and speculative strand roadmap. + * [docs/topics/edict-integration/README.md](./docs/topics/edict-integration/README.md) — Sandbox boundaries and Edict target profiles. --- -Built with geometric lawfulness by [FLYING ROBOTS](https://github.com/flyingrobots) +Built with geometric lawfulness for the post-Unix era by [FLYING ROBOTS](https://github.com/flyingrobots). diff --git a/docs/diagrams/cycle-loop.svg b/docs/diagrams/cycle-loop.svg index 093434e5..ee953b70 100644 --- a/docs/diagrams/cycle-loop.svg +++ b/docs/diagrams/cycle-loop.svg @@ -1 +1 @@ -

asap/

cycle/

failing tests

passing tests

findings/debt

PR to main

Pull

Branch

Red

Green

Retro

Ship

\ No newline at end of file +

asap/

cycle/

failing tests

passing tests

findings/debt

PR to main

Pull

Branch

Red

Green

Retro

Ship

\ No newline at end of file diff --git a/docs/diagrams/milestone-lifecycle.svg b/docs/diagrams/milestone-lifecycle.svg index 92178e76..b3ccb7b1 100644 --- a/docs/diagrams/milestone-lifecycle.svg +++ b/docs/diagrams/milestone-lifecycle.svg @@ -1 +1 @@ -

OPEN

LOCKED

SHIPPED

\ No newline at end of file +

OPEN

LOCKED

SHIPPED

\ No newline at end of file diff --git a/docs/diagrams/orchestration-fsm.svg b/docs/diagrams/orchestration-fsm.svg index f113fe96..522a523e 100644 --- a/docs/diagrams/orchestration-fsm.svg +++ b/docs/diagrams/orchestration-fsm.svg @@ -1 +1 @@ -

INGEST

NORMALIZE

FAILED

CLASSIFY

VALIDATE

MERGE

REBALANCE

SCHEDULE

REVIEW

EMIT

APPLY

DONE

\ No newline at end of file +

INGEST

NORMALIZE

FAILED

CLASSIFY

VALIDATE

MERGE

REBALANCE

SCHEDULE

REVIEW

EMIT

APPLY

DONE

\ No newline at end of file diff --git a/docs/diagrams/planning-pipeline.svg b/docs/diagrams/planning-pipeline.svg index fbd772a0..8e153636 100644 --- a/docs/diagrams/planning-pipeline.svg +++ b/docs/diagrams/planning-pipeline.svg @@ -1 +1 @@ -

INGEST

NORMALIZE

CLASSIFY

VALIDATE

MERGE

REBALANCE

SCHEDULE

REVIEW

EMIT

APPLY

DONE

FAILED

\ No newline at end of file +

INGEST

NORMALIZE

CLASSIFY

VALIDATE

MERGE

REBALANCE

SCHEDULE

REVIEW

EMIT

APPLY

DONE

FAILED

\ No newline at end of file diff --git a/docs/diagrams/quest-status-lifecycle.svg b/docs/diagrams/quest-status-lifecycle.svg index 40c05bf5..5d0af869 100644 --- a/docs/diagrams/quest-status-lifecycle.svg +++ b/docs/diagrams/quest-status-lifecycle.svg @@ -1 +1 @@ -

promote

reject

reject

claim

seal / merge

reopen

BACKLOG

PLANNED

GRAVEYARD

IN_PROGRESS

DONE

BLOCKED

\ No newline at end of file +

promote

reject

reject

claim

seal / merge

reopen

BACKLOG

PLANNED

GRAVEYARD

IN_PROGRESS

DONE

BLOCKED

\ No newline at end of file diff --git a/docs/diagrams/task-lifecycle.svg b/docs/diagrams/task-lifecycle.svg index c7be8274..05e02552 100644 --- a/docs/diagrams/task-lifecycle.svg +++ b/docs/diagrams/task-lifecycle.svg @@ -1 +1 @@ -

promote (human only)

reject

claim

reject

seal / merge

reopen (human only)

BACKLOG

PLANNED

GRAVEYARD

IN_PROGRESS

BLOCKED

DONE

\ No newline at end of file +

promote (human only)

reject

claim

reject

seal / merge

reopen (human only)

BACKLOG

PLANNED

GRAVEYARD

IN_PROGRESS

BLOCKED

DONE

\ No newline at end of file diff --git a/docs/diagrams/teardown-cli-context.svg b/docs/diagrams/teardown-cli-context.svg index ae86e7d3..575c7137 100644 --- a/docs/diagrams/teardown-cli-context.svg +++ b/docs/diagrams/teardown-cli-context.svg @@ -1 +1 @@ -

graphPort

observation

operationalRead

inspection

shared singleton

shared singleton

shared singleton

CliContext

+agentId: string

+cwd: string

+graphName: string

+identity: ResolvedIdentity

+json: boolean

+graphPort: WarpGraphAdapter

+observation: ObservationPort

+operationalRead: OperationalReadPort

+inspection: SubstrateInspectionPort

+logger: DiagnosticLogPort

+style: StylePort

+ok(msg) : void

+warn(msg) : void

+fail(msg) : never

+failWithData(msg, data, diagnostics) : never

+jsonStart(command, data) : void

+jsonProgress(command, message, data) : void

+jsonOut(envelope) : void

WarpGraphAdapter

-graphPromise: Promise<WarpGraph> | null

+getGraph() : Promise<WarpGraph>

+openIsolatedGraph() : Promise<WarpGraph>

+reset() : void

WarpObservationAdapter

+openSession(request) : Promise<ObservationSession>

WarpOperationalReadAdapter

+getBriefing(perspective) : Promise<Briefing>

+getNext(criteria) : Promise<ActionableItem[]>

WarpSubstrateInspectionAdapter

+inspectGraph() : Promise<InspectionReport>

\ No newline at end of file +

graphPort

observation

operationalRead

inspection

shared singleton

shared singleton

shared singleton

CliContext

+agentId: string

+cwd: string

+graphName: string

+identity: ResolvedIdentity

+json: boolean

+graphPort: WarpGraphAdapter

+observation: ObservationPort

+operationalRead: OperationalReadPort

+inspection: SubstrateInspectionPort

+logger: DiagnosticLogPort

+style: StylePort

+ok(msg) : void

+warn(msg) : void

+fail(msg) : never

+failWithData(msg, data, diagnostics) : never

+jsonStart(command, data) : void

+jsonProgress(command, message, data) : void

+jsonOut(envelope) : void

WarpGraphAdapter

-graphPromise: Promise<WarpGraph> | null

+getGraph() : Promise<WarpGraph>

+openIsolatedGraph() : Promise<WarpGraph>

+reset() : void

WarpObservationAdapter

+openSession(request) : Promise<ObservationSession>

WarpOperationalReadAdapter

+getBriefing(perspective) : Promise<Briefing>

+getNext(criteria) : Promise<ActionableItem[]>

WarpSubstrateInspectionAdapter

+inspectGraph() : Promise<InspectionReport>

\ No newline at end of file diff --git a/docs/diagrams/teardown-domain-entities.svg b/docs/diagrams/teardown-domain-entities.svg index 1cab3058..3f180dff 100644 --- a/docs/diagrams/teardown-domain-entities.svg +++ b/docs/diagrams/teardown-domain-entities.svg @@ -1 +1 @@ -

authorized-by

implements

decomposes-to

has-criterion

verifies

submits

has-patchset

reviews

decides

INTENT

string

id

PK

intent:*

string

title

min 5 chars

string

requestedBy

must be human.*

number

createdAt

unix ms timestamp

string

description

optional

QUEST

string

id

PK

task:*

string

title

min 5 chars

string

status

BACKLOG|PLANNED|READY|IN_PROGRESS|BLOCKED|DONE|GRAVEYARD

number

hours

non-negative

string

priority

P0-P5 default P3

string

taskKind

delivery|spike|maintenance|ops

string

assignedTo

optional agent/human

number

claimedAt

optional

number

completedAt

optional

STORY

string

id

PK

story:*

string

title

string

persona

who

string

goal

what

string

benefit

why

string

createdBy

number

createdAt

REQUIREMENT

string

id

PK

req:*

string

description

string

kind

functional|non-functional

string

priority

must|should|could|wont

CRITERION

string

id

PK

criterion:*

string

description

min 5 chars

boolean

verifiable

EVIDENCE

string

id

PK

evidence:*

string

kind

test|benchmark|manual|screenshot

string

result

pass|fail|linked

number

producedAt

string

producedBy

string

artifactHash

optional

SUBMISSION

string

id

PK

submission:*

string

questId

FK

task:*

string

submittedBy

number

submittedAt

PATCHSET

string

id

PK

patchset:*

string

workspaceRef

string

description

min 10 chars

string

authoredBy

number

authoredAt

REVIEW

string

id

PK

review:*

string

patchsetId

FK

string

verdict

approve|request-changes|comment

string

reviewedBy

number

reviewedAt

DECISION

string

id

PK

decision:*

string

submissionId

FK

string

kind

merge|close

string

decidedBy

string

rationale

\ No newline at end of file +

authorized-by

implements

decomposes-to

has-criterion

verifies

submits

has-patchset

reviews

decides

INTENT

string

id

PK

intent:*

string

title

min 5 chars

string

requestedBy

must be human.*

number

createdAt

unix ms timestamp

string

description

optional

QUEST

string

id

PK

task:*

string

title

min 5 chars

string

status

BACKLOG|PLANNED|READY|IN_PROGRESS|BLOCKED|DONE|GRAVEYARD

number

hours

non-negative

string

priority

P0-P5 default P3

string

taskKind

delivery|spike|maintenance|ops

string

assignedTo

optional agent/human

number

claimedAt

optional

number

completedAt

optional

STORY

string

id

PK

story:*

string

title

string

persona

who

string

goal

what

string

benefit

why

string

createdBy

number

createdAt

REQUIREMENT

string

id

PK

req:*

string

description

string

kind

functional|non-functional

string

priority

must|should|could|wont

CRITERION

string

id

PK

criterion:*

string

description

min 5 chars

boolean

verifiable

EVIDENCE

string

id

PK

evidence:*

string

kind

test|benchmark|manual|screenshot

string

result

pass|fail|linked

number

producedAt

string

producedBy

string

artifactHash

optional

SUBMISSION

string

id

PK

submission:*

string

questId

FK

task:*

string

submittedBy

number

submittedAt

PATCHSET

string

id

PK

patchset:*

string

workspaceRef

string

description

min 10 chars

string

authoredBy

number

authoredAt

REVIEW

string

id

PK

review:*

string

patchsetId

FK

string

verdict

approve|request-changes|comment

string

reviewedBy

number

reviewedAt

DECISION

string

id

PK

decision:*

string

submissionId

FK

string

kind

merge|close

string

decidedBy

string

rationale

\ No newline at end of file diff --git a/docs/diagrams/teardown-hexagonal-arch.svg b/docs/diagrams/teardown-hexagonal-arch.svg index 42b412e8..edf29b9e 100644 --- a/docs/diagrams/teardown-hexagonal-arch.svg +++ b/docs/diagrams/teardown-hexagonal-arch.svg @@ -1 +1 @@ -

«interface»

GraphPort

+getGraph() : Promise<WarpGraph>

+openIsolatedGraph() : Promise<WarpGraph>

+reset() : void

«interface»

IntakePort

+promote(questId, intentId, campaignId) : Promise<string>

+shape(questId, opts) : Promise<string>

+ready(questId) : Promise<string>

+reject(questId, rationale) : Promise<string>

+reopen(questId) : Promise<string>

«interface»

ObservationPort

+openSession(request) : Promise<ObservationSession>

«interface»

SubmissionPort

+submit(args) : Promise<PatchResult>

+revise(args) : Promise<PatchResult>

+review(args) : Promise<PatchResult>

+decide(args) : Promise<PatchResult>

«interface»

LlmPort

+analyzeTestCoverage(request) : Promise<LlmMatch[]>

«interface»

ConfigPort

+get<K>(key) : Promise<XyphConfig[K]>

+getAll() : Promise<XyphConfig>

+set<K>(key, value, target) : Promise<void>

WarpGraphAdapter

+getGraph() : Promise<WarpGraph>

+openIsolatedGraph() : Promise<WarpGraph>

+reset() : void

WarpIntakeAdapter

+promote(...) : Promise<string>

+ready(...) : Promise<string>

WarpObservationAdapter

+openSession(request) : Promise<ObservationSession>

WarpSubmissionAdapter

+submit(...) : Promise<PatchResult>

+decide(...) : Promise<PatchResult>

AnthropicLlmAdapter

+analyzeTestCoverage(request) : Promise<LlmMatch[]>

NoOpLlmAdapter

+analyzeTestCoverage(request) : Promise<LlmMatch[]>

ConfigAdapter

+get<K>(key) : Promise<XyphConfig[K]>

+set<K>(key, value, target) : Promise<void>

\ No newline at end of file +

«interface»

GraphPort

+getGraph() : Promise<WarpGraph>

+openIsolatedGraph() : Promise<WarpGraph>

+reset() : void

«interface»

IntakePort

+promote(questId, intentId, campaignId) : Promise<string>

+shape(questId, opts) : Promise<string>

+ready(questId) : Promise<string>

+reject(questId, rationale) : Promise<string>

+reopen(questId) : Promise<string>

«interface»

ObservationPort

+openSession(request) : Promise<ObservationSession>

«interface»

SubmissionPort

+submit(args) : Promise<PatchResult>

+revise(args) : Promise<PatchResult>

+review(args) : Promise<PatchResult>

+decide(args) : Promise<PatchResult>

«interface»

LlmPort

+analyzeTestCoverage(request) : Promise<LlmMatch[]>

«interface»

ConfigPort

+get<K>(key) : Promise<XyphConfig[K]>

+getAll() : Promise<XyphConfig>

+set<K>(key, value, target) : Promise<void>

WarpGraphAdapter

+getGraph() : Promise<WarpGraph>

+openIsolatedGraph() : Promise<WarpGraph>

+reset() : void

WarpIntakeAdapter

+promote(...) : Promise<string>

+ready(...) : Promise<string>

WarpObservationAdapter

+openSession(request) : Promise<ObservationSession>

WarpSubmissionAdapter

+submit(...) : Promise<PatchResult>

+decide(...) : Promise<PatchResult>

AnthropicLlmAdapter

+analyzeTestCoverage(request) : Promise<LlmMatch[]>

NoOpLlmAdapter

+analyzeTestCoverage(request) : Promise<LlmMatch[]>

ConfigAdapter

+get<K>(key) : Promise<XyphConfig[K]>

+set<K>(key, value, target) : Promise<void>

\ No newline at end of file diff --git a/docs/diagrams/teardown-jsonl-types.svg b/docs/diagrams/teardown-jsonl-types.svg index 3f0afac3..66ff0ecd 100644 --- a/docs/diagrams/teardown-jsonl-types.svg +++ b/docs/diagrams/teardown-jsonl-types.svg @@ -1 +1 @@ -

JsonStreamEvent

+event: start | progress

+command: string

+at: number

+message?: string

+data?: Record

JsonEnvelope

+success: true

+command: string

+data: Record

+diagnostics?: Diagnostic[]

JsonErrorEnvelope

+success: false

+error: string

+data?: Record

+diagnostics?: Diagnostic[]

Diagnostic

+code: string

+message: string

+path?: string

+context?: Record

\ No newline at end of file +

JsonStreamEvent

+event: start | progress

+command: string

+at: number

+message?: string

+data?: Record

JsonEnvelope

+success: true

+command: string

+data: Record

+diagnostics?: Diagnostic[]

JsonErrorEnvelope

+success: false

+error: string

+data?: Record

+diagnostics?: Diagnostic[]

Diagnostic

+code: string

+message: string

+path?: string

+context?: Record

\ No newline at end of file diff --git a/docs/diagrams/teardown-schema.svg b/docs/diagrams/teardown-schema.svg index 454fd3ce..c2c18edb 100644 --- a/docs/diagrams/teardown-schema.svg +++ b/docs/diagrams/teardown-schema.svg @@ -1 +1 @@ -

source of

target of

NODE

string

id

PK

prefix:identifier format

string

prefix

one of 46 PREFIXES

string

identifier

arbitrary slug

EDGE

string

source

FK

must be valid node id

string

target

FK

must be valid node id

string

type

one of 33 EDGE_TYPES

float

confidence

optional 0.0-1.0

\ No newline at end of file +

source of

target of

NODE

string

id

PK

prefix:identifier format

string

prefix

one of 46 PREFIXES

string

identifier

arbitrary slug

EDGE

string

source

FK

must be valid node id

string

target

FK

must be valid node id

string

type

one of 33 EDGE_TYPES

float

confidence

optional 0.0-1.0

\ No newline at end of file diff --git a/docs/diagrams/teardown-submission-lifecycle.svg b/docs/diagrams/teardown-submission-lifecycle.svg index 8d4c58b7..d4a7ec39 100644 --- a/docs/diagrams/teardown-submission-lifecycle.svg +++ b/docs/diagrams/teardown-submission-lifecycle.svg @@ -1 +1 @@ -

submit()

review(request-changes)

revise() — new patchset supersedes old

review(approve) — threshold met

decide(merge)

decide(close)

decide(close)

decide(close)

OPEN

CHANGES_REQUESTED

APPROVED

MERGED

CLOSED

\ No newline at end of file +

submit()

review(request-changes)

revise() — new patchset supersedes old

review(approve) — threshold met

decide(merge)

decide(close)

decide(close)

decide(close)

OPEN

CHANGES_REQUESTED

APPROVED

MERGED

CLOSED

\ No newline at end of file diff --git a/docs/diagrams/vision-tenets.svg b/docs/diagrams/vision-tenets.svg index d7100d6f..49b784b6 100644 --- a/docs/diagrams/vision-tenets.svg +++ b/docs/diagrams/vision-tenets.svg @@ -1 +1 @@ -

Xyph

Stigmergic Coordination

Environment as Medium

Shared Deterministic Plan

Implicit Task Discovery

Causal Sovereignty

Genealogy of Intent

Human-Rooted Work

Authorized Agent Quests

Deterministic Bedrock

CRDT

Offline Convergence

Immutable Causal History

Cryptographic Trust

Ed25519 Guild Seals

Scrolls

Mathematical Settlement

Agent-Human Parity

JSONL Control Plane

Shared Domain Model

Common TUI Cockpit

\ No newline at end of file +

Xyph

Stigmergic Coordination

Environment as Medium

Shared Deterministic Plan

Implicit Task Discovery

Causal Sovereignty

Genealogy of Intent

Human-Rooted Work

Authorized Agent Quests

Deterministic Bedrock

CRDT

Offline Convergence

Immutable Causal History

Cryptographic Trust

Ed25519 Guild Seals

Scrolls

Mathematical Settlement

Agent-Human Parity

JSONL Control Plane

Shared Domain Model

Common TUI Cockpit

\ No newline at end of file diff --git a/docs/diagrams/xyph-edict-sequence.mmd b/docs/diagrams/xyph-edict-sequence.mmd new file mode 100644 index 00000000..2113d89b --- /dev/null +++ b/docs/diagrams/xyph-edict-sequence.mmd @@ -0,0 +1,14 @@ +sequenceDiagram + autonumber + participant Agent as Autonomous Agent + participant XYPH as XYPH Runtime + participant HOLMES as HOLMES (Assurance) + participant gitwarp as git-warp (Substrate) + + Agent->>Agent: Generate Edict intent source code + Agent->>XYPH: Submit intent for compilation + XYPH->>XYPH: Compile to Core IR & verify bounds + XYPH->>HOLMES: Check verifier report & generate Lawfulness Certificate + HOLMES-->>XYPH: Certified Contract Bundle + XYPH->>gitwarp: Evaluate admission policy & execute in sandboxed WASM + gitwarp-->>Agent: Return typed obstruction or success receipt diff --git a/docs/diagrams/xyph-edict-sequence.mmd.sha256 b/docs/diagrams/xyph-edict-sequence.mmd.sha256 new file mode 100644 index 00000000..1cc582ec --- /dev/null +++ b/docs/diagrams/xyph-edict-sequence.mmd.sha256 @@ -0,0 +1 @@ +1da7fe54b522885ce6789ed228ee5c4879ffd84026a4fa227af08b26e11970a4 diff --git a/docs/diagrams/xyph-edict-sequence.svg b/docs/diagrams/xyph-edict-sequence.svg new file mode 100644 index 00000000..f22337d1 --- /dev/null +++ b/docs/diagrams/xyph-edict-sequence.svg @@ -0,0 +1 @@ +git-warp (Substrate)HOLMES (Assurance)XYPH RuntimeAutonomous Agentgit-warp (Substrate)HOLMES (Assurance)XYPH RuntimeAutonomous AgentGenerate Edict intent source code1Submit intent for compilation2Compile to Core IR & verify bounds3Check verifier report & generate Lawfulness Certificate4Certified Contract Bundle5Evaluate admission policy & execute in sandboxed WASM6Return typed obstruction or success receipt7 \ No newline at end of file diff --git a/docs/diagrams/xyph-evolution-shifts.mmd b/docs/diagrams/xyph-evolution-shifts.mmd new file mode 100644 index 00000000..7370972d --- /dev/null +++ b/docs/diagrams/xyph-evolution-shifts.mmd @@ -0,0 +1,19 @@ +flowchart TD + subgraph From ["Monolithic / Local (Present)"] + A1["Monolithic Materialization (Full GraphSnapshot)"] + A2["Direct Worldline Mutations (Planning Clutter)"] + A3["Walking Full Git History (Verifying Quest Scrolls)"] + A4["Centralized Git Sync (origin/main)"] + end + + subgraph To ["Decentralized / Post-Unix (Target)"] + B1["Bounded Quest Optics (Causal Cone Subgraphs)"] + B2["Speculative Strands (Counterfactual Lanes)"] + B3["Boundary Transition Records (Cryptographic Scrolls)"] + B4["Continuum Protocol (P2P Agent Treaties)"] + end + + A1 -->|Shift I| B1 + A2 -->|Shift II| B2 + A3 -->|Shift III| B3 + A4 -->|Shift IV| B4 diff --git a/docs/diagrams/xyph-evolution-shifts.mmd.sha256 b/docs/diagrams/xyph-evolution-shifts.mmd.sha256 new file mode 100644 index 00000000..40a2d27b --- /dev/null +++ b/docs/diagrams/xyph-evolution-shifts.mmd.sha256 @@ -0,0 +1 @@ +43429bf4e95415aae178acd900a961ed4f30db5eb2024f9d92faa23ee3c033ff diff --git a/docs/diagrams/xyph-evolution-shifts.svg b/docs/diagrams/xyph-evolution-shifts.svg new file mode 100644 index 00000000..89cc526b --- /dev/null +++ b/docs/diagrams/xyph-evolution-shifts.svg @@ -0,0 +1 @@ +

Decentralized / Post-Unix (Target)

Monolithic / Local (Present)

Shift I

Shift II

Shift III

Shift IV

Monolithic Materialization (Full GraphSnapshot)

Direct Worldline Mutations (Planning Clutter)

Walking Full Git History (Verifying Quest Scrolls)

Centralized Git Sync (origin/main)

Bounded Quest Optics (Causal Cone Subgraphs)

Speculative Strands (Counterfactual Lanes)

Boundary Transition Records (Cryptographic Scrolls)

Continuum Protocol (P2P Agent Treaties)

\ No newline at end of file diff --git a/docs/topics/edict-integration/README.md b/docs/topics/edict-integration/README.md new file mode 100644 index 00000000..f75267b2 --- /dev/null +++ b/docs/topics/edict-integration/README.md @@ -0,0 +1,180 @@ +# Edict Integration: Safe Optics & Bounded Execution Model for XYPH + +> [!WARNING] +> **ROADMAP DOCUMENT — NOT PRESENT IMPLEMENTATION TRUTH** +> As of June 21, 2026, Edict is in early alpha. The first alpha issue is open and explicitly covers only parsing and source-AST validation. Core IR, target lowerers, bundle admission, and runtime execution are not yet implemented. This document establishes the target architecture, integration requirements, and conformance constraints for future implementation. + +This document outlines how **Edict**—the safe, statically verifiable programming language for Optics—will integrate into XYPH to close the ambient-authority gap for migrated operations, contain the blast radius of prompt injection, and establish secure, verified agent execution. + +--- + +## 1. The Core Architecture + +Edict bridges the gap between schema definitions, governance lawpacks, and the underlying `git-warp` causal history runtime. + +Unlike the initial proposal, GraphQL is treated as an adapter rather than XYPH’s sovereign top layer. XYPH's canonical machine interface is its versioned JSONL control plane. Edict is designed to be usable directly over the control plane without GraphQL. + +```text + ┌──────────────────────────────────────────────────────────┐ + │ Surface Adapters (GraphQL / CLI / TUI) │ + │ Presents views and captures structured inputs │ + └──────────────────────────┬───────────────────────────────┘ + ▼ + ┌──────────────────────────────────────────────────────────┐ + │ Canonical JSONL Control Plane (XYPH) │ + │ Sovereign interface for reading & submitting commands │ + └──────────────────────────┬───────────────────────────────┘ + ▼ + ┌──────────────────────────────────────────────────────────┐ + │ Edict Operations (Optics) │ + │ Statically verified, capability-bound transactions │ + └──────────────────────────┬───────────────────────────────┘ + ▼ + ┌──────────────────────────────────────────────────────────┐ + │ git-warp Causal History Runtime │ + │ Evaluates admission policies, applies target rules │ + └──────────────────────────────────────────────────────────┘ +``` + +### Path Separation: Cold vs. Hot + +We separate the cold compilation/registration path from the hot execution path. Routine agents do not compile fresh source for every action. They invoke pre-admitted law. + +```text +AUTHORING / REGISTRATION (Cold Path) +GraphQL Shape IR ─┐ +XYPH Lawpack ─────┼─> Edict Compiler -> Core IR -> git-warp Target IR +Edict Source ─────┤ -> Verifier Report +Target Profile ───┘ -> Contract Bundle + -> HOLMES Evidence + -> Participant Admission + │ (continuum.lane.lawful-autonomous/v1) + └> Operation Registry + +EXECUTION (Hot Path) +Agent / TUI / XYPH API + │ + │ { bundleDigest, typedInput, basis, capabilityRef, idempotencyKey } + ▼ +Pre-Admitted Operation Registry + │ + ▼ +git-warp Target Executor + │ + ▼ +Typed outcome + patch witness + admission receipt reference +``` + +--- + +## 2. Shift I: Planning Rules as Edict Intents (Governance Lawpacks) + +XYPH currently separates validation and mutation, sometimes repeating checks inside adapters. By moving the rule, read, guard, and write into a target-owned atomic application, we improve coherence. + +Domain rules live in `xyph.governance@1` as a **lawpack**, with an adapter to a generic `gitwarp.causal-graph@1` target. Lawpacks own typed constants, obstructions, operation profiles, budgets, semantic effects, and target adapters, preserving the rule: **XYPH owns product meaning; git-warp owns bedrock mechanics.** + +### Conceptual Sample Surgery + +Below is the updated conceptual Edict operation for claiming a Quest, correcting previous semantic errors: +* Respects the requirement that claiming requires `READY` status (not `BACKLOG`). +* Permits unassigned quests or existing self-assignments. +* Avoids introducing cycles (cycle prevention belongs to dependency mutation). +* Requires an explicit basis. +* Uses the normative grammar keyword `return` (not `reveal`). +* Delegates the budget to the governance lawpack instead of hardcoding it at the intent layer. +* Returns a minimal receipt rather than disclosing the entire updated entity. + +```graphql +package xyph.operations@1; + +use shape "schemas/planning.graphql" + digest "sha256:8f4c..." as shape; +use lawpack xyph.governance@1 + digest "sha256:d3e1..." as governance; +use target gitwarp.causal-graph@1 + digest "sha256:a7b8..." as warp; + +intent claimQuest(input: shape.ClaimQuestRequest) + returns shape.ClaimQuestReceipt + implements governance.claimQuest + basis input.basis + footprint <= governance.claimQuestFootprint + budget <= governance.claimQuestBudget +{ + let receipt = governance.quest.claim({ + questId: input.questId, + basis: input.basis, + grant: input.claimCapability + }) else { + missing => governance.QuestMissing, + invalidStatus(f) => governance.InvalidStatus(f), + alreadyAssigned(f) => governance.AlreadyAssigned(f), + staleGuard(f) => governance.StaleBasis(f) + }; + + return receipt; +} +``` + +*Note: The `xyph.governance` adapter—not the high-level intent—lowers `governance.quest.claim` into exact git-warp property operations and guards.* + +--- + +## 3. Shift II: The Bounded Autonomous Lane (Formerly "YOLO") + +We retain "YOLO (You Only Lawfully Operate)" as human-facing branding. However, canonical artifacts must use `continuum.lane.lawful-autonomous/v1` in all hash-significant coordinates. + +We split agent operations into two lanes: +1. **Lawful Execution**: Select a pre-compiled, admitted bundle, and supply inputs. Routine agents operate exclusively in this lane. +2. **Lawful Extension**: Propose new Edict source, compile it, verify it, certify it, and seek admission. + +### Containing Prompt Injection +Edict **contains the authority blast radius of prompt injection**. It does not solve or prevent prompt injection. If an agent is compromised by an injection: +* It cannot delete the repository or access external networks if its footprint and target profile forbid it. +* However, it *can* still perform unauthorized actions within its permitted aperture (e.g. spamming lawful claims, choosing adversarial inputs, or disclosing data it has legitimate authority to read). + +--- + +## 4. Shift III: Bounded TUI Readings + +XYPH's present `ObservationSession` already restricts reads and separates observation from mutation authority. Edict enhances this by offering compile-time proofs of: +* Provably bounded apertures. +* Verified zero logical writes (no logical side-effects). +* Explicit basis and read identity. +* Bounded execution cost and output size. +* Safe, deterministic cache keys. +* Target-directed optic selection and causal slicing. + +*Note: We do not promise "zero locks". The compiler guarantees logical read-only effects, not that the runtime implementation avoids internal mutexes.* + +--- + +## 5. Integration Mandates (MUST) + +1. **Build the git-warp Target Profile**: This is the primary integration project. We must define the target intrinsics, footprint and cost algebras, Target IR, named failures, verifier, sandbox identity, atomicity model, and conformance fixtures. +2. **Bind Identity to Capability Evidence**: We cannot rely on unauthenticated inputs like `input.agentId`. Reading an Agent node only proves a record exists. We must use a scoped `CapabilityRef`, where participant admission binds the claimant, quest scope, basis, bounds, revocation policy, and policy epoch. +3. **Resolve Claim Concurrency Semantics**: Under current `git-warp` behavior, two concurrent claims can commit locally and converge later via Last-Write-Wins (LWW). A synchronous `ClaimConflict` cannot detect an unseen concurrent claim without coordination. We must choose: + - *Coordination-free*: Operation returns `ClaimSubmitted`; later observation of the converged graph determines the winning claimant. + - *Exclusive claim*: Introduce sequenced admission, Compare-And-Swap (CAS), a lease authority, or another coordinating participant. +4. **Make Production Claims Conditional**: Describe the system in future-conditional terms (e.g. "will close the ambient-authority gap for migrated operations") rather than declaring that it currently eliminates FIDLAR across XYPH. +5. **Preserve Failure-Class Separation**: Keep expected domain failures (e.g. invalid quest state) distinct. Compiler failures, admission rejection, integrity faults, resource exhaustion, and internal runtime defects must be separate structured failure classes—not user-defined obstructions. + +--- + +## 6. Guidelines & Adjustments (SHOULD / COULD) + +### SHOULD +* **Bundle Registry**: Maintain a registry keyed by semantic digest, with human-readable aliases (e.g., `xyph.claimQuest@1`). +* **Explicit Inputs**: Require every execution request to include an explicit basis, capability receipt digest, and idempotency key. +* **Causal Provenance**: Replace ambient `Date.now()` and random IDs inside the lawful lane with causal coordinates, content-derived IDs, or participant-supplied provenance. +* **Shadow Mode**: Run Edict beside existing TypeScript services in shadow mode, comparing outcomes before making Edict authoritative. +* **Test Reuse**: Re-use existing XYPH concurrent-claim and state-transition tests as target-profile conformance fixtures. +* **Reading Cache Key**: Cache reads based on: `bundleDigest + basisDigest + inputDigest + observerDigest`. + +### COULD / COOL IDEAS™ +* **Law Nutrition Labels**: Display reads, writes, basis, budget, capability scope, obstruction vocabulary, and bundle digest in the TUI prior to execution. +* **Obstruction Strategies**: Annotate typed failures with recovery metadata (e.g. `retry-after-refresh`, `retry-with-backoff`, `requires-human`, or `terminal`). +* **Footprint-Aware Scheduling**: Run operations with proven-disjoint write footprints in parallel. +* **Law Diffs**: Show static analysis changes in PRs (e.g. "This revision adds one Quest read and widens output by 128 bytes"). +* **Historical Lawful Replay**: Reproduce an action against its original basis to verify deterministic outcomes. +* **Aperture Heat Maps**: Visualize graph regions that registered operations are permitted to touch. diff --git a/docs/topics/git-warp-evolution/README.md b/docs/topics/git-warp-evolution/README.md new file mode 100644 index 00000000..c0d79ffd --- /dev/null +++ b/docs/topics/git-warp-evolution/README.md @@ -0,0 +1,74 @@ +# Architectural Evolution: Aligning XYPH with Git-WARP Primitives + +> [!WARNING] +> **ROADMAP DOCUMENT — NOT PRESENT IMPLEMENTATION TRUTH** +> This document outlines the planned evolutionary direction for XYPH's integration with `git-warp`. The structural shifts proposed here (e.g. counterfactual strands, BTR-style scrolls, and target-specific optics) represent future design gravity, not present-tense implementation. + +This document outlines how XYPH's design and runtime must evolve to leverage the core holographic, optic, and causal history capabilities of `git-warp`. + +Currently, XYPH treats the planning graph as a traditional database, loading monolithic state snapshots. To scale to large codebases and enable decentralized, offline-first agent coordination, we must shift to target-specific optics, speculative strands, and verifiable boundaries. + +--- + +## 1. The Core Shifts + +![XYPH Evolution Shifts](../../diagrams/xyph-evolution-shifts.svg) + + +### Shift I: From Monolithic Materialization to Bounded Optics +* **The Problem**: Currently, `fetchSnapshot` loads the entire `GraphSnapshot` containing campaigns, quests, scrolls, and policies. As the graph grows to thousands of nodes, this causes high memory consumption and latency, especially during agent briefing loops. +* **The Vision**: We must transition to **Quest Optics**. An agent assigned to Quest `Q` does not need to see the entire graph. The agent only needs the **causal cone** `D(Q)` of the quest: + - Its ancestry (Intent, Parent Quest) + - Its immediate dependencies and blockers + - Its associated requirements, criteria, and policies +* **Implementation**: Define a specialized `QuestOptic` in XYPH that calls `git-warp`'s coordinate-optic APIs directly to pull only the required subgraph. + +### Shift II: Counterfactual Planning via Speculative Strands +* **The Problem**: Proposing new campaigns or tasks currently writes directly to the shared planning worldline, which can lead to planning clutter and merge conflicts when multiple agents propose different approaches. +* **The Vision**: Model planning proposals as **Strands** (counterfactual lanes). + - When an agent proposes a project roadmap or splits a Quest, it opens a private planning Strand. + - The agent can speculative-execute rules, verify dependencies, and simulate outcomes on this strand. + - Once the plan is finalized and approved (satisfying the approval gates), the strand is **braided** (merged) back into the shared worldline. + +### Shift III: Verifiable Verification Boundaries (Scrolls as BTRs/Wormholes) +* **The Problem**: A Completed Quest is recorded as a "Scroll" node in the graph, containing arbitrary metadata and signatures. Verifying a task requires downloading the entire repository and walking its history. +* **The Vision**: Elevate **Scrolls** to native **Boundary Transition Records (BTRs)**. + - A Scroll becomes a cryptographically signed envelope certifying a transition boundary from `Quest: UNRESOLVED` to `Quest: RESOLVED`. + - It specifies exact inputs (parent commits, task requirements) and outputs (code outputs, verification logs) and signs them. + - This allows a peer agent or human operator to verify that a Quest was lawfully resolved by reading only the Scroll itself (its holographic boundary), without materializing or downloading the full repository history. + +### Shift IV: P2P Agent Treaties (Continuum Integration) +* **The Problem**: XYPH currently relies on a centralized Git remote (`origin/main`) to sync agent states. +* **The Vision**: Use the **Continuum protocol** to support peer-to-peer agent collaboration. + - Independent agents working offline or on different machines can sync directly via Continuum. + - They exchange witnessed suffixes of their planning worldlines, build comparable slices locally, and lower them under the local admission laws. + - This removes the centralized Git server dependency and establishes a true trust-free peer network. + +--- + +## 2. Refactored Code Layout (Target Architecture) + +To support this evolution, the XYPH architecture will shift from a monolithic adapter to specialized ports: + +```text +src/ +├── domain/ +│ └── services/ +│ ├── QuestOpticService.ts # Bounded optic slicing for agent execution +│ ├── CounterfactualPlanning.ts # Speculative strand management +│ └── ScrollVerifier.ts # BTR-style cryptographic validation +└── ports/ + ├── QuestOpticPort.ts # Port for loading targeted causal cones + └── AgentTreatyPort.ts # Continuum integration for P2P sync +``` + +--- + +## 3. High-Priority Action Items + +1. **Phase 1: Optic-Based Briefing** + - Replace the full `GraphSnapshot` lookup in `AgentBriefingService` with a `QuestOptic` query to load only the task's causal cone. +2. **Phase 2: Cryptographic Scroll Seals** + - Align the `Scroll` model with `git-warp`'s `BTR` schema to ensure self-contained, verifiable execution boundaries. +3. **Phase 3: Strand-Based Triaging** + - Refactor the actuator's `inbox promote` and `claim` commands to work on speculative Strands rather than mutating the main worldline directly. diff --git a/test/unit/ReadmeOnboardingShape.test.ts b/test/unit/ReadmeOnboardingShape.test.ts index b386be4b..ecfbdba1 100644 --- a/test/unit/ReadmeOnboardingShape.test.ts +++ b/test/unit/ReadmeOnboardingShape.test.ts @@ -8,7 +8,7 @@ describe('README onboarding shape', () => { it('introduces Xyph with a quick-start section before documentation', () => { const sectionOrder = [ - '## Why Xyph?', + '## Why XYPH?', '## Quick Start', '## Documentation', ]; @@ -30,7 +30,11 @@ describe('README onboarding shape', () => { it('contains a truthful first-use flow', () => { expect(readme).toContain('npx tsx xyph-actuator.ts intent intent:setup'); - expect(readme).toContain('npx tsx xyph-actuator.ts quest task:docs-001'); + expect(readme).toContain('npx tsx xyph-actuator.ts quest task:setup-001'); expect(readme).toContain('--intent intent:setup'); }); + + it('does not contain absolute file:// URLs', () => { + expect(readme).not.toContain('file:///Users/'); + }); });