create-githolon 0.34.1 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-githolon",
-  "version": "0.34.1",
+  "version": "0.36.0",
   "type": "module",
   "description": "Scaffold a Nomos domain package: the starter domain + compile config + live e2e. `npm create githolon my-app`.",
   "license": "SEE LICENSE IN LICENSE.md",

package/template/docs/09-attested-reads.md

@@ -0,0 +1,87 @@
+# 09 — Attested cross-workspace reads (slice B)
+
+Your law can gate a write on a FACT IN ANOTHER WORKSPACE — without ever trusting the host,
+and without any peer opening the foreign chain at replay. The source's kernel SIGNS the
+answer; your law declares whose signature it trusts; every door (author, edge admission,
+`verify_chain` forever) re-verifies the signed envelope.
+
+## Declare the trust edge in law
+
+```ts
+import { z, directive, read, trustSource, foreignQuery } from "@githolon/dsl";
+
+const platformPolicy = foreignQuery("platformPolicy"); // the SOURCE's declared query, by id
+
+// module level — the trust boundary IS law (rides the domainHash):
+export const platformTrust = trustSource("co2-platform", {
+  genesis: "9d1c…",            // the source's genesis oid (its true identity — names are routing)
+  keyHashes: ["41aa…"],        // sha256 of the source's read-attestor public key(s)
+  maxAgeMs: 86_400_000,        // how stale an envelope may be vs the intent's own clock
+  minSourceEpoch: "birth",
+  monotone: true,              // refuse an answer older than one this chain already saw
+});
+
+export const enrollDevice = directive("enrollDevice")
+  .creates(HomeDevice)
+  .payload(z.object({ device: z.string() }))
+  .readsFrom("co2-platform", platformPolicy)   // the declared foreign read
+  .plan((p) => {
+    const rows = read(platformPolicy, { scope: "homes" }, { from: "co2-platform" });
+    if (rows[0]?.data?.enrollmentOpen !== "true") throw new Error("enrollment closed");
+    create(HomeDevice).set("device", p.device);
+    return [];
+  });
+```
+
+## Who fetches the evidence? THE AUTHOR — never the host
+
+The host never initiates a fetch (that would be orchestration — host-purge doctrine). Three
+lanes, in precedence order:
+
+1. **Carried** — the offer already contains `attestations: [{queryId, result, attestation}]`.
+   The gate judges the carried envelope; nothing ever replaces it.
+2. **Colocated (kernel-internal)** — when the source workspace is mounted in the SAME engine
+   instance (the container pool colocates workspaces), the engine plane serves + signs the
+   read in-kernel and injects it. Zero HTTP. The envelope is byte-identical to the HTTP lane —
+   colocation is invisible to the gate.
+3. **Client-carried (`?attest=1`)** — otherwise the CLIENT pre-fetches from the source's open
+   read lane and carries the envelope on the offer.
+
+## `@githolon/client` does the dance for you
+
+```ts
+const holon = await connect({ cloud, workspace, clientId,
+  attestedSources: { "co2-platform": "https://nomos.captainapp.co.uk" } }); // optional override
+await holon.dispatch("home", "enrollDevice", { device: "d-1" });
+// → the kernel refuses TYPED naming the missing read; the client fetches
+//   GET <sourceCloud>/v2/workspaces/co2-platform/platformPolicy?scope=homes&attest=1
+//   injects the signed envelope, retries — automatically.
+```
+
+**Offline:** if the source is unreachable, the offer FAILS with the named
+`attested-read-unreachable` error. There is NO stale fallback — a plan without its live
+premise cannot author. Retry when the source is reachable. You can also pre-fetch ahead of
+time (`holon.fetchAttestedRead(from, queryId, args)`) and pass
+`dispatch(..., { attestations: [entry] })`.
+
+## The two-step dance for THIN clients (raw HTTP, no SDK)
+
+1. `POST /v2/workspaces/<ws>/<directiveId>` with your payload. If the law declares foreign
+   reads and your body carries no matching attestation, you get **422** with:
+   `attested-read-unreachable: read('<queryId>', {from: '<source>'}) args={…} has no injected
+   attestation — pre-fetch it from the source's open read lane (?attest=1 …)`.
+2. `GET /v2/workspaces/<source>/<queryId>?<args>&attest=1` → `{ok, rows, attestation}` —
+   the source KERNEL signed it; the host relayed opaque bytes. Retry the POST with
+   `"attestations": [{"queryId": "<queryId>", "result": <rows>, "attestation": <attestation>}]`
+   in the body (it rides beside your payload fields, not inside them).
+
+No server fills this in for you — the refusal is the kernel INSTRUCTING you what evidence to
+carry. That is the design, not a limitation: the author carries the premise; every replayer
+verifies the signature forever, offline.
+
+## What the gate checks (every door, every peer, forever)
+
+declared edge ✓ → key hash ∈ your law's pins ∧ genesis matches ∧ signature verifies over the
+result ✓ → size bounds ✓ → freshness (`maxAgeMs` vs the intent's frozen clock, `minSourceEpoch`,
+the `monotone` frontier) ✓ → the plan re-runs with the replayed capture and byte-compares.
+A forged/tampered/stale/wrong-key envelope is a TYPED refusal. No peer ever contacts the source.