@githolon/dsl 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/codegen_dart.ts

@@ -612,6 +612,13 @@ function aggFieldSpec(
     }
     case "int":
       return { name, wireName, kind: field.kind, dartType: "int", optional };
+    // A PN-COUNTER reads as its net count and a POSITION as its order-key — the read model collapses
+    // them (kernel `observed_value`) to a scalar Int / Str, so codegen treats them AS `int` / `string`
+    // (the spec carries the NORMALIZED kind so every downstream reader path is unchanged).
+    case "counter":
+      return { name, wireName, kind: "int", dartType: "int", optional };
+    case "position":
+      return { name, wireName, kind: "string", dartType: valueClass ?? "String", optional, ...(valueClass !== undefined ? { valueClass } : {}) };
     case "bool":
       return { name, wireName, kind: field.kind, dartType: "bool", optional };
     case "enum": {
@@ -1195,6 +1202,8 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
         ? `() { final v = ${reader}; return v == null ? null : ${s.refIdClass}.fromRow(v); }()`
         : `${s.refIdClass}.fromRow(${reader})`;
     }
+    // `position` normalizes to `string`, `counter` to `int` in `aggFieldSpec` — unreachable here.
+    case "position":
     case "string":
       if (s.valueClass !== undefined) {
         const reader = opt
@@ -1217,6 +1226,7 @@ function parseField(s: AggFieldSpec, aggregate: string): string {
       // The projection decodes a bool field to a real JSON boolean — read it directly (no runtime
       // helper). Optional → nullable cast; required → a plain cast (absent ⇒ throws, like readInt).
       return opt ? `(data['${s.wireName}'] as bool?)` : `(data['${s.wireName}'] as bool)`;
+    case "counter":
     case "int":
       return opt
         ? `readIntOrNull(data, '${aggregate}', '${s.wireName}')`
@@ -1277,8 +1287,12 @@ function readModelDartType(s: AggFieldSpec): string {
       // leaf — the kernel `Value` is Str|Int only), so it is surfaced as the permissive
       // `Object?` (the read engine's decoded value as-is — never coerced/thrown).
       return isJsonObjectLeaf(s) ? "Map<String, Object?>" : "Object?";
+    // `position`/`counter` are normalized to `string`/`int` in `aggFieldSpec` (read-collapsed scalars),
+    // so these labels are unreachable at runtime — present for FieldKind exhaustiveness.
+    case "position":
     case "string":
       return s.valueClass ?? "String";
+    case "counter":
     case "int":
       return "int";
     case "bool":
@@ -1327,6 +1341,7 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
         ? `() { final v = ${reader}; return v == null ? null : ${s.refIdClass}.fromRow(v); }()`
         : `${s.refIdClass}.fromRow(${reader})`;
     }
+    case "position":
     case "string":
       if (s.valueClass !== undefined) {
         const reader = opt
@@ -1355,6 +1370,7 @@ function parseReadModelField(s: AggFieldSpec, aggregate: string): string {
         : `readJsonObject(data, '${aggregate}', '${s.wireName}')`;
     case "bool":
       return opt ? `(data['${s.wireName}'] as bool?)` : `(data['${s.wireName}'] as bool)`;
+    case "counter":
     case "int":
       return opt
         ? `readIntOrNull(data, '${aggregate}', '${s.wireName}')`

package/src/codegen_ts.ts

@@ -229,6 +229,12 @@ function tsTypeOfField(field: Field): string {
       return "string";
     case "int":
       return "number";
+    // STRUCTURAL CRDT scalars (read-collapsed): a counter reads as its net number, a position as its
+    // order-key string (kernel `observed_value` → the projection surfaces a plain scalar).
+    case "counter":
+      return "number";
+    case "position":
+      return "string";
     case "bool":
       return "boolean";
     case "enum":

package/src/directive.ts

@@ -53,11 +53,45 @@ export interface Directive<P = unknown> {
    * directive, and the OBJECT it is checked on. The ONE gate runs `engine.check(schema, object,
    * relation, principal)` over the pre-apply folded tuple store — refusing an author who does not
    * hold it (the side-door fix made real). `object` is SELF-RELATIVE by default (`"workspace:self"`,
-   * the governance convention); a payload-derived per-record object is the follow-on. DISTINCT from
-   * the legacy `requiresCapability` (RBAC) and `declaredRelations` (cross-workspace) axes. Emitted
-   * into the `nomosRelationGate` USD era key; enforced IFF the law also declares a relation schema.
+   * the governance convention). A PER-RECORD object (home_holons §6) is set via `objectFrom`: the gate
+   * then checks the relation on `<recordType>:<validated_payload[idField]>` — the specific record this
+   * directive writes, not the whole workspace (`record ⊂ object`; the engine is already object-generic).
+   * DISTINCT from the legacy `requiresCapability` (RBAC) and `declaredRelations` (cross-workspace) axes.
+   * Emitted into the `nomosRelationGate` USD era key; enforced IFF the law also declares a relation schema.
    */
-  readonly requiresRelationGate?: { readonly relation: string; readonly object: string };
+  readonly requiresRelationGate?: {
+    readonly relation: string;
+    readonly object: string;
+    /** PER-RECORD (§6): when set, the gate object is `<recordType>:<payload[idField]>` (the static
+     *  `object` is the fallback). `undefined` ⇒ the static object — era-ruled, byte-identical replay. */
+    readonly objectFrom?: { readonly recordType: string; readonly idField: string };
+  };
+  /**
+   * CROSS-CUSTODY ATTESTATION-AUTHORIZED (home_holons §3/§5). When `true`, this directive's authorization
+   * is a carried §3 SIGNED QUOTE (the asserter's pubkey + a signature over the edge), NOT an author block —
+   * so a key-less bailiff can deliver it host-free to an OFFLINE subject. Lowered into the
+   * `nomosAttestationGate` USD era key: the one gate then re-verifies the quote (bound to the home's warrant
+   * owner) AND pins the captured principal to the proven, unprivileged attestation key, and the signed-author
+   * doors exempt it. The directive's payload MUST carry the framework-convention fields the gate reads
+   * (`asserterWorkspace` / `object` / `relation` / `attestedAt` / `publicKey` / `signature` — the
+   * `recordShare` shape). FRAMEWORK-ONLY today (the home law's `recordShare`); a true E2E authority-free fact.
+   */
+  readonly attestationAuthorizedGate?: {
+    /** The singleton aggregate INSTANCE id whose field holds the home owner (e.g. `home-owner:self`). */
+    readonly ownerObject: string;
+    /** The field on that singleton holding the owner principal (e.g. `principal`). */
+    readonly ownerField: string;
+    /** The payload field names the §3 quote rides in — the law's declared wire shape (defaulted to the
+     *  framework `recordShare` convention by `.attestationAuthorized()`, so the kernel hardcodes none). */
+    readonly fields: {
+      readonly asserterWorkspace: string;
+      readonly object: string;
+      readonly relation: string;
+      readonly attestedAt: string;
+      readonly publicKey: string;
+      readonly signature: string;
+    };
+  };
   /**
    * The directive's DECLARED read boundary: the ref types its `plan` may READ (the
    * "IR for law boundaries" decision — the boundary is part of the domain identity).
@@ -135,7 +169,17 @@ export interface RequirableDirective<P> extends Directive<P> {
    * to the directive id) at the scope `scopeFrom(payload)` derives (defaults to root).
    * Returns a new `Directive` carrying `requiresCapability` + `scopeFrom`.
    */
-  requires(relation: string, opts?: { object?: string }): RequirableDirective<P>;
+  requires(
+    relation: string,
+    opts?: { object?: string; objectFrom?: { recordType: string; idField: string } },
+  ): RequirableDirective<P>;
+  /**
+   * Declare this directive ATTESTATION-AUTHORIZED (home_holons §3/§5): its authorization is a carried §3
+   * signed quote rather than an author block — lowered into the `nomosAttestationGate` era key so the one
+   * gate verifies the quote + pins the principal to the attestation key, and the bailiff delivers it
+   * host-free. Framework-only (the home law's `recordShare`). Returns a NEW requirable directive.
+   */
+  attestationAuthorized(owner: { ownerObject: string; ownerField: string }): RequirableDirective<P>;
   /**
    * Declare the directive's READ boundary. TWO argument kinds, one declaration site:
    *   * a STRING declares a ref TYPE its `plan` may read (the original boundary —
@@ -260,6 +304,19 @@ class DirectivePlanStep<Id extends string, P> {
   }
 }
 
+/**
+ * Build a PER-RECORD authz object template (home_holons §6) for `.requires(rel, { objectFrom })`. The
+ * gate then checks the relation on `<Agg>:<validated_payload[idField]>` — the specific record this
+ * directive writes (e.g. `recordObject(Entry, "entryId")` ⇒ `Entry:<payload.entryId>`), not the whole
+ * workspace. `record ⊂ object`: the same engine, pointed at one record.
+ */
+export function recordObject(
+  agg: AggregateHandle,
+  idField: string,
+): { recordType: string; idField: string } {
+  return { recordType: agg.id, idField };
+}
+
 /**
  * Wrap a `Directive` with the chainable `.requires(...)` declaration. `.requires`
  * is non-destructive: it returns a NEW requirable directive carrying the resolved
@@ -269,14 +326,46 @@ class DirectivePlanStep<Id extends string, P> {
 function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
   return {
     ...base,
-    requires(relation: string, opts?: { object?: string }): RequirableDirective<P> {
+    requires(
+      relation: string,
+      opts?: { object?: string; objectFrom?: { recordType: string; idField: string } },
+    ): RequirableDirective<P> {
       // THE ONE write-authz declaration (full-native Zanzibar, no mixed systems): the captured author
-      // must HOLD `relation` on `object` (self-relative `"workspace:self"` by default) for the one gate
-      // to admit. Lowers to the `nomosRelationGate` era key; `admit` runs `engine.check`. (Replaces the
-      // deleted RBAC capability axis — a capability WAS just a relation.)
+      // must HOLD `relation` on the object for the one gate to admit. Default object is self-relative
+      // (`"workspace:self"`, the governance convention); `objectFrom` (home_holons §6) gates on the
+      // PER-RECORD object the payload names (`recordObject(Agg, "idField")`) instead. Lowers to the
+      // `nomosRelationGate` era key; `admit` runs `engine.check`. (Replaces the deleted RBAC capability
+      // axis — a capability WAS just a relation.)
+      return makeRequirable({
+        ...base,
+        requiresRelationGate: {
+          relation,
+          object: opts?.object ?? "workspace:self",
+          ...(opts?.objectFrom !== undefined ? { objectFrom: opts.objectFrom } : {}),
+        },
+      });
+    },
+    attestationAuthorized(owner: { ownerObject: string; ownerField: string }): RequirableDirective<P> {
+      // CROSS-CUSTODY ATTESTATION-AUTHORIZED (home_holons §3/§5): this directive's authorization is a
+      // carried §3 signed quote, not an author block — lowered into the `nomosAttestationGate` era key, so
+      // the one gate verifies the quote (binding its subject to the LAW-DECLARED `owner`), pins the principal
+      // to the attestation key, and the signed-author doors exempt it. `owner` names the singleton + field
+      // holding the home owner; the QUOTE FIELD NAMES default to the framework `recordShare` convention HERE
+      // (in the DSL — the kernel reads them from the law's declaration, hardcoding nothing).
       return makeRequirable({
         ...base,
-        requiresRelationGate: { relation, object: opts?.object ?? "workspace:self" },
+        attestationAuthorizedGate: {
+          ownerObject: owner.ownerObject,
+          ownerField: owner.ownerField,
+          fields: {
+            asserterWorkspace: "asserterWorkspace",
+            object: "object",
+            relation: "relation",
+            attestedAt: "attestedAt",
+            publicKey: "publicKey",
+            signature: "signature",
+          },
+        },
       });
     },
     reads(...reads: (string | QueryDecl)[]): RequirableDirective<P> {

package/src/fields.ts

@@ -15,7 +15,7 @@
  * the value type (via Zod) is preserved.
  */
 import { z } from "zod";
-import { Conflict, Lww, type Driver } from "./drivers.js";
+import { Conflict, Counter, LastPosition, Lww, type Driver } from "./drivers.js";
 import type { AggregateHandle } from "./aggregate.js";
 
 export type FieldKind =
@@ -35,7 +35,14 @@ export type FieldKind =
   // evidence.md §6/§9.2 — a content-addressed EvidenceRef. The migration target of the
   // hand-wired `blobRef` `t.jsonObject()` string (thing_structures.ts). The authored
   // value is the typed EvidenceRef shape; it encodes to a kernel `Value::Evidence`.
-  | "evidence";
+  | "evidence"
+  // ── STRUCTURAL CRDT scalar kinds (the read-collapsible drivers) ──
+  // `t.counter()` — a PN-counter (`Driver::Counter`): driven by `increment`/`decrement`, read as the
+  // net `Int` (Σpos − Σneg). `t.position()` — an LWW order-key (`Driver::LastPosition`): driven by
+  // `set`, read as the `String` key. Both collapse to a scalar at read time (kernel `observed_value`),
+  // so the read model + codegen treat them as `number` / `string`.
+  | "counter"
+  | "position";
 
 /**
  * The authored shape of an `EvidenceRef` (`evidence.md` §1) — a content-addressed
@@ -224,6 +231,21 @@ export const t = {
   bool(): Field<boolean, "bool"> {
     return makeField("bool", z.boolean(), Lww);
   },
+  /** A PN-COUNTER (`Driver::Counter`) — a number that CONVERGES under concurrent edits: two replicas
+   *  that each `increment` while offline both land (the merge is the per-replica sum), so nobody's count
+   *  is lost. Drive it with `increment(handle, "field", n)` / `decrement(...)`, NOT `set()` (set would
+   *  clobber the convergent state). Reads back as the net `number` (Σincrements − Σdecrements; may be
+   *  negative). The kernel owns the CRDT; the field tag picks it. */
+  counter(): Field<number, "counter"> {
+    return makeField<number, "counter">("counter", z.number().int(), Counter);
+  },
+  /** An LWW ORDER-KEY POSITION (`Driver::LastPosition`) — an opaque fractional/index string (e.g. `"a0"`,
+   *  `"a0V"`) that orders an item among siblings, resolved last-writer-wins by HLC. Drive it with
+   *  `set(handle, "pos", key)`; concurrent moves converge to one position (the later HLC). Reads back as
+   *  the `string` key. (Compute the key client-side — fractional indexing — and ride it in the payload.) */
+  position(): Field<string, "position"> {
+    return makeField<string, "position">("position", z.string(), LastPosition);
+  },
   /** Enum via `as const` literal union — value typos squeal at compile time. */
   enum<const E extends readonly [string, ...string[]]>(values: E): Field<E[number], "enum"> {
     return makeField<E[number], "enum">(

package/src/framework/home.ts

@@ -0,0 +1,183 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * framework/home.ts — THE HOME HOLON (the identity role; `architecture/home_holons_and_cross_custody.md`
+ * §4). One holon, three roles — "workspace," "platform," "home" are the SAME githolon wearing the role
+ * its installed LAW gives it. A HOME holon runs THIS law: an identity's subject-side root.
+ *
+ * It holds only PUBLIC material + signed facts (private keys never leave the client, so the cloud hosting
+ * it stays operator-blind):
+ *  - KEY DIRECTORY — the identity's public device keys: the `signer` relation
+ *    (`identity:<principal>#signer@key:<hash>`, `framework/signing_identity.ts`). Re-exported here so a
+ *    home holon's law carries it: "wrap the scope key to U's device" becomes "read U's home key roster."
+ *  - SHARED-WITH-ME index (§5) — one record per verified cross-custody attestation delivered here, so
+ *    "show me everything shared with me" is a LOCAL query, no fan-out.
+ *  - INBOX — grants/invites/notifications/dead-letters addressed to the identity.
+ *
+ * THE FORWARD-CHECK DOCTRINE (§5): the index is a DISCOVERY HINT, not the authority. When the identity
+ * actually opens the asserting workspace, THAT workspace's gate does the live `Check` — so a stale share
+ * (the asserter revoked it) is fail-safe: the identity sees a workspace it can no longer open, the forward
+ * check denies, the hint is pruned. (The cross-custody ATTESTATION that proves a delivered share is signed
+ * + verifiable is §3; the host DELIVERY lane that fills the index is §5. This file is the law that holds
+ * the result, and the owner-authored lane to maintain it.)
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
+import { directive } from "../directive.js";
+import { create } from "../authoring.js";
+import { set, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
+import { workspaceInvariant, refAs } from "./workspace_invariant.js";
+import { identityRelations } from "./signing_identity.js";
+
+// `nomos.sha256` — the TRUSTLESS, pure hash computed IN the githolon (Rust sha2 bound in the sealed engine;
+// see deterministic-rquickjs). Available as a global to plans + invariant predicates (like `nomos.mint`); it
+// lets the home law re-derive `home-<hash(owner)>` itself, so the SQUAT invariant runs in-law on every peer.
+declare const nomos: { sha256(input: string): string };
+
+/** The KEY DIRECTORY is the `signer` relation — re-exported so a home holon's law composes it (the
+ *  identity's public device keys, enrolled via `enrollSigner`, checked by the gate). */
+export { identityRelations };
+
+/**
+ * THE HOME OWNER (home_holons §5 — the owner stamp). A home holon is born UNWARRANTED (the subject may
+ * never have logged in — a share can be delivered to a stranger's lazily-born home, before they hold any
+ * device key, so there is no signed-author regime yet). This singleton records WHO the home belongs to: the
+ * §3 cross-custody gate binds a delivered quote's subject to THIS principal (`executor::HOME_OWNER_ID`), so
+ * a quote signed for anyone else fails closed. Seeded ONCE at birth by the host (the control-plane
+ * `seedHomeOwner`, kept off the open session lane), so a tenant cannot forge ownership.
+ */
+export const HOME_OWNER_ID = "home-owner:self";
+/** A home holon's SELF-COMMITTED NAME prefix — `home-<sha256(subject)>` (the client's `homeNameOf` + the
+ *  squat invariant both derive it). The home's chain commits to its own routing name, so the bailiff can
+ *  bind the name to the CONTENT (custody) while the LAW guarantees the name hashes its owner. */
+export const HOME_NAME_PREFIX = "home-";
+export const HOME_NAME_HASH_LEN = 40;
+export const HomeOwner = aggregate("HomeOwner", {
+  /** The identity this home belongs to — the canonical `user:<uid>` subject the §3 gate binds quotes to. */
+  principal: t.string().merge(Lww),
+  /** THE HOME'S SELF-COMMITTED NAME (`home-<sha256(principal)>`) — the squat invariant asserts it hashes the
+   *  owner, so the chain's claimed name can ONLY be its rightful owner's slot (home_holons §5). */
+  homeName: t.string().merge(Lww),
+  /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
+  bornAt: t.string().merge(Lww),
+});
+
+/** The framework PRIMITIVE plan: stamp the home's owner + its self-committed name (singleton at the fixed id). */
+export function writeHomeOwner(p: { principal: string; homeName: string; bornAt: string }): PlannedOp[] {
+  const h = instance(HomeOwner, HOME_OWNER_ID);
+  return [set(h, "principal", p.principal), set(h, "homeName", p.homeName), set(h, "bornAt", p.bornAt)];
+}
+
+/**
+ * `seedHomeOwner` — the birth-door directive that stamps the home's owner + its self-committed `homeName` at
+ * the fixed singleton id. A CONTROL-PLANE write: the host authors it once at lazy birth; the open session
+ * lane structurally REFUSES it (by directive id). `.ensures` (a deterministic-keyed singleton). The `homeName`
+ * is caller-supplied but the {@link homeNameBindsOwner} invariant proves it `== home-<sha256(principal)>`,
+ * so a squatter cannot claim a name slot that doesn't hash to ITS own owner.
+ */
+export const seedHomeOwner = directive("seedHomeOwner")
+  .ensures(HomeOwner)
+  .payload(z.object({ principal: z.string().min(1), homeName: z.string().min(1), bornAt: z.string().min(1) }))
+  .plan((p) => writeHomeOwner(p));
+
+/**
+ * THE SQUAT INVARIANT (home_holons §5) — a home holon's self-committed `homeName` MUST be the hash of its
+ * owner: `homeName == home-<sha256(principal)>`. Declared by the home law, it EXECUTES at the one gate — and
+ * crucially at `verify_chain` (the bailiff's upload-birth): a squatter's chain (claiming `home-<hash(bob)>`
+ * but owned by `mallory`) FAILS the home law's OWN gate during adoption — refused IN THE GITHOLON, BY THE LAW,
+ * never by a host check. The host only routes the chain to the name it commits to (custody). `nomos.sha256`
+ * re-derives the hash in-law on every peer, so the verdict is identical everywhere.
+ */
+export const homeNameBindsOwner = workspaceInvariant("HomeNameBindsOwner")
+  .on("seedHomeOwner")
+  .reads(() => [refAs("owner", "HomeOwner", HOME_OWNER_ID)])
+  .assert(({ owner }) => {
+    const o = (owner ?? {}) as { principal?: string; homeName?: string };
+    const expected = HOME_NAME_PREFIX + nomos.sha256(String(o.principal ?? "")).slice(0, HOME_NAME_HASH_LEN);
+    return o.homeName === expected
+      ? { accept: true }
+      : { reject: "a home's name must hash its owner (home-<sha256(principal)>) — refusing a squatted home" };
+  });
+
+/**
+ * THE SHARED-WITH-ME INDEX (§5) — one record per cross-custody attestation delivered to this home holon:
+ * a signed edge `<asserterWorkspace> : <object> # <relation> @ this-identity`, indexed LOCALLY so the
+ * access list is a local query (no fan-out across every resource holon). A DISCOVERY HINT — the live authz
+ * stays the forward `Check` on the asserting holon when the identity opens it.
+ */
+export const SharedWithMe = aggregate("SharedWithMe", {
+  /** The holon that signed + delivered this edge — WHERE the live forward `Check` runs when opened. */
+  asserterWorkspace: t.string().merge(Lww),
+  /** The shared OBJECT — the whole workspace (`workspace:self`) or a specific record (`Entry:<id>`). */
+  object: t.string().merge(Lww),
+  /** The relation granted (`reader` / `editor` / a read cap). */
+  relation: t.string().merge(Lww),
+  /** The asserter's OWNER principal — whose key signed the attestation (verified at §3 admission). */
+  asserterPrincipal: t.string().merge(Lww),
+  /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
+  attestedAt: t.string().merge(Lww),
+  /** PRUNED (forward-check fail-safe): set when the live `Check` on the asserter denies — the hint is
+   *  dropped from the list but the audit row stays. `""` = live. */
+  prunedAt: t.string().merge(Lww),
+});
+
+/**
+ * `recordShare` — index a cross-custody share into the home holon's access list. AUTHORED on the home
+ * holon (the identity's own subject-side root). The payload carries the §3 CROSS-CUSTODY ATTESTATION — a
+ * SIGNED QUOTE: the asserter's device `publicKey` + a `signature` over the edge
+ * `<asserterWorkspace>:<object>#<relation>@<this-home-owner>`. The home holon's OWN gate verifies it
+ * (`executor::record_share_attestation_violation`, bound to the warrant owner), so the BAILIFF can deliver
+ * it HOST-FREE (the host carries bytes, vouches nothing — the gate vouches). The owner lane authors the
+ * SAME shape (the owner holds the quote the asserter gave it). The signature is a verification input, not
+ * stored — only the edge facts fold into the index. The live authority stays the forward `Check` on the
+ * asserter when the identity opens it (§5 fail-safe); a stale/forged quote can't enter the list at all.
+ */
+export const recordShare = directive("recordShare")
+  .creates(SharedWithMe)
+  .payload(
+    z.object({
+      asserterWorkspace: z.string().min(1),
+      object: z.string().min(1),
+      relation: z.string().min(1),
+      asserterPrincipal: z.string().min(1),
+      attestedAt: z.string().min(1),
+      /** The asserter's device PUBLIC KEY (base64) — what the §3 gate verifies the quote against. */
+      publicKey: z.string().min(1),
+      /** The asserter's SIGNATURE (base64) over the edge bytes, subject = this home's owner. */
+      signature: z.string().min(1),
+    }),
+  )
+  .plan((p) => {
+    create(SharedWithMe)
+      .set("asserterWorkspace", p.asserterWorkspace)
+      .set("object", p.object)
+      .set("relation", p.relation)
+      .set("asserterPrincipal", p.asserterPrincipal)
+      .set("attestedAt", p.attestedAt)
+      .set("prunedAt", "");
+    return [];
+  })
+  // CROSS-CUSTODY ATTESTATION-AUTHORIZED (§3/§5): the payload's signed quote IS the authorization (lowered
+  // into the `nomosAttestationGate` era key) — the one gate verifies it against the home's owner (the
+  // LAW-DECLARED owner-source below, NOT a kernel-hardcoded id) + pins the principal to the attestation key,
+  // so the bailiff delivers it host-free to an OFFLINE subject (no device key, no author block).
+  .attestationAuthorized({ ownerObject: HOME_OWNER_ID, ownerField: "principal" });
+
+/**
+ * `pruneShare` — fail-safe drop of a hint whose forward `Check` denied (the asserter revoked it). The row
+ * stays for audit; `prunedAt` removes it from the live list. (The forward check itself is the resource
+ * holon's job — this records the verdict locally.)
+ */
+export const pruneShare = directive("pruneShare")
+  .mutates(SharedWithMe)
+  .payload(z.object({ shareId: z.string().min(1), prunedAt: z.string().min(1) }))
+  .plan((p) => [set(instance(SharedWithMe, p.shareId), "prunedAt", p.prunedAt)]);
+
+/** "Show me everything <asserter> shared with me" — an indexed probe over the local access list. */
+export const sharedByWorkspace = query("sharedByWorkspace").key("asserterWorkspace").returns(SharedWithMe);

package/src/index.ts

@@ -51,6 +51,9 @@ export {
   set,
   addToSet,
   setEntry,
+  increment,
+  decrement,
+  removeFromSet,
   withMarker,
   strike,
   type PlannedOp,
@@ -58,7 +61,7 @@ export {
   type PlannedEventMarker,
   type StrikeOp,
 } from "./ops.js";
-export { directive, type Directive, type ReferentialMarker } from "./directive.js";
+export { directive, recordObject, type Directive, type ReferentialMarker } from "./directive.js";
 // FIRST-CLASS WORKSPACE TYPES (sharding §10 RATIFIED, slice 1) live on the SUBPATH
 // `@githolon/dsl/workspace-type` (`workspaceType("estate").root(Estate).hasMany(...)`),
 // NOT this runtime barrel — the barrel is bundled into EVERY tenant's engine lump, and
@@ -231,6 +234,21 @@ export {
   SIGNER_RELATION,
   enrollSigner,
 } from "./framework/signing_identity.js";
+// THE HOME HOLON (home_holons_and_cross_custody.md §4) — the identity-role law: the shared-with-me access
+// index + the owner lane to maintain it (the key directory is the `signer` relation above).
+export {
+  SharedWithMe,
+  recordShare,
+  pruneShare,
+  sharedByWorkspace,
+  HomeOwner,
+  HOME_OWNER_ID,
+  HOME_NAME_PREFIX,
+  HOME_NAME_HASH_LEN,
+  seedHomeOwner,
+  writeHomeOwner,
+  homeNameBindsOwner,
+} from "./framework/home.js";
 // THE GENESIS WARRANT (identity_keys.md step 0) — the in-history birth fact that lets
 // the gate's genesis clause admit a founding control-plane grant on a virgin chain.
 export {

package/src/ops.ts

@@ -37,7 +37,7 @@ export interface FieldOp {
    */
   readonly marker?: PlannedEventMarker;
   readonly field: string;
-  readonly kind: "set" | "addToSet" | "setEntry";
+  readonly kind: "set" | "addToSet" | "setEntry" | "increment" | "decrement" | "removeFromSet";
   readonly value?: unknown;
   readonly items?: readonly string[];
   readonly entryKey?: string;
@@ -147,6 +147,55 @@ export function addToSet<
   return { ...addressOf(agg), field, kind: "addToSet", items };
 }
 
+/**
+ * `increment(handle, "field", amount)` — add to a PN-COUNTER field (`t.counter()`). The ONLY way to
+ * advance a counter (set() would clobber the convergent CRDT state). Concurrent increments on different
+ * replicas all land (the merge sums the per-replica totals), so nobody's count is lost. `amount` is a
+ * non-negative integer; the field must be `kind:"counter"`. `decrement` is the symmetric subtract.
+ */
+function counterDelta<A extends Target, K extends CounterKey<A>>(
+  agg: A,
+  field: K,
+  amount: number,
+  kind: "increment" | "decrement",
+): FieldOp {
+  if (!Number.isInteger(amount) || amount < 0) {
+    throw new Error(`${kind}('${String(field)}', ${amount}): amount must be a non-negative integer.`);
+  }
+  return { ...addressOf(agg), field: field as string, kind, value: amount };
+}
+/** A counter field key — `kind:"counter"` only (an `int` is NOT a counter; that would not converge). */
+type CounterKey<A> = {
+  [P in keyof Fields<A>]: Fields<A>[P] extends { kind: "counter" } ? P : never;
+}[keyof Fields<A>] &
+  string;
+
+export function increment<A extends Target, K extends CounterKey<A>>(agg: A, field: K, amount = 1): FieldOp {
+  return counterDelta(agg, field, amount, "increment");
+}
+/** `decrement(handle, "field", amount)` — subtract from a PN-counter field. See {@link increment}. */
+export function decrement<A extends Target, K extends CounterKey<A>>(agg: A, field: K, amount = 1): FieldOp {
+  return counterDelta(agg, field, amount, "decrement");
+}
+
+/**
+ * `removeFromSet(handle, "field", items)` — tombstone items in a REMOVE-WINS set (`t.set(...).merge(
+ * RemoveWins)`). The remove permanently WINS over any concurrent or later add of the same element
+ * (2-phase-set semantics), so a concurrent add+remove converges to "removed". The additive partner is
+ * {@link addToSet}; on a RemoveWins field both are encoded to the kernel's 2-phase ops. (On a plain
+ * AddWins set there is no remove — that's the whole point of AddWins — so this targets set fields and
+ * the encoder refuses a non-RemoveWins set at compile output.)
+ */
+export function removeFromSet<
+  A extends Target,
+  K extends {
+    [P in keyof Fields<A>]: FieldValue<Fields<A>[P]> extends string[] ? P : never;
+  }[keyof Fields<A>] &
+    string,
+>(agg: A, field: K, items: readonly string[]): FieldOp {
+  return { ...addressOf(agg), field, kind: "removeFromSet", items };
+}
+
 /** Set one entry of a map field. The map's value type is checked. */
 export function setEntry<
   A extends Target,

package/src/usd.ts

@@ -221,6 +221,31 @@ export interface UsdLayer {
     readonly v: 1;
     readonly requires: Record<string, { readonly relation: string; readonly object: string }>;
   };
+  /**
+   * THE CROSS-CUSTODY ATTESTATION GATE (home_holons §3/§5). Present IFF ≥1 directive declares
+   * `.attestationAuthorized()`: the SORTED set of their ids. A directive named here is authorized by a
+   * carried §3 signed quote rather than an author block — the one gate verifies the quote (bound to the
+   * home's warrant owner) + pins the captured principal to the proven attestation key, and the signed-author
+   * doors exempt it. OMITTED for law with no such directive (the era rule — byte-identical hash).
+   */
+  readonly nomosAttestationGate?: {
+    readonly v: 1;
+    readonly directives: Record<
+      string,
+      {
+        readonly ownerObject: string;
+        readonly ownerField: string;
+        readonly fields: {
+          readonly asserterWorkspace: string;
+          readonly object: string;
+          readonly relation: string;
+          readonly attestedAt: string;
+          readonly publicKey: string;
+          readonly signature: string;
+        };
+      }
+    >;
+  };
   /**
    * STABLE IDENTIFIERS (#58 — names are labels, identity is minted). The layer's
    * domain/aggregate/field sids + label lineages, carried verbatim from the canonical
@@ -448,14 +473,48 @@ export function emitUsd(
       ]);
       // THE RELATION GATE (P4): directives declaring `.requiresRelation` → directiveId → {relation,
       // object}. SORTED keys; omit-when-empty (era rule — a relation-gate-free layer is byte-identical).
-      const relationGateReq: Record<string, { relation: string; object: string }> = {};
+      const relationGateReq: Record<
+        string,
+        { relation: string; object: string; objectFrom?: { recordType: string; idField: string } }
+      > = {};
       for (const d of [...l.module.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
         if (d.requiresRelationGate !== undefined) {
-          relationGateReq[d.id] = { relation: d.requiresRelationGate.relation, object: d.requiresRelationGate.object };
+          relationGateReq[d.id] = {
+            relation: d.requiresRelationGate.relation,
+            object: d.requiresRelationGate.object,
+            // PER-RECORD object (home_holons §6): carried through to the wasm gate; omitted when absent
+            // so a self-relative directive's USD is byte-identical (the era rule).
+            ...(d.requiresRelationGate.objectFrom !== undefined
+              ? { objectFrom: d.requiresRelationGate.objectFrom }
+              : {}),
+          };
         }
       }
       const nomosRelationGate =
         Object.keys(relationGateReq).length > 0 ? { v: 1 as const, requires: relationGateReq } : undefined;
+      // THE CROSS-CUSTODY ATTESTATION GATE (home_holons §3/§5): directives declaring `.attestationAuthorized()`
+      // → directiveId → its LAW-DECLARED owner-source {ownerObject, ownerField}. SORTED keys (byte-
+      // determinism). Omit-when-empty (era rule). The one gate verifies the carried §3 quote (binding its
+      // subject to the named owner) + pins the principal to the attestation key — the kernel hardcodes no id.
+      const attestationReq: Record<
+        string,
+        {
+          ownerObject: string;
+          ownerField: string;
+          fields: { asserterWorkspace: string; object: string; relation: string; attestedAt: string; publicKey: string; signature: string };
+        }
+      > = {};
+      for (const d of [...l.module.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+        if (d.attestationAuthorizedGate !== undefined) {
+          attestationReq[d.id] = {
+            ownerObject: d.attestationAuthorizedGate.ownerObject,
+            ownerField: d.attestationAuthorizedGate.ownerField,
+            fields: { ...d.attestationAuthorizedGate.fields },
+          };
+        }
+      }
+      const nomosAttestationGate =
+        Object.keys(attestationReq).length > 0 ? { v: 1 as const, directives: attestationReq } : undefined;
       // THE CAPTURED-READ GATE DECLARATION (#58): collected from the canonical
       // manifest's per-directive `capturedReads` (omit-when-empty — read-free law's
       // USD is byte-identical apart from the always-on stableIds key).
@@ -515,6 +574,7 @@ export function emitUsd(
           : {}),
         ...(nomosRelations !== undefined ? { nomosRelations } : {}),
         ...(nomosRelationGate !== undefined ? { nomosRelationGate } : {}),
+        ...(nomosAttestationGate !== undefined ? { nomosAttestationGate } : {}),
         ...(Object.keys(visAggregates).length > 0
           ? { nomosReadVisibility: { v: 1 as const, aggregates: visAggregates } }
           : {}),

package/src/usd_layers.ts

@@ -371,6 +371,9 @@ export function usdaLayerText(
     ...(layer.nomosRelationGate !== undefined
       ? [`        custom string nomos:relationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosRelationGate)))}`]
       : []),
+    ...(layer.nomosAttestationGate !== undefined
+      ? [`        custom string nomos:attestationGateHex = ${usdaString(hexUtf8(JSON.stringify(layer.nomosAttestationGate)))}`]
+      : []),
     ``,
     ...body,
     `    }`,
@@ -584,6 +587,22 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
         relationGate = { v: 1, requires: requiresRec };
       }
     }
+    // THE ATTESTATION GATE (home_holons §3/§5): directiveId → owner-source merged later-wins across layers,
+    // SORTED keys. Omit-when-empty (era rule).
+    let attestationGate: UsdLayer["nomosAttestationGate"];
+    {
+      type AttSrc = NonNullable<UsdLayer["nomosAttestationGate"]>["directives"][string];
+      const a = new Map<string, AttSrc>();
+      for (const l of stack) {
+        if (l.nomosAttestationGate === undefined) continue;
+        for (const [id, src] of Object.entries(l.nomosAttestationGate.directives)) a.set(id, src);
+      }
+      if (a.size > 0) {
+        const rec: Record<string, AttSrc> = {};
+        for (const k of [...a.keys()].sort()) rec[k] = a.get(k)!;
+        attestationGate = { v: 1, directives: rec };
+      }
+    }
     return {
       path,
       prims: [...prims.keys()].sort().map((p) => prims.get(p)!),
@@ -596,6 +615,7 @@ export function flattenLayeredUsd(layers: readonly UsdLayer[]): UsdDocument {
       ...(encryption !== undefined ? { nomosEncryption: encryption } : {}),
       ...(relations !== undefined ? { nomosRelations: relations } : {}),
       ...(relationGate !== undefined ? { nomosRelationGate: relationGate } : {}),
+      ...(attestationGate !== undefined ? { nomosAttestationGate: attestationGate } : {}),
     };
   });
 
@@ -719,6 +739,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
   const encryptionByDomain = new Map<string, UsdLayer["nomosEncryption"]>();
   const relationsByDomain = new Map<string, UsdLayer["nomosRelations"]>();
   const relationGateByDomain = new Map<string, UsdLayer["nomosRelationGate"]>();
+  const attestationGateByDomain = new Map<string, UsdLayer["nomosAttestationGate"]>();
   for (const p of prims) {
     if (p.attrs.get("nomos:kind") === "domain") {
       const domain = attrString(p, "nomos:domain");
@@ -752,6 +773,11 @@ export function parseUsdaDocument(text: string): UsdDocument {
       if (typeof relGateHex === "string") {
         relationGateByDomain.set(domain, JSON.parse(unhexUtf8(relGateHex)) as UsdLayer["nomosRelationGate"]);
       }
+      // THE ATTESTATION GATE (home_holons §3/§5): the hex-carried attestation-authorized directive set.
+      const attGateHex = p.attrs.get("nomos:attestationGateHex");
+      if (typeof attGateHex === "string") {
+        attestationGateByDomain.set(domain, JSON.parse(unhexUtf8(attGateHex)) as UsdLayer["nomosAttestationGate"]);
+      }
     }
   }
 
@@ -845,6 +871,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
       const enc = encryptionByDomain.get(domain);
       const rel = relationsByDomain.get(domain);
       const relGate = relationGateByDomain.get(domain);
+      const attGate = attestationGateByDomain.get(domain);
       return {
         path: `/Nomos/${domain}`,
         prims: [...b.prims].sort(byPath),
@@ -857,6 +884,7 @@ export function parseUsdaDocument(text: string): UsdDocument {
         ...(enc !== undefined ? { nomosEncryption: enc } : {}),
         ...(rel !== undefined ? { nomosRelations: rel } : {}),
         ...(relGate !== undefined ? { nomosRelationGate: relGate } : {}),
+        ...(attGate !== undefined ? { nomosAttestationGate: attGate } : {}),
       };
     })
     .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/src/wire.ts

@@ -39,7 +39,12 @@ export type WireValue =
   | { Int: number }
   | { Set: string[] }
   | { Map: Record<string, WireField> }
-  | { Evidence: WireEvidenceRef };
+  | { Evidence: WireEvidenceRef }
+  // ── STRUCTURAL CRDT state values (only seen when reading RAW folded state back; the read MODEL
+  //    collapses them via the kernel `observed_value` to Int/Str/Set, so typed reads stay scalar) ──
+  | { Counter: Record<string, { pos: number; neg: number }> }
+  | { Position: string }
+  | { TwoPhaseSet: { adds: string[]; removes: string[] } };
 
 /** `EvidenceRef { hash: ContentHash, media_type, byte_length, storage_class }` — the
  * kernel serde shape. `ContentHash(String)` serializes transparently as a bare string
@@ -57,11 +62,21 @@ export interface WireField {
   stamp: WireHlc;
 }
 
-/** `Op = Set(Value) | AddToSet(BTreeSet<String>) | SetEntry { key, value }`. */
+/**
+ * `Op` — the kernel's externally-tagged serde shape (`nomos2/kernel/src/lib.rs::Op`). The originals
+ * (Set / AddToSet / SetEntry) plus the STRUCTURAL CRDT ops: `AddToTwoPhase`/`RemoveFromTwoPhase`
+ * (the `removeWins` 2-phase set), `IncrementCounter`/`DecrementCounter` (the `counter` PN-counter,
+ * carrying a bare `u64` amount), and `SetPosition` (the `lastPosition` LWW order-key, a bare string).
+ */
 export type WireOp =
   | { Set: WireValue }
   | { AddToSet: string[] }
-  | { SetEntry: { key: string; value: WireValue } };
+  | { SetEntry: { key: string; value: WireValue } }
+  | { AddToTwoPhase: string[] }
+  | { RemoveFromTwoPhase: string[] }
+  | { IncrementCounter: number }
+  | { DecrementCounter: number }
+  | { SetPosition: string };
 
 /** `FieldOp { field: FieldId, op: Op }`. */
 export interface WireFieldOp {

package/src/wire_encode.ts

@@ -100,13 +100,39 @@ function encodeKernelValue(field: Field | undefined, value: unknown): WireValue
 }
 
 function encodeKernelFieldOp(op: FieldOp, field: Field | undefined): WireFieldOp {
+  // The field's DRIVER selects the kernel op for the structural CRDTs — a `set`/`addToSet` on a
+  // position / remove-wins field lowers to `SetPosition` / `AddToTwoPhase`, never the scalar/AddWins op.
+  const driver = field?.driver?.kind;
   let wireOp: WireOp;
   switch (op.kind) {
     case "set":
-      wireOp = { Set: encodeKernelValue(field, op.value) };
+      // A `lastPosition` field's `set` is the kernel `SetPosition` (LWW order-key, a bare string).
+      wireOp =
+        driver === "LastPosition"
+          ? { SetPosition: String(op.value) }
+          : { Set: encodeKernelValue(field, op.value) };
       break;
     case "addToSet":
-      wireOp = { AddToSet: [...(op.items ?? [])] };
+      // On a remove-wins set the add grows the 2-phase set's `adds`; on AddWins it is the plain union.
+      wireOp =
+        driver === "RemoveWins"
+          ? { AddToTwoPhase: [...(op.items ?? [])] }
+          : { AddToSet: [...(op.items ?? [])] };
+      break;
+    case "removeFromSet":
+      if (driver !== "RemoveWins") {
+        throw new Error(
+          `removeFromSet('${op.field}'): only a RemoveWins set has a remove (an AddWins set is ` +
+            `add-only by design). Declare the field \`t.set(...).merge(RemoveWins)\`.`,
+        );
+      }
+      wireOp = { RemoveFromTwoPhase: [...(op.items ?? [])] };
+      break;
+    case "increment":
+      wireOp = { IncrementCounter: Number(op.value) };
+      break;
+    case "decrement":
+      wireOp = { DecrementCounter: Number(op.value) };
       break;
     case "setEntry":
       wireOp = {