From c7f83514e2c19e4e225338d0fc9a7167c05f09a1 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 05:34:40 -0700 Subject: [PATCH 1/9] docs: add XYPH Git-WARP evolution and Edict integration design plans --- docs/xyph-edict-integration.md | 121 ++++++++++++++++++++++++++++++++ docs/xyph-git-warp-evolution.md | 82 ++++++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 docs/xyph-edict-integration.md create mode 100644 docs/xyph-git-warp-evolution.md diff --git a/docs/xyph-edict-integration.md b/docs/xyph-edict-integration.md new file mode 100644 index 00000000..19f2cc4d --- /dev/null +++ b/docs/xyph-edict-integration.md @@ -0,0 +1,121 @@ +# Edict Integration: Safe Optics & The YOLO Execution Model for XYPH + +This document outlines how **Edict**—the safe, statically verifiable programming language for Optics—integrates into XYPH to eliminate **FIDLAR** (ambient authority risk) and establish secure, verified agent execution. + +--- + +## 1. The Core Architecture + +Edict bridges the gap between GraphQL schema definitions and the underlying `git-warp` causal history runtime. + +```text + ┌──────────────────────────────────────────────────────────┐ + │ GraphQL Surface │ + │ Describes the types (Quest, Intent, Scroll, etc.) │ + └──────────────────────────┬───────────────────────────────┘ + ▼ + ┌──────────────────────────────────────────────────────────┐ + │ Edict Operations (Optics) │ + │ Defines what intents/readings are allowed to do │ + └──────────────────────────┬───────────────────────────────┘ + ▼ + ┌──────────────────────────────────────────────────────────┐ + │ Continuum Spine │ + │ Validates the contract bundle & checks credentials │ + └──────────────────────────┬───────────────────────────────┘ + ▼ + ┌──────────────────────────────────────────────────────────┐ + │ git-warp Causal History Runtime │ + │ Admits changes and executes sandboxed operations │ + └──────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. Shift I: Planning Rules as Edict Intents + +Currently, XYPH's graph-mutation constraints (e.g., verifying that claiming a Quest does not introduce cycles) are written in TypeScript inside services like `IntakeService.ts` or `SubmissionService.ts`. These services run with ambient system authority. + +### The Edict Approach +We must rewrite XYPH planning rules as **Edict Intents**. + +For example, the rules for claiming a Quest are defined in `xyph.governance@1`: + +```graphql +package xyph.governance@1; + +use shape "schemas/planning.graphql" as shape; +use target warp.dpo@1 digest "sha256:4d8..." as warp; + +intent claimQuest(input: shape.ClaimQuestInput) + returns shape.ClaimQuestReceipt | shape.ClaimQuestObstruction + profile warp.readWrite + budget <= shape.mediumBudget +{ + let questRef = warp.ref(input.questId); + let quest = questRef.read() else shape.ClaimQuestObstruction.QuestMissing; + + // Enforce state machine rules + require quest.status == "BACKLOG" + else shape.ClaimQuestObstruction.InvalidStatus { currentStatus: quest.status }; + + // Enforce assignment constraints + let agentRef = warp.ref(input.agentId); + let agent = agentRef.read() else shape.ClaimQuestObstruction.AgentMissing; + + // Write the claim edge + let updatedQuest = questRef.write({ + status: "IN_PROGRESS", + assignedTo: input.agentId + }) else { + conflict => shape.ClaimQuestObstruction.ClaimConflict + }; + + reveal updatedQuest; +} +``` + +### The Benefits +* **Static Footprint Verification**: The compiler proves that `claimQuest` *only* reads and writes the targeted `Quest` and `Agent` nodes and has no capability to delete campaigns or read secrets. +* **No Ambient Authority**: The operation cannot touch the network, access the local filesystem, or leak environment variables. + +--- + +## 3. Shift II: The YOLO Agent Execution Model + +Currently, XYPH agents run in **FIDLAR** mode: they run general TypeScript/JavaScript code, giving them ambient access to the host's files, processes, and credentials. + +### The YOLO Model in XYPH +We will implement the **YOLO (You Only Lawfully Operate)** execution lane for all autonomous agent actions: + +```mermaid +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 +``` + +### The Benefits +* **Isolate Prompt Injection**: If a malicious prompt injection instructs the agent to delete the codebase or download secrets, the compiled Edict program will fail static validation because the target footprint and network access are unauthorized. +* **Typed Failure Resolution**: Because all failures are returned as typed **Obstructions** rather than unhandled exceptions or arbitrary string errors, the agent can programmatically correct its inputs (e.g. basis refresh) and retry. + +--- + +## 4. Shift III: Zero-Side-Effect TUI Readings + +Currently, the TUI dashboard queries the graph using arbitrary queries that could potentially trigger unexpected mutations or state locks. + +### The Edict Approach +We will express TUI queries as **Edict Readings**: +* Every dashboard panel requests a reading governed by a read-only profile (`profile warp.readOnly`). +* Because the compiler guarantees that the reading has zero write effects, the runtime can optimize execution using **holographic slicing** (reconstructing only the needed causal cones) with zero risk of concurrent locks or state corruption. diff --git a/docs/xyph-git-warp-evolution.md b/docs/xyph-git-warp-evolution.md new file mode 100644 index 00000000..2091f61c --- /dev/null +++ b/docs/xyph-git-warp-evolution.md @@ -0,0 +1,82 @@ +# Architectural Evolution: Aligning XYPH with Git-WARP Primitives + +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 + +```mermaid +graph TD + A["Current: Monolithic Graph DB"] --> B["Future: Causal History & Optics"] + C["Full Graph Materialization"] --> D["Quest Optics (Targeted Cones)"] + E["Ad-hoc Planning Nodes"] --> F["Speculative Strands (Counterfactuals)"] + G["Ad-hoc Scroll Documents"] --> H["verifiable BTRs & Wormholes"] + I["Central Git Collaboration"] --> J["Continuum P2P Agent Treaty"] + + style B fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px + style D fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px + style F fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px + style H fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px + style J fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px +``` + +### 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. From 895d1f8a5f6e01c5c64241565e17a6393d8b602f Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 05:43:57 -0700 Subject: [PATCH 2/9] docs: extract inline mermaid blocks and replace with SVG links --- CONTRIBUTING.md | 18 +----------------- docs/diagrams/cycle-loop.svg | 2 +- docs/diagrams/docs-structure.mmd | 14 ++++++++++++++ docs/diagrams/docs-structure.mmd.sha256 | 1 + docs/diagrams/docs-structure.svg | 1 + docs/diagrams/milestone-lifecycle.svg | 2 +- docs/diagrams/orchestration-fsm.svg | 2 +- docs/diagrams/planning-pipeline.svg | 2 +- docs/diagrams/quest-status-lifecycle.svg | 2 +- docs/diagrams/task-lifecycle.svg | 2 +- docs/diagrams/teardown-cli-context.svg | 2 +- docs/diagrams/teardown-domain-entities.svg | 2 +- docs/diagrams/teardown-hexagonal-arch.svg | 2 +- docs/diagrams/teardown-jsonl-types.svg | 2 +- docs/diagrams/teardown-schema.svg | 2 +- .../diagrams/teardown-submission-lifecycle.svg | 2 +- docs/diagrams/vision-tenets.svg | 2 +- docs/diagrams/xyph-edict-sequence.mmd | 14 ++++++++++++++ docs/diagrams/xyph-edict-sequence.mmd.sha256 | 1 + docs/diagrams/xyph-edict-sequence.svg | 1 + docs/diagrams/xyph-evolution-shifts.mmd | 12 ++++++++++++ docs/diagrams/xyph-evolution-shifts.mmd.sha256 | 1 + docs/diagrams/xyph-evolution-shifts.svg | 1 + docs/xyph-edict-integration.md | 17 +---------------- docs/xyph-git-warp-evolution.md | 16 ++-------------- 25 files changed, 63 insertions(+), 60 deletions(-) create mode 100644 docs/diagrams/docs-structure.mmd create mode 100644 docs/diagrams/docs-structure.mmd.sha256 create mode 100644 docs/diagrams/docs-structure.svg create mode 100644 docs/diagrams/xyph-edict-sequence.mmd create mode 100644 docs/diagrams/xyph-edict-sequence.mmd.sha256 create mode 100644 docs/diagrams/xyph-edict-sequence.svg create mode 100644 docs/diagrams/xyph-evolution-shifts.mmd create mode 100644 docs/diagrams/xyph-evolution-shifts.mmd.sha256 create mode 100644 docs/diagrams/xyph-evolution-shifts.svg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8f66841d..f0e00d3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,23 +40,7 @@ current truth -> planned verification -> executable evidence -> historical reaso ## 3. Topic-Based Directory Structure Durable concepts that span multiple development cycles live in dedicated topic folders under `docs/topics//`. This forms a modular reference manual. - -```mermaid -graph TD - docs["docs/"] --> README["README.md (The Spine / Index)"] - docs --> BEARING["BEARING.md (Current Posture)"] - docs --> topics["topics/"] - - topics --> topicA["sovereign-ontology/"] - topics --> topicB["traceability/"] - - topicA --> readmeA["README.md (Current Invariants)"] - topicA --> planA["test-plan.md (Verification Contract)"] - topicA --> archA["architecture.md (Structural Map)"] - topicA --> ratA["rationale.md (Tradeoffs)"] - - docs --> design["design/cycles/ (Historical Cycle RFCs)"] -``` +![Topic Directory Structure](docs/diagrams/docs-structure.svg) ### Reference Map 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/docs-structure.mmd b/docs/diagrams/docs-structure.mmd new file mode 100644 index 00000000..1dd31360 --- /dev/null +++ b/docs/diagrams/docs-structure.mmd @@ -0,0 +1,14 @@ +graph TD + docs["docs/"] --> README["README.md (The Spine / Index)"] + docs --> BEARING["BEARING.md (Current Posture)"] + docs --> topics["topics/"] + + topics --> topicA["sovereign-ontology/"] + topics --> topicB["traceability/"] + + topicA --> readmeA["README.md (Current Invariants)"] + topicA --> planA["test-plan.md (Verification Contract)"] + topicA --> archA["architecture.md (Structural Map)"] + topicA --> ratA["rationale.md (Tradeoffs)"] + + docs --> design["design/cycles/ (Historical Cycle RFCs)"] diff --git a/docs/diagrams/docs-structure.mmd.sha256 b/docs/diagrams/docs-structure.mmd.sha256 new file mode 100644 index 00000000..3e912357 --- /dev/null +++ b/docs/diagrams/docs-structure.mmd.sha256 @@ -0,0 +1 @@ +f2325285dc6d01810ecf69ed96e262cdb78de453c175406b839b4e2ef4cff967 diff --git a/docs/diagrams/docs-structure.svg b/docs/diagrams/docs-structure.svg new file mode 100644 index 00000000..3d95f14b --- /dev/null +++ b/docs/diagrams/docs-structure.svg @@ -0,0 +1 @@ +

docs/

README.md (The Spine / Index)

BEARING.md (Current Posture)

topics/

sovereign-ontology/

traceability/

README.md (Current Invariants)

test-plan.md (Verification Contract)

architecture.md (Structural Map)

rationale.md (Tradeoffs)

design/cycles/ (Historical Cycle RFCs)

 \ 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..af630c86 --- /dev/null +++ b/docs/diagrams/xyph-evolution-shifts.mmd @@ -0,0 +1,12 @@ +graph TD + A["Current: Monolithic Graph DB"] --> B["Future: Causal History & Optics"] + C["Full Graph Materialization"] --> D["Quest Optics (Targeted Cones)"] + E["Ad-hoc Planning Nodes"] --> F["Speculative Strands (Counterfactuals)"] + G["Ad-hoc Scroll Documents"] --> H["verifiable BTRs & Wormholes"] + I["Central Git Collaboration"] --> J["Continuum P2P Agent Treaty"] + + style B fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px + style D fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px + style F fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px + style H fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px + style J fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px diff --git a/docs/diagrams/xyph-evolution-shifts.mmd.sha256 b/docs/diagrams/xyph-evolution-shifts.mmd.sha256 new file mode 100644 index 00000000..87f20142 --- /dev/null +++ b/docs/diagrams/xyph-evolution-shifts.mmd.sha256 @@ -0,0 +1 @@ +2046ba8213226a352f18ede19b115969ff0ebb54ba4cc673d4e2504a6f74e929 diff --git a/docs/diagrams/xyph-evolution-shifts.svg b/docs/diagrams/xyph-evolution-shifts.svg new file mode 100644 index 00000000..f532991b --- /dev/null +++ b/docs/diagrams/xyph-evolution-shifts.svg @@ -0,0 +1 @@ +

Current: Monolithic Graph DB

Future: Causal History & Optics

Full Graph Materialization

Quest Optics (Targeted Cones)

Ad-hoc Planning Nodes

Speculative Strands (Counterfactuals)

Ad-hoc Scroll Documents

verifiable BTRs & Wormholes

Central Git Collaboration

Continuum P2P Agent Treaty

 \ No newline at end of file diff --git a/docs/xyph-edict-integration.md b/docs/xyph-edict-integration.md index 19f2cc4d..dfd5911e 100644 --- a/docs/xyph-edict-integration.md +++ b/docs/xyph-edict-integration.md @@ -88,22 +88,7 @@ Currently, XYPH agents run in **FIDLAR** mode: they run general TypeScript/JavaS ### The YOLO Model in XYPH We will implement the **YOLO (You Only Lawfully Operate)** execution lane for all autonomous agent actions: -```mermaid -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 -``` +![Edict Integration Sequence](diagrams/xyph-edict-sequence.svg) ### The Benefits * **Isolate Prompt Injection**: If a malicious prompt injection instructs the agent to delete the codebase or download secrets, the compiled Edict program will fail static validation because the target footprint and network access are unauthorized. diff --git a/docs/xyph-git-warp-evolution.md b/docs/xyph-git-warp-evolution.md index 2091f61c..14e53df9 100644 --- a/docs/xyph-git-warp-evolution.md +++ b/docs/xyph-git-warp-evolution.md @@ -8,20 +8,8 @@ Currently, XYPH treats the planning graph as a traditional database, loading mon ## 1. The Core Shifts -```mermaid -graph TD - A["Current: Monolithic Graph DB"] --> B["Future: Causal History & Optics"] - C["Full Graph Materialization"] --> D["Quest Optics (Targeted Cones)"] - E["Ad-hoc Planning Nodes"] --> F["Speculative Strands (Counterfactuals)"] - G["Ad-hoc Scroll Documents"] --> H["verifiable BTRs & Wormholes"] - I["Central Git Collaboration"] --> J["Continuum P2P Agent Treaty"] - - style B fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px - style D fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px - style F fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px - style H fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px - style J fill:#1b3a4b,stroke:#00a8cc,stroke-width:2px -``` +![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. From a8095bf72cd11a805d22edf8c8e13155826c7d03 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 06:05:36 -0700 Subject: [PATCH 3/9] docs: enhance Edict integration design roadmap and align with target architecture critiques --- docs/xyph-edict-integration.md | 189 ++++++++++++++++++++++---------- docs/xyph-git-warp-evolution.md | 4 + 2 files changed, 136 insertions(+), 57 deletions(-) diff --git a/docs/xyph-edict-integration.md b/docs/xyph-edict-integration.md index dfd5911e..9343c9bd 100644 --- a/docs/xyph-edict-integration.md +++ b/docs/xyph-edict-integration.md @@ -1,106 +1,181 @@ -# Edict Integration: Safe Optics & The YOLO Execution Model for XYPH +# Edict Integration: Safe Optics & Bounded Execution Model for XYPH -This document outlines how **Edict**—the safe, statically verifiable programming language for Optics—integrates into XYPH to eliminate **FIDLAR** (ambient authority risk) and establish secure, verified agent execution. +> [!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 GraphQL schema definitions and the underlying `git-warp` causal history runtime. +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 ┌──────────────────────────────────────────────────────────┐ - │ GraphQL Surface │ - │ Describes the types (Quest, Intent, Scroll, etc.) │ + │ Surface Adapters (GraphQL / CLI / TUI) │ + │ Presents views and captures structured inputs │ └──────────────────────────┬───────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────┐ - │ Edict Operations (Optics) │ - │ Defines what intents/readings are allowed to do │ + │ Canonical JSONL Control Plane (XYPH) │ + │ Sovereign interface for reading & submitting commands │ └──────────────────────────┬───────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────┐ - │ Continuum Spine │ - │ Validates the contract bundle & checks credentials │ + │ Edict Operations (Optics) │ + │ Statically verified, capability-bound transactions │ └──────────────────────────┬───────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────┐ │ git-warp Causal History Runtime │ - │ Admits changes and executes sandboxed operations │ + │ Evaluates admission policies, applies target rules │ └──────────────────────────────────────────────────────────┘ ``` ---- +### Path Separation: Cold vs. Hot -## 2. Shift I: Planning Rules as Edict Intents +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. -Currently, XYPH's graph-mutation constraints (e.g., verifying that claiming a Quest does not introduce cycles) are written in TypeScript inside services like `IntakeService.ts` or `SubmissionService.ts`. These services run with ambient system authority. +```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 +``` -### The Edict Approach -We must rewrite XYPH planning rules as **Edict Intents**. +--- -For example, the rules for claiming a Quest are defined in `xyph.governance@1`: +## 2. Shift I: Planning Rules as Edict Intents (Governance Lawpacks) -```graphql -package xyph.governance@1; +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. -use shape "schemas/planning.graphql" as shape; -use target warp.dpo@1 digest "sha256:4d8..." as warp; +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.** -intent claimQuest(input: shape.ClaimQuestInput) - returns shape.ClaimQuestReceipt | shape.ClaimQuestObstruction - profile warp.readWrite - budget <= shape.mediumBudget -{ - let questRef = warp.ref(input.questId); - let quest = questRef.read() else shape.ClaimQuestObstruction.QuestMissing; +### Conceptual Sample Surgery - // Enforce state machine rules - require quest.status == "BACKLOG" - else shape.ClaimQuestObstruction.InvalidStatus { currentStatus: quest.status }; +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. - // Enforce assignment constraints - let agentRef = warp.ref(input.agentId); - let agent = agentRef.read() else shape.ClaimQuestObstruction.AgentMissing; - - // Write the claim edge - let updatedQuest = questRef.write({ - status: "IN_PROGRESS", - assignedTo: input.agentId +```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 { - conflict => shape.ClaimQuestObstruction.ClaimConflict + missing => governance.QuestMissing, + invalidStatus(f) => governance.InvalidStatus(f), + alreadyAssigned(f) => governance.AlreadyAssigned(f), + staleGuard(f) => governance.StaleBasis(f) }; - reveal updatedQuest; + return receipt; } ``` -### The Benefits -* **Static Footprint Verification**: The compiler proves that `claimQuest` *only* reads and writes the targeted `Quest` and `Agent` nodes and has no capability to delete campaigns or read secrets. -* **No Ambient Authority**: The operation cannot touch the network, access the local filesystem, or leak environment variables. +*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 YOLO Agent Execution Model +## 3. Shift II: The Bounded Autonomous Lane (Formerly "YOLO") -Currently, XYPH agents run in **FIDLAR** mode: they run general TypeScript/JavaScript code, giving them ambient access to the host's files, processes, and credentials. +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. -### The YOLO Model in XYPH -We will implement the **YOLO (You Only Lawfully Operate)** execution lane for all autonomous agent actions: +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. -![Edict Integration Sequence](diagrams/xyph-edict-sequence.svg) +### 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). + +--- -### The Benefits -* **Isolate Prompt Injection**: If a malicious prompt injection instructs the agent to delete the codebase or download secrets, the compiled Edict program will fail static validation because the target footprint and network access are unauthorized. -* **Typed Failure Resolution**: Because all failures are returned as typed **Obstructions** rather than unhandled exceptions or arbitrary string errors, the agent can programmatically correct its inputs (e.g. basis refresh) and retry. +## 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.* --- -## 4. Shift III: Zero-Side-Effect TUI Readings +## 5. Integration Mandates (MUST) -Currently, the TUI dashboard queries the graph using arbitrary queries that could potentially trigger unexpected mutations or state locks. +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. **Start with Graph-Only Operations**: Operations like `claim`, `shape`, and bounded readings are reasonable initial targets. Operations like `submit`, `seal`, and `merge` cross graph, Git workspace, filesystem, and keyring boundaries, requiring a composite target that explicitly owns coordination and atomicity. +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. **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. + +--- -### The Edict Approach -We will express TUI queries as **Edict Readings**: -* Every dashboard panel requests a reading governed by a read-only profile (`profile warp.readOnly`). -* Because the compiler guarantees that the reading has zero write effects, the runtime can optimize execution using **holographic slicing** (reconstructing only the needed causal cones) with zero risk of concurrent locks or state corruption. +## 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/xyph-git-warp-evolution.md b/docs/xyph-git-warp-evolution.md index 14e53df9..5b1e580c 100644 --- a/docs/xyph-git-warp-evolution.md +++ b/docs/xyph-git-warp-evolution.md @@ -1,5 +1,9 @@ # 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. From 761c715dd4f281c0494982892cabcdd551665c3a Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 09:09:24 -0700 Subject: [PATCH 4/9] docs: overhaul README to align with Continuum participant plans --- README.md | 111 +++++++++++++++++------- test/unit/ReadmeOnboardingShape.test.ts | 4 +- 2 files changed, 80 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 280d8090..56e446ed 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](file:///Users/james/git/xyph/GUIDE.md) — Orientation, Digital Guild nouns, and quick checklist. +2. **The Bedrock**: + * [ARCHITECTURE.md](file:///Users/james/git/xyph/docs/canonical/ARCHITECTURE.md) — Authoritative structural references (Hexagonal, Ports, WARP). + * [docs/VISION.md](file:///Users/james/git/xyph/docs/VISION.md) — Stigmergic tenets and the mission. + * [METHOD.md](file:///Users/james/git/xyph/docs/canonical/METHOD.md) — Work doctrine and cycle loops. +3. **The Direction**: + * [docs/BEARING.md](file:///Users/james/git/xyph/docs/BEARING.md) — Current release posture and strategic target. + * [docs/xyph-git-warp-evolution.md](file:///Users/james/git/xyph/docs/xyph-git-warp-evolution.md) — Optical query and speculative strand roadmap. + * [docs/xyph-edict-integration.md](file:///Users/james/git/xyph/docs/xyph-edict-integration.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/test/unit/ReadmeOnboardingShape.test.ts b/test/unit/ReadmeOnboardingShape.test.ts index b386be4b..2f25021b 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,7 @@ 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'); }); }); From e1c7d3aefdeedd6955e672d1a38dd42f9921e953 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 09:10:13 -0700 Subject: [PATCH 5/9] docs: add Edict integration and Git-WARP evolution roadmaps --- docs/xyph-edict-integration.md | 180 ++++++++++++++++++++++++++++++++ docs/xyph-git-warp-evolution.md | 74 +++++++++++++ 2 files changed, 254 insertions(+) create mode 100644 docs/xyph-edict-integration.md create mode 100644 docs/xyph-git-warp-evolution.md diff --git a/docs/xyph-edict-integration.md b/docs/xyph-edict-integration.md new file mode 100644 index 00000000..a905e88f --- /dev/null +++ b/docs/xyph-edict-integration.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/xyph-git-warp-evolution.md b/docs/xyph-git-warp-evolution.md new file mode 100644 index 00000000..5b1e580c --- /dev/null +++ b/docs/xyph-git-warp-evolution.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. From c87cf9129ac66cfdf06acb2c7f10a0655e2fe829 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 09:16:31 -0700 Subject: [PATCH 6/9] docs: add shift diagram for Git-WARP evolution --- docs/diagrams/xyph-evolution-shifts.mmd | 19 +++++++++++++++++++ .../diagrams/xyph-evolution-shifts.mmd.sha256 | 1 + docs/diagrams/xyph-evolution-shifts.svg | 1 + 3 files changed, 21 insertions(+) create mode 100644 docs/diagrams/xyph-evolution-shifts.mmd create mode 100644 docs/diagrams/xyph-evolution-shifts.mmd.sha256 create mode 100644 docs/diagrams/xyph-evolution-shifts.svg 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 From 065eff5fbc0fa1cdabd5ed05af1b86de98d20944 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 09:20:55 -0700 Subject: [PATCH 7/9] style: remove trailing whitespace in roadmaps and README --- README.md | 2 +- docs/xyph-edict-integration.md | 2 +- docs/xyph-git-warp-evolution.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 56e446ed..056ad186 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # XYPH -A sovereign agentic planning substrate and Edict execution runtime designed for the [Continuum](https://github.com/flyingrobots/continuum) post-Unix platform. +A sovereign agentic planning substrate and Edict execution runtime designed for the [Continuum](https://github.com/flyingrobots/continuum) post-Unix platform. 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. diff --git a/docs/xyph-edict-integration.md b/docs/xyph-edict-integration.md index a905e88f..f75267b2 100644 --- a/docs/xyph-edict-integration.md +++ b/docs/xyph-edict-integration.md @@ -10,7 +10,7 @@ This document outlines how **Edict**—the safe, statically verifiable programmi ## 1. The Core Architecture -Edict bridges the gap between schema definitions, governance lawpacks, and the underlying `git-warp` causal history runtime. +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. diff --git a/docs/xyph-git-warp-evolution.md b/docs/xyph-git-warp-evolution.md index 5b1e580c..4d3ab09a 100644 --- a/docs/xyph-git-warp-evolution.md +++ b/docs/xyph-git-warp-evolution.md @@ -4,7 +4,7 @@ > **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`. +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. From 52708a1065017b62f0418acae5a9eb4ca5dc215e Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 09:34:24 -0700 Subject: [PATCH 8/9] Fix: convert absolute file URLs in README.md to relative repository paths --- README.md | 14 +++++++------- test/unit/ReadmeOnboardingShape.test.ts | 4 ++++ 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 056ad186..9a545c7f 100644 --- a/README.md +++ b/README.md @@ -96,15 +96,15 @@ npm run tui To orient yourself, follow the authoritative manifests in order: 1. **The Entrance**: - * [GUIDE.md](file:///Users/james/git/xyph/GUIDE.md) — Orientation, Digital Guild nouns, and quick checklist. + * [GUIDE.md](./GUIDE.md) — Orientation, Digital Guild nouns, and quick checklist. 2. **The Bedrock**: - * [ARCHITECTURE.md](file:///Users/james/git/xyph/docs/canonical/ARCHITECTURE.md) — Authoritative structural references (Hexagonal, Ports, WARP). - * [docs/VISION.md](file:///Users/james/git/xyph/docs/VISION.md) — Stigmergic tenets and the mission. - * [METHOD.md](file:///Users/james/git/xyph/docs/canonical/METHOD.md) — Work doctrine and cycle loops. + * [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](file:///Users/james/git/xyph/docs/BEARING.md) — Current release posture and strategic target. - * [docs/xyph-git-warp-evolution.md](file:///Users/james/git/xyph/docs/xyph-git-warp-evolution.md) — Optical query and speculative strand roadmap. - * [docs/xyph-edict-integration.md](file:///Users/james/git/xyph/docs/xyph-edict-integration.md) — Sandbox boundaries and Edict target profiles. + * [docs/BEARING.md](./docs/BEARING.md) — Current release posture and strategic target. + * [docs/xyph-git-warp-evolution.md](./docs/xyph-git-warp-evolution.md) — Optical query and speculative strand roadmap. + * [docs/xyph-edict-integration.md](./docs/xyph-edict-integration.md) — Sandbox boundaries and Edict target profiles. --- diff --git a/test/unit/ReadmeOnboardingShape.test.ts b/test/unit/ReadmeOnboardingShape.test.ts index 2f25021b..ecfbdba1 100644 --- a/test/unit/ReadmeOnboardingShape.test.ts +++ b/test/unit/ReadmeOnboardingShape.test.ts @@ -33,4 +33,8 @@ describe('README onboarding shape', () => { 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/'); + }); }); From 4365ddfcf00de3c25403298b2d941afee66f0c7a Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 21 Jun 2026 09:39:27 -0700 Subject: [PATCH 9/9] docs: restructure roadmaps to conform to docs/topics/ protocol --- README.md | 4 ++-- .../edict-integration/README.md} | 0 .../git-warp-evolution/README.md} | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename docs/{xyph-edict-integration.md => topics/edict-integration/README.md} (100%) rename docs/{xyph-git-warp-evolution.md => topics/git-warp-evolution/README.md} (98%) diff --git a/README.md b/README.md index 9a545c7f..fc108b63 100644 --- a/README.md +++ b/README.md @@ -103,8 +103,8 @@ To orient yourself, follow the authoritative manifests in order: * [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/xyph-git-warp-evolution.md](./docs/xyph-git-warp-evolution.md) — Optical query and speculative strand roadmap. - * [docs/xyph-edict-integration.md](./docs/xyph-edict-integration.md) — Sandbox boundaries and Edict target profiles. + * [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. --- diff --git a/docs/xyph-edict-integration.md b/docs/topics/edict-integration/README.md similarity index 100% rename from docs/xyph-edict-integration.md rename to docs/topics/edict-integration/README.md diff --git a/docs/xyph-git-warp-evolution.md b/docs/topics/git-warp-evolution/README.md similarity index 98% rename from docs/xyph-git-warp-evolution.md rename to docs/topics/git-warp-evolution/README.md index 4d3ab09a..c0d79ffd 100644 --- a/docs/xyph-git-warp-evolution.md +++ b/docs/topics/git-warp-evolution/README.md @@ -12,7 +12,7 @@ Currently, XYPH treats the planning graph as a traditional database, loading mon ## 1. The Core Shifts -![XYPH Evolution Shifts](diagrams/xyph-evolution-shifts.svg) +![XYPH Evolution Shifts](../../diagrams/xyph-evolution-shifts.svg) ### Shift I: From Monolithic Materialization to Bounded Optics