pi-outpost 0.7.0 → 0.9.0

package/dist/contract/README.md

@@ -0,0 +1,190 @@
+# Structured exchange — for producers
+
+A tool can return structured data alongside its text, and this application will render
+it natively: a graph, a sequence, or a table, drawn from the data rather than from
+anything the tool wrote for display. When the document names a target it is read as a
+*proposal* to change something an external authority holds, and its rendering becomes
+the approval gate before that change is applied.
+
+This page is for whoever writes such a producer. The normative contract is
+[`shared/schemas/structured-exchange-1.json`](../shared/schemas/structured-exchange-1.json).
+
+## The two payloads, and why you owe both
+
+A tool result carries two things, and they go to different readers:
+
+| Channel | Reaches | Carries |
+|---|---|---|
+| the result's text content | **the model** | what the agent will reason about later |
+| `details` | **the interface only** | the structured document |
+
+The SDK defines `details` as metadata the LLM does not see. That is what makes it the
+right home for a 500-element graph — the model pays nothing for it — and it is exactly
+why the text half is not optional.
+
+**A producer that emits only the structured document leaves the agent with nothing to
+reason about.** It will render beautifully and be useless on the next turn, when the
+agent is asked a follow-up question about a structure it cannot see. Summarise the
+structure in the text: what it contains, what changed, what matters.
+
+The reverse also holds: text alone gets you today's behaviour, a wall of prose.
+
+## Describing is not changing
+
+On anything carrying a `ref`, the fields you declare beside it **describe what the
+authority already holds**. They are how a reader recognises the thing. They are not
+applied. An intended change goes in `set`:
+
+```json
+{ "id": "ledger", "ref": "EL-7", "label": "Ledger",
+  "set": { "label": "General Ledger" } }
+```
+
+Two consequences worth stating plainly.
+
+**Include as much context as the reader needs.** Elements carried purely so the
+proposal can be situated cost nothing and change nothing. A proposal nobody can place
+is a proposal nobody should approve.
+
+**The default runs this way round because producers forget.** Were a declared field
+taken as an intended change, a producer including twenty elements for context would be
+proposing twenty renames to the names those elements already have — and the reader,
+seeing them marked as changes, could approve them. This way a forgotten `set` changes
+nothing and somebody says "it didn't work". A generative producer's mistakes have to
+fail inert.
+
+A `set` on something with no `ref` is refused: there is nothing there to change, and
+its fields are already its values.
+
+## Emitting a document
+
+Put the envelope in your tool result's `details`:
+
+```js
+return {
+  content: [{ type: "text", text: "Billing now calls Ledger. 12 elements, 1 added." }],
+  details: {
+    schema: "urn:structured-exchange:1",
+    kind: "graph",
+    data: {
+      nodes: [{ id: "billing", label: "Billing" }, { id: "ledger", label: "Ledger" }],
+      edges: [{ from: "billing", to: "ledger", kind: "calls" }],
+    },
+  },
+};
+```
+
+The server forwards anything whose `schema` starts with `urn:structured-exchange:`
+and validates nothing — validation happens where the rendering decision is made.
+
+## The agent as a producer
+
+The agent can author these too, guided by [`skills/structured-exchange`](../skills/structured-exchange/SKILL.md).
+It presents one through the `present_structure` tool, which validates before showing
+anything and hands back the diagnostics when it refuses, so a document can be corrected
+without leaving the exchange.
+
+## Validating before you emit
+
+```
+node contract/validate-structured-exchange.mjs document.json
+cat document.json | node contract/validate-structured-exchange.mjs
+```
+
+One file, no install, no checkout: the schema and the rules are inside it. In this
+repository, build it with `npm run build:validator` and find it at
+`shared/dist/validate-structured-exchange.mjs`.
+
+| Exit | Meaning |
+|------|---------|
+| `0` | the document conforms |
+| `1` | the document was read and parsed, and does not conform |
+| `2` | the input could not be read at all |
+| `3` | the input was read and is not JSON |
+
+The last three are separated on purpose. A missing file, a truncated write and a
+document that says the wrong thing send you looking in three different places, and a
+build that collapses them into "invalid" sends you to the schema for a problem that
+is not there.
+
+Diagnostics name the rule and point at the value:
+
+```json
+{"valid": false, "issues": [
+  {"rule": "unresolved-endpoint", "path": "/data/edges/0/to",
+   "message": "\"ledgr\" is not an identifier declared in /data/nodes"}
+]}
+```
+
+Every broken rule is reported, not just the first.
+
+## Getting a diagram into a document
+
+Use **download SVG**, then insert the file as a picture. Word does not accept an SVG
+pasted from the clipboard — it wants a file. **copy markup** is there for the places
+that do take it directly: an editor, a wiki, a repository.
+
+The markup stands on its own. Boxes are `rect` and `text` with colours as attributes
+and an explicit white ground, so what lands in the document is what was on screen. An
+earlier version drew them as HTML inside `foreignObject`, which looks identical in the
+browser and loses everything the moment it is serialized.
+
+## If you are not building in this repository
+
+You do not need our command-line interface, and you do not need this repository. The
+contract ships with the package, under `contract/`:
+
+```
+node_modules/pi-outpost/dist/contract/
+  schemas/structured-exchange-1.json    the normative schema — any validator runs it
+  conformance/                          documents and the verdict each should get
+  validate-structured-exchange.mjs      the reference validator, self-contained
+  README.md                             this page
+```
+
+- The **schema** is what the application validates against, byte for byte: it is the
+  same file, copied at build time rather than restated.
+- The **conformance suite** covers the relational rules JSON Schema cannot express.
+  Run your implementation against it; if it agrees on every case, it conforms.
+- The **validator** is the reference implementation of both, bundled with everything
+  it needs. Use it as a check on your own, or as the check itself.
+
+In this repository the same two live at `shared/schemas/` and `shared/conformance/`.
+
+## Where the document has to be put
+
+On `details` of a tool result. That is the whole channel, and it is deliberate:
+`details` is filled by a tool's implementation and never by the model, so a proposal
+shown as an approval gate was produced by code rather than written by the thing whose
+work is being reviewed.
+
+```js
+return {
+  content: [{ type: "text", text: "Billing now calls Ledger. 12 elements, 1 added." }],
+  details: envelope,
+};
+```
+
+**There is no MCP path.** The agent SDK underneath has no MCP client — it says so
+outright and points anyone who wants one at writing an extension. So if you are
+bridging a model-context server into this, the bridge is yours to write, and it meets
+this contract by returning the envelope in `details` of its own tool result. Nothing
+here reads MCP's `structuredContent`, because nothing in this process produces it.
+
+Relay it unchanged. A bridge that reshapes what it passes through is a second
+producer, and the reader would be approving its work rather than the original.
+
+## What is deliberately not here
+
+**Delivery.** How an approved proposal reaches the authority that applies it, and what
+that authority reports back, is a separate contract. What this one guarantees is that
+an approved proposal survives unaltered and can be recovered exactly as it was
+validated — the precondition any delivery mechanism needs.
+
+**Concurrency.** A document names *which* artifact it targets, not which revision. A
+proposal built from a stale export and applied late is the receiving authority's to
+detect; this contract does not carry what it would need to do so.
+
+**A vocabulary.** Relationship kinds are opaque strings. What `calls`, `composition`,
+or anything else means belongs to your domain, and enumerating it here would make a
+provider-neutral contract into somebody's particular one.

package/dist/contract/conformance/README.md

@@ -0,0 +1,54 @@
+# Structured-exchange conformance suite
+
+The executable half of the contract. `../schemas/structured-exchange-1.json` says what
+the shape is; these cases say what a correct implementation *does* with documents that
+sit on either side of the line — including the ones JSON Schema alone cannot judge.
+
+Any producer, in any language, can run this: the cases are plain JSON and
+`index.json` states the expected verdict for each. Nothing here depends on this
+repository, which is the point — a producer that has to read our TypeScript to know
+whether it conforms does not have a contract, it has a dependency.
+
+## Layout
+
+- `valid/` — documents a conforming implementation accepts.
+- `invalid/` — documents it refuses. `index.json` names the rule each one breaks.
+- `index.json` — the manifest, with `expectedRule` for every invalid case.
+
+## Rules that are not in the schema
+
+JSON Schema decides shape. These are the relational rules that follow it, and the
+`expectedRule` values that name them:
+
+| Rule | What it refuses |
+|---|---|
+| `duplicate-identifier` | two elements sharing an envelope-scoped `id` |
+| `unresolved-endpoint` | a relationship endpoint that no declared element carries |
+| `kind-data-mismatch` | a declared `kind` that disagrees with the data variant present |
+| `kind-not-proposable` | a `table` carrying a `target` or a `removal` |
+| `removal-without-target` | a removal in a document that targets nothing |
+| `duplicate-reference` | the same reference addressed twice — changed twice, or changed and removed |
+| `row-column-mismatch` | a row whose length differs from the declared columns |
+
+Rules prefixed `schema/` come from the JSON Schema itself; the suffix is the keyword
+that refused it.
+
+## Running it here
+
+```
+node --import tsx/esm shared/bin/validate-structured-exchange.mjs shared/conformance/valid/graph-minimal.json
+```
+
+Exits 0 for a valid document, 1 for a refused one, 2 when the input could not be read
+at all — which is not the same thing as invalid, and a producer's build should not
+treat it as if it were.
+
+## Two things a conforming implementation must not do
+
+**Repair.** No case here is close enough to valid to be worth guessing at, and that is
+deliberate: `unresolved-endpoint` names an endpoint one character from a declared
+identifier. Correcting it would produce a document the producer never wrote.
+
+**Report only the first problem.** A document breaking several rules is reported
+against all of them. A producer that has to fix one thing, be refused, fix the next,
+and be refused again is a producer that stops using the format.

package/dist/contract/conformance/index.json

@@ -0,0 +1,165 @@
+{
+  "valid": [
+    {
+      "file": "valid/graph-minimal.json"
+    },
+    {
+      "file": "valid/graph-with-typed-relationship.json"
+    },
+    {
+      "file": "valid/graph-proposal-addition-only.json"
+    },
+    {
+      "file": "valid/graph-proposal-field-patch.json"
+    },
+    {
+      "file": "valid/graph-proposal-context-element.json"
+    },
+    {
+      "file": "valid/graph-proposal-reattachment.json"
+    },
+    {
+      "file": "valid/sequence-minimal.json"
+    },
+    {
+      "file": "valid/sequence-ordered.json"
+    },
+    {
+      "file": "valid/table-minimal.json"
+    },
+    {
+      "file": "valid/graph-proposal-named-context.json"
+    },
+    {
+      "file": "valid/graph-proposal-declared-change.json"
+    },
+    {
+      "file": "valid/graph-at-the-kind-ceiling.json"
+    },
+    {
+      "file": "valid/graph-with-containers.json"
+    },
+    {
+      "file": "valid/sequence-with-containers.json"
+    },
+    {
+      "file": "valid/graph-with-empty-container.json"
+    },
+    {
+      "file": "valid/graph-proposal-moves-a-member.json"
+    },
+    {
+      "file": "valid/graph-containers-at-the-ceiling.json"
+    }
+  ],
+  "invalid": [
+    {
+      "file": "invalid/unknown-version.json",
+      "expectedRule": "schema/const"
+    },
+    {
+      "file": "invalid/undeclared-property.json",
+      "expectedRule": "schema/additionalProperties"
+    },
+    {
+      "file": "invalid/new-element-without-label.json",
+      "expectedRule": "schema/required"
+    },
+    {
+      "file": "invalid/new-relationship-without-kind.json",
+      "expectedRule": "schema/required"
+    },
+    {
+      "file": "invalid/relationship-without-endpoints.json",
+      "expectedRule": "schema/required"
+    },
+    {
+      "file": "invalid/removal-without-type.json",
+      "expectedRule": "schema/required"
+    },
+    {
+      "file": "invalid/duplicate-identifier.json",
+      "expectedRule": "duplicate-identifier"
+    },
+    {
+      "file": "invalid/unresolved-endpoint.json",
+      "expectedRule": "unresolved-endpoint"
+    },
+    {
+      "file": "invalid/kind-data-mismatch.json",
+      "expectedRule": "kind-data-mismatch"
+    },
+    {
+      "file": "invalid/table-with-target.json",
+      "expectedRule": "kind-not-proposable"
+    },
+    {
+      "file": "invalid/table-with-removal.json",
+      "expectedRule": "kind-not-proposable"
+    },
+    {
+      "file": "invalid/removal-without-target.json",
+      "expectedRule": "removal-without-target"
+    },
+    {
+      "file": "invalid/duplicate-reference.json",
+      "expectedRule": "duplicate-reference"
+    },
+    {
+      "file": "invalid/row-column-mismatch.json",
+      "expectedRule": "row-column-mismatch"
+    },
+    {
+      "file": "invalid/label-past-ceiling.json",
+      "expectedRule": "schema/maxLength"
+    },
+    {
+      "file": "invalid/change-without-reference.json",
+      "expectedRule": "change-without-reference"
+    },
+    {
+      "file": "invalid/empty-change.json",
+      "expectedRule": "schema/minProperties"
+    },
+    {
+      "file": "invalid/duplicate-reference-twice.json",
+      "expectedRule": "duplicate-reference"
+    },
+    {
+      "file": "invalid/change-without-target.json",
+      "expectedRule": "change-without-target"
+    },
+    {
+      "file": "invalid/relationship-change-without-target.json",
+      "expectedRule": "change-without-target"
+    },
+    {
+      "file": "invalid/table-with-empty-removals.json",
+      "expectedRule": "kind-not-proposable"
+    },
+    {
+      "file": "invalid/too-many-element-kinds.json",
+      "expectedRule": "too-many-kinds"
+    },
+    {
+      "file": "invalid/too-many-relationship-kinds.json",
+      "expectedRule": "too-many-kinds"
+    },
+    {
+      "file": "invalid/container-unknown-membership.json",
+      "expectedRule": "unresolved-container"
+    },
+    {
+      "file": "invalid/container-duplicate-id.json",
+      "expectedRule": "duplicate-container-identifier"
+    },
+    {
+      "file": "invalid/container-as-endpoint.json",
+      "expectedRule": "unresolved-endpoint"
+    },
+    {
+      "file": "invalid/containers-over-the-ceiling.json",
+      "expectedRule": "schema/maxItems"
+    }
+  ]
+}

package/dist/contract/conformance/invalid/change-without-reference.json

@@ -0,0 +1,17 @@
+{
+  "schema": "urn:structured-exchange:1",
+  "kind": "graph",
+  "target": "T",
+  "data": {
+    "nodes": [
+      {
+        "id": "a",
+        "label": "A",
+        "set": {
+          "label": "B"
+        }
+      }
+    ],
+    "edges": []
+  }
+}

package/dist/contract/conformance/invalid/change-without-target.json

@@ -0,0 +1,10 @@
+{
+  "schema": "urn:structured-exchange:1",
+  "kind": "graph",
+  "data": {
+    "nodes": [
+      { "id": "a", "ref": "EL-1", "label": "Old name", "set": { "label": "New name" } }
+    ],
+    "edges": []
+  }
+}

package/dist/contract/conformance/invalid/container-as-endpoint.json

@@ -0,0 +1,26 @@
+{
+  "schema": "urn:structured-exchange:1",
+  "kind": "graph",
+  "data": {
+    "containers": [
+      {
+        "id": "electrical",
+        "label": "Electrical system"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "battery",
+        "label": "Battery",
+        "container": "electrical"
+      }
+    ],
+    "edges": [
+      {
+        "from": "battery",
+        "to": "electrical",
+        "kind": "feeds"
+      }
+    ]
+  }
+}

package/dist/contract/conformance/invalid/container-duplicate-id.json

@@ -0,0 +1,24 @@
+{
+  "schema": "urn:structured-exchange:1",
+  "kind": "graph",
+  "data": {
+    "containers": [
+      {
+        "id": "electrical",
+        "label": "Electrical system"
+      },
+      {
+        "id": "electrical",
+        "label": "Electrical system again"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "battery",
+        "label": "Battery",
+        "container": "electrical"
+      }
+    ],
+    "edges": []
+  }
+}

package/dist/contract/conformance/invalid/container-unknown-membership.json

@@ -0,0 +1,20 @@
+{
+  "schema": "urn:structured-exchange:1",
+  "kind": "graph",
+  "data": {
+    "containers": [
+      {
+        "id": "electrical",
+        "label": "Electrical system"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "battery",
+        "label": "Battery",
+        "container": "hydraulic"
+      }
+    ],
+    "edges": []
+  }
+}