@sentropic/h2a 0.96.0 → 0.96.2

package/dist/runtime/memory/promote-client.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Promote client — D11 double-consensus, CLIENT-SIDE orchestration (build brief
+ * slice 6, this build's WP11-slice-3). Two independent high-grade legs each
+ * write a VERDICT (third-party-readable, never self-report); this module
+ * enforces the double-consensus BEFORE `promoteNote` is ever called, and
+ * dispatches through an INJECTED `MemoryProducerPort` exactly like
+ * `admit-client.ts` does for admission.
+ *
+ * SCOPE (bounded): this is the client's consensus *enforcement* + evidence
+ * *assembly*. Launching the two model legs and interpreting/reading verdict
+ * FILES is out of scope here — a "leg" is an opaque `{model, session}` pair
+ * and a verdict ref is an opaque locator string, both supplied by the caller
+ * (the conductor orchestrating the legs). graphify's gate is the other half
+ * of this boundary: it re-checks structurally (refs + attestation shape), it
+ * never trusts this client's say-so either — this module's own refusal is a
+ * courtesy that saves a round trip, not the authority.
+ *
+ * REF, NOT INLINE: `independence_attestation` in `PromotionEvidence` is a
+ * LOCATOR string, exactly like `leg1_verdict_ref`/`leg2_verdict_ref` (§9.4).
+ * graphify's evidence holds the three refs; the attestation ARTIFACT (a file
+ * — see `./d11-ceremony.ts`, which writes it) holds the actual
+ * `IndependenceAttestation` content that ref points to. This module never
+ * serializes the attestation object itself into the evidence — the caller
+ * writes the artifact and hands `assemblePromotionEvidence` the ref it got
+ * back.
+ *
+ * I5 — fail-closed, TWO LAYERS:
+ *   1. `checkDoubleConsensusPreconditions` is a PURE, port-less function. It
+ *      cannot call the port even if it wanted to — a refusal here makes
+ *      "promoteNote never called" true BY CONSTRUCTION, not by a runtime
+ *      guard that could be bypassed or forgotten.
+ *   2. `promoteNote` (the raw dispatch) mirrors `admit-client.ts`: an absent
+ *      port, or one that throws/rejects, REFUSES — never a silent
+ *      `promoted: true` a caller might mistake for success.
+ * `promoteNoteWithDoubleConsensus` composes both layers for a caller that
+ * wants one call: check → assemble → dispatch, short-circuiting before the
+ * port is ever touched on any local refusal.
+ *
+ * STRUCTURAL independence, not merely attested: the guard computes leg
+ * distinctness and the author/session collision from the VERDICTS'
+ * own `leg` field, never from `attestation.distinctModels` /
+ * `attestation.distinctSessions` — those booleans are a self-report from the
+ * orchestrator and reach graphify only by reference (the attestation
+ * ARTIFACT, not this in-memory object — see the REF note above), but this
+ * client does not treat them as authoritative for its own local refusal. A
+ * lying attestation cannot paper over two identical verdict legs.
+ *
+ * I1 — durable identity slot: `leg.model`, `leg.session`, `authorId` and
+ * `noteId` are all OPAQUE strings here — compared with `===` only, never
+ * parsed, split or derived-from. This module reserves the slot; it does not
+ * mint or interpret conversation-scoped identity.
+ * I4 — no new capabilities vocabulary opens here; `MemoryVerdict` and
+ * `IndependenceAttestation` are D11-specific data shapes, not a second
+ * capabilities taxonomy, and `PromotionEvidence`/`PromotionOutcome` are
+ * reused unchanged from `./port-v1.ts`.
+ */
+import type { MemoryContext, MemoryProducerPort, PromotionEvidence, PromotionOutcome } from "./port-v1.js";
+/** An opaque leg identity — never parsed, only compared for equality. */
+export interface LegIdentity {
+    readonly model: string;
+    readonly session: string;
+}
+/**
+ * A single leg's verdict on a note. Written by the leg itself, to a
+ * third-party-readable file; the FILE (referenced elsewhere by an opaque
+ * `*Ref` string) is the record, not this in-memory shape — this type is how
+ * the client reasons about a verdict once the caller has already resolved
+ * one, not a re-implementation of reading the file.
+ */
+export interface MemoryVerdict {
+    readonly noteId: string;
+    readonly verdict: "GO" | "NO-GO";
+    readonly leg: LegIdentity;
+    readonly at: number;
+    readonly reason?: string;
+}
+/**
+ * The orchestrator's attestation that the two legs were actually independent.
+ * This is the CONTENT of the attestation artifact a ceremony writes (see
+ * `./d11-ceremony.ts`); `PromotionEvidence.independence_attestation` carries
+ * only that artifact's REF (locator string), never this object inline — see
+ * the module doc's REF note. This client does NOT treat
+ * `distinctModels`/`distinctSessions` here as authoritative for its own
+ * refusal; it recomputes distinctness from the verdicts.
+ */
+export interface IndependenceAttestation {
+    readonly leg1: LegIdentity;
+    readonly leg2: LegIdentity;
+    readonly distinctModels: boolean;
+    readonly distinctSessions: boolean;
+    readonly verdictsWrittenBeforeCrossVisibility: boolean;
+    readonly orchestrator: string;
+}
+/**
+ * Pack the two verdict-file references and the attestation REFERENCE into the
+ * port's `PromotionEvidence` shape. Pure: same inputs → same output, no I/O.
+ *
+ * `attestationRef` is a LOCATOR string, exactly like `leg1Ref`/`leg2Ref` — NOT
+ * the `IndependenceAttestation` object serialized inline. graphify's evidence
+ * holds the three refs; the attestation ARTIFACT (a file, written by whoever
+ * ran the ceremony — see `./d11-ceremony.ts`) holds the actual
+ * `{leg1,leg2,distinct*,...}` content that ref points to. Passed through
+ * unchanged — no `JSON.stringify` — because there is nothing to serialize
+ * here: the caller already resolved the ref by writing the artifact.
+ */
+export declare function assemblePromotionEvidence(leg1Ref: string, leg2Ref: string, attestationRef: string): PromotionEvidence;
+export type DoubleConsensusCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface DoubleConsensusInput {
+    readonly verdicts: readonly MemoryVerdict[];
+    readonly attestation: IndependenceAttestation;
+    readonly leg1Ref: string;
+    readonly leg2Ref: string;
+    /** The note's author (opaque id) — a leg's `session` must not equal this. */
+    readonly authorId: string;
+}
+/**
+ * REFUSES to let a caller proceed to `promoteNote` unless ALL hold:
+ *   - exactly 2 verdicts;
+ *   - BOTH verdicts are `"GO"` (any `"NO-GO"`, or a split, refuses);
+ *   - the two verdicts reference the SAME note (a mismatch refuses — two
+ *     verdicts for different notes cannot jointly promote either one);
+ *   - the two legs are STRUCTURALLY distinct — computed from `verdict.leg`
+ *     itself, not from the attestation's own booleans (not the same
+ *     model+session counted twice);
+ *   - `leg1Ref !== leg2Ref` (the same verdict-file reference cannot stand in
+ *     for both legs);
+ *   - neither leg's `session` equals `authorId` (separation of powers — a
+ *     leg cannot review its own note).
+ * This function takes no port: it cannot call `promoteNote` even if it
+ * wanted to, so its refusal holds by construction, not by convention.
+ */
+export declare function checkDoubleConsensusPreconditions(input: DoubleConsensusInput): DoubleConsensusCheck;
+export interface PromoteNoteResult {
+    readonly outcome: PromotionOutcome;
+    /** True when refused locally (no port, unreachable port, or a precondition) — the port was never called, or its call never resolved to a success. */
+    readonly localOnly: boolean;
+}
+/**
+ * Dispatch `evidence` through `port.promoteNote(noteId, evidence, ctx)`.
+ * `port` is injected and may be `undefined`/`null` (I5: fail-closed default,
+ * not a wiring error — mirrors `admit-client.ts`). This function does NOT
+ * itself enforce the double-consensus preconditions — that is
+ * `checkDoubleConsensusPreconditions`'s job, run BEFORE this is called (see
+ * `promoteNoteWithDoubleConsensus` for the composed entry point).
+ */
+export declare function promoteNote(noteId: string, evidence: PromotionEvidence, ctx: MemoryContext, port: MemoryProducerPort | undefined | null): Promise<PromoteNoteResult>;
+export interface PromoteNoteWithDoubleConsensusInput extends DoubleConsensusInput {
+    readonly noteId: string;
+    readonly ctx: MemoryContext;
+    /**
+     * The attestation ARTIFACT's locator — distinct from `attestation` (the
+     * in-memory object `checkDoubleConsensusPreconditions` uses for its own
+     * completeness gate, unchanged by this reconciliation). This is what
+     * actually travels to the port via `assemblePromotionEvidence`.
+     */
+    readonly attestationRef: string;
+}
+/**
+ * The client-side D11 promotion entry point: runs
+ * `checkDoubleConsensusPreconditions` first, and ONLY on `{ok: true}`
+ * assembles the evidence (`assemblePromotionEvidence`) and dispatches
+ * (`promoteNote`). A local refusal short-circuits BEFORE the port is ever
+ * touched — the composed call, not just the pure guard in isolation, is what
+ * a conductor actually invokes once both legs have written their verdicts.
+ */
+export declare function promoteNoteWithDoubleConsensus(input: PromoteNoteWithDoubleConsensusInput, port: MemoryProducerPort | undefined | null): Promise<PromoteNoteResult>;
+//# sourceMappingURL=promote-client.d.ts.map

package/dist/runtime/memory/promote-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote-client.d.ts","sourceRoot":"","sources":["../../../src/runtime/memory/promote-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAM3G,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,OAAO,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,oCAAoC,EAAE,OAAO,CAAC;IACvD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,GACrB,iBAAiB,CAMnB;AAMD,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAUD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,CAwCnG;AAMD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,qJAAqJ;IACrJ,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAMD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,iBAAiB,EAC3B,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,kBAAkB,GAAG,SAAS,GAAG,IAAI,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAY5B;AAMD,MAAM,WAAW,mCAAoC,SAAQ,oBAAoB;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,mCAAmC,EAC1C,IAAI,EAAE,kBAAkB,GAAG,SAAS,GAAG,IAAI,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAQ5B"}

package/dist/runtime/memory/promote-client.js

@@ -0,0 +1,168 @@
+/**
+ * Promote client — D11 double-consensus, CLIENT-SIDE orchestration (build brief
+ * slice 6, this build's WP11-slice-3). Two independent high-grade legs each
+ * write a VERDICT (third-party-readable, never self-report); this module
+ * enforces the double-consensus BEFORE `promoteNote` is ever called, and
+ * dispatches through an INJECTED `MemoryProducerPort` exactly like
+ * `admit-client.ts` does for admission.
+ *
+ * SCOPE (bounded): this is the client's consensus *enforcement* + evidence
+ * *assembly*. Launching the two model legs and interpreting/reading verdict
+ * FILES is out of scope here — a "leg" is an opaque `{model, session}` pair
+ * and a verdict ref is an opaque locator string, both supplied by the caller
+ * (the conductor orchestrating the legs). graphify's gate is the other half
+ * of this boundary: it re-checks structurally (refs + attestation shape), it
+ * never trusts this client's say-so either — this module's own refusal is a
+ * courtesy that saves a round trip, not the authority.
+ *
+ * REF, NOT INLINE: `independence_attestation` in `PromotionEvidence` is a
+ * LOCATOR string, exactly like `leg1_verdict_ref`/`leg2_verdict_ref` (§9.4).
+ * graphify's evidence holds the three refs; the attestation ARTIFACT (a file
+ * — see `./d11-ceremony.ts`, which writes it) holds the actual
+ * `IndependenceAttestation` content that ref points to. This module never
+ * serializes the attestation object itself into the evidence — the caller
+ * writes the artifact and hands `assemblePromotionEvidence` the ref it got
+ * back.
+ *
+ * I5 — fail-closed, TWO LAYERS:
+ *   1. `checkDoubleConsensusPreconditions` is a PURE, port-less function. It
+ *      cannot call the port even if it wanted to — a refusal here makes
+ *      "promoteNote never called" true BY CONSTRUCTION, not by a runtime
+ *      guard that could be bypassed or forgotten.
+ *   2. `promoteNote` (the raw dispatch) mirrors `admit-client.ts`: an absent
+ *      port, or one that throws/rejects, REFUSES — never a silent
+ *      `promoted: true` a caller might mistake for success.
+ * `promoteNoteWithDoubleConsensus` composes both layers for a caller that
+ * wants one call: check → assemble → dispatch, short-circuiting before the
+ * port is ever touched on any local refusal.
+ *
+ * STRUCTURAL independence, not merely attested: the guard computes leg
+ * distinctness and the author/session collision from the VERDICTS'
+ * own `leg` field, never from `attestation.distinctModels` /
+ * `attestation.distinctSessions` — those booleans are a self-report from the
+ * orchestrator and reach graphify only by reference (the attestation
+ * ARTIFACT, not this in-memory object — see the REF note above), but this
+ * client does not treat them as authoritative for its own local refusal. A
+ * lying attestation cannot paper over two identical verdict legs.
+ *
+ * I1 — durable identity slot: `leg.model`, `leg.session`, `authorId` and
+ * `noteId` are all OPAQUE strings here — compared with `===` only, never
+ * parsed, split or derived-from. This module reserves the slot; it does not
+ * mint or interpret conversation-scoped identity.
+ * I4 — no new capabilities vocabulary opens here; `MemoryVerdict` and
+ * `IndependenceAttestation` are D11-specific data shapes, not a second
+ * capabilities taxonomy, and `PromotionEvidence`/`PromotionOutcome` are
+ * reused unchanged from `./port-v1.ts`.
+ */
+// ---------------------------------------------------------------------------
+// assemblePromotionEvidence — pure, packs refs + attestation into the port's shape.
+// ---------------------------------------------------------------------------
+/**
+ * Pack the two verdict-file references and the attestation REFERENCE into the
+ * port's `PromotionEvidence` shape. Pure: same inputs → same output, no I/O.
+ *
+ * `attestationRef` is a LOCATOR string, exactly like `leg1Ref`/`leg2Ref` — NOT
+ * the `IndependenceAttestation` object serialized inline. graphify's evidence
+ * holds the three refs; the attestation ARTIFACT (a file, written by whoever
+ * ran the ceremony — see `./d11-ceremony.ts`) holds the actual
+ * `{leg1,leg2,distinct*,...}` content that ref points to. Passed through
+ * unchanged — no `JSON.stringify` — because there is nothing to serialize
+ * here: the caller already resolved the ref by writing the artifact.
+ */
+export function assemblePromotionEvidence(leg1Ref, leg2Ref, attestationRef) {
+    return {
+        leg1_verdict_ref: leg1Ref,
+        leg2_verdict_ref: leg2Ref,
+        independence_attestation: attestationRef
+    };
+}
+function refuseCheck(reason) {
+    return { ok: false, reason };
+}
+function sameLeg(a, b) {
+    return a.model === b.model && a.session === b.session;
+}
+/**
+ * REFUSES to let a caller proceed to `promoteNote` unless ALL hold:
+ *   - exactly 2 verdicts;
+ *   - BOTH verdicts are `"GO"` (any `"NO-GO"`, or a split, refuses);
+ *   - the two verdicts reference the SAME note (a mismatch refuses — two
+ *     verdicts for different notes cannot jointly promote either one);
+ *   - the two legs are STRUCTURALLY distinct — computed from `verdict.leg`
+ *     itself, not from the attestation's own booleans (not the same
+ *     model+session counted twice);
+ *   - `leg1Ref !== leg2Ref` (the same verdict-file reference cannot stand in
+ *     for both legs);
+ *   - neither leg's `session` equals `authorId` (separation of powers — a
+ *     leg cannot review its own note).
+ * This function takes no port: it cannot call `promoteNote` even if it
+ * wanted to, so its refusal holds by construction, not by convention.
+ */
+export function checkDoubleConsensusPreconditions(input) {
+    const { verdicts, attestation, leg1Ref, leg2Ref, authorId } = input;
+    if (!attestation) {
+        return refuseCheck("an independence attestation is required");
+    }
+    if (!Array.isArray(verdicts) || verdicts.length !== 2) {
+        const got = Array.isArray(verdicts) ? String(verdicts.length) : "a non-array";
+        return refuseCheck(`double consensus requires exactly 2 verdicts, got ${got}`);
+    }
+    const [v1, v2] = verdicts;
+    if (v1.verdict !== "GO" || v2.verdict !== "GO") {
+        return refuseCheck("double consensus requires BOTH legs to verdict GO — a NO-GO or a split refuses locally");
+    }
+    if (v1.noteId !== v2.noteId) {
+        return refuseCheck("the two verdicts reference different notes — refusing to conflate them");
+    }
+    if (sameLeg(v1.leg, v2.leg)) {
+        return refuseCheck("the two legs are not independent — the same model+session was counted twice (same leg twice)");
+    }
+    if (leg1Ref === leg2Ref) {
+        return refuseCheck("leg1Ref and leg2Ref are identical — refusing to accept one verdict reference twice");
+    }
+    if (v1.leg.session === authorId || v2.leg.session === authorId) {
+        return refuseCheck("a promoting leg's session equals the note's author — separation of powers requires an independent reviewer");
+    }
+    return { ok: true };
+}
+function refuseResult(reason) {
+    return { outcome: { promoted: false, reason }, localOnly: true };
+}
+/**
+ * Dispatch `evidence` through `port.promoteNote(noteId, evidence, ctx)`.
+ * `port` is injected and may be `undefined`/`null` (I5: fail-closed default,
+ * not a wiring error — mirrors `admit-client.ts`). This function does NOT
+ * itself enforce the double-consensus preconditions — that is
+ * `checkDoubleConsensusPreconditions`'s job, run BEFORE this is called (see
+ * `promoteNoteWithDoubleConsensus` for the composed entry point).
+ */
+export async function promoteNote(noteId, evidence, ctx, port) {
+    if (!port) {
+        return refuseResult("no memory producer port injected — refusing (fail-closed, I5)");
+    }
+    try {
+        const outcome = await port.promoteNote(noteId, evidence, ctx);
+        return { outcome, localOnly: false };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return refuseResult(`memory producer port unreachable: ${reason}`);
+    }
+}
+/**
+ * The client-side D11 promotion entry point: runs
+ * `checkDoubleConsensusPreconditions` first, and ONLY on `{ok: true}`
+ * assembles the evidence (`assemblePromotionEvidence`) and dispatches
+ * (`promoteNote`). A local refusal short-circuits BEFORE the port is ever
+ * touched — the composed call, not just the pure guard in isolation, is what
+ * a conductor actually invokes once both legs have written their verdicts.
+ */
+export async function promoteNoteWithDoubleConsensus(input, port) {
+    const check = checkDoubleConsensusPreconditions(input);
+    if (!check.ok) {
+        return refuseResult(`double-consensus preconditions not met: ${check.reason}`);
+    }
+    const evidence = assemblePromotionEvidence(input.leg1Ref, input.leg2Ref, input.attestationRef);
+    return promoteNote(input.noteId, evidence, input.ctx, port);
+}
+//# sourceMappingURL=promote-client.js.map

package/dist/runtime/memory/promote-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote-client.js","sourceRoot":"","sources":["../../../src/runtime/memory/promote-client.ts"],"names":[],"mappings":"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"}

package/dist/runtime/memory/recall-client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Recall client — WP11 slice 5 (build brief), read-side (wake-recall). Consumes
+ * an INJECTED `MemoryRecallPort` and returns the notes for the wake path. This
+ * slice stubs the port in tests; it never wires to real storage/graphify and is
+ * NOT wired into the actual wake/CLI path — the real recall factory awaits
+ * graphify's storage-laying Vague B (out of scope here, same boundary as
+ * `admit-client.ts`'s producer side).
+ *
+ * READ-SIDE GUARANTEES ENFORCED HERE, AS A CONSUMER (not just assumed from the
+ * port's types — the port is an external boundary, so this module re-checks the
+ * shape of what it gets back):
+ *  - `projection: "notes-only"` — this module exposes the notes as a FLAT LIST
+ *    and offers no helper that aggregates `subject: "human:<id>"` notes into a
+ *    profile. `groupAgentWorkNotesBySubject` below is the ONE grouping helper
+ *    this module offers, and it EXCLUDES human-subject notes from the grouping
+ *    by construction (counts them, never groups them) — so a UserModel cannot
+ *    be assembled by composing this consumer's exports. A port that returns a
+ *    different projection value is refused locally too: a misbehaving or
+ *    incorrectly-stubbed port must not silently smuggle a different shape past
+ *    the consumer boundary (the projection prohibition, §3.3.3, holds even if
+ *    the far side does not enforce it correctly).
+ *  - `freshness` and each note's `trust`/`review_status`/`provenance` are
+ *    passed through VERBATIM — never stripped, never re-labeled as verified.
+ *  - I5 fail-closed: an absent port, or one that throws/rejects, REFUSES —
+ *    never a silent `notes: []` that reads as "no memories exist". A refusal
+ *    is a structurally distinct shape (`refused: true` + `reason`, `notes: []`)
+ *    from a genuine empty recall (`refused: false, notes: []`), so a caller
+ *    cannot conflate "asked and got nothing" with "could not ask".
+ *  - I1: `ctx.principal_owner` travels through opaque and unexamined — this
+ *    module never derives, parses or keys on it (same reservation as
+ *    `note-builder.ts`).
+ *  - I4: no new capabilities/taxonomy vocabulary opens here — the
+ *    human-subject predicate is REUSED from `note-builder.ts`
+ *    (`isHumanMemorySubject`), never redefined.
+ */
+import type { MemoryContext, MemoryRecallPort, MemoryRecallQuery, MemoryRecallResultView, RecalledMemoryNoteView } from "./port-v1.js";
+export interface RecallMemorySuccess {
+    readonly refused: false;
+    readonly notes: readonly RecalledMemoryNoteView[];
+    readonly freshness: MemoryRecallResultView["freshness"];
+    readonly projection: MemoryRecallResultView["projection"];
+    readonly requestingPrincipal: string;
+    readonly unpaged: true;
+}
+export interface RecallMemoryRefusal {
+    readonly refused: true;
+    readonly reason: string;
+    /** Always empty on a refusal — never conflate with a genuine empty recall. */
+    readonly notes: readonly [];
+}
+export type RecallMemoryOutcome = RecallMemorySuccess | RecallMemoryRefusal;
+/**
+ * Dispatch `query` through `port.recallMemory(query, ctx)` for the wake path.
+ * `port` is injected and may be `undefined`/`null` (I5: fail-closed default,
+ * not a wiring error — the real recall factory does not exist yet).
+ */
+export declare function recallMemory(query: MemoryRecallQuery, ctx: MemoryContext, port: MemoryRecallPort | undefined | null): Promise<RecallMemoryOutcome>;
+export interface NotesGroupedBySubject {
+    /** Grouped ONLY for non-human subjects (e.g. `"agent-work"`). */
+    readonly grouped: Readonly<Record<string, readonly RecalledMemoryNoteView[]>>;
+    /** Count of human-subject notes excluded from the grouping — never aggregated. */
+    readonly excludedHumanSubjectCount: number;
+}
+/**
+ * The ONE grouping/summary helper this consumer offers, and it deliberately
+ * cannot be used to assemble a human-subject profile: any `human:<id>`
+ * subject note is EXCLUDED from the grouping (counted, never aggregated).
+ * Only non-human subjects (e.g. `"agent-work"`) are grouped. This mirrors the
+ * projection prohibition (§3.3.3) at the consumer boundary, so the
+ * prohibition holds even if a caller composes only this module's own exports
+ * — there is no way to reach a `Record<humanSubject, notes[]>` through it.
+ */
+export declare function groupAgentWorkNotesBySubject(notes: readonly RecalledMemoryNoteView[]): NotesGroupedBySubject;
+//# sourceMappingURL=recall-client.d.ts.map

package/dist/runtime/memory/recall-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-client.d.ts","sourceRoot":"","sources":["../../../src/runtime/memory/recall-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC,YAAY,CAAC,CAAC;IAC1D,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC;CAC7B;AAED,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAM5E;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI,GACxC,OAAO,CAAC,mBAAmB,CAAC,CA2B9B;AAED,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,CAAC,CAAC;IAC9E,kFAAkF;IAClF,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,SAAS,sBAAsB,EAAE,GACvC,qBAAqB,CAcvB"}

package/dist/runtime/memory/recall-client.js

@@ -0,0 +1,91 @@
+/**
+ * Recall client — WP11 slice 5 (build brief), read-side (wake-recall). Consumes
+ * an INJECTED `MemoryRecallPort` and returns the notes for the wake path. This
+ * slice stubs the port in tests; it never wires to real storage/graphify and is
+ * NOT wired into the actual wake/CLI path — the real recall factory awaits
+ * graphify's storage-laying Vague B (out of scope here, same boundary as
+ * `admit-client.ts`'s producer side).
+ *
+ * READ-SIDE GUARANTEES ENFORCED HERE, AS A CONSUMER (not just assumed from the
+ * port's types — the port is an external boundary, so this module re-checks the
+ * shape of what it gets back):
+ *  - `projection: "notes-only"` — this module exposes the notes as a FLAT LIST
+ *    and offers no helper that aggregates `subject: "human:<id>"` notes into a
+ *    profile. `groupAgentWorkNotesBySubject` below is the ONE grouping helper
+ *    this module offers, and it EXCLUDES human-subject notes from the grouping
+ *    by construction (counts them, never groups them) — so a UserModel cannot
+ *    be assembled by composing this consumer's exports. A port that returns a
+ *    different projection value is refused locally too: a misbehaving or
+ *    incorrectly-stubbed port must not silently smuggle a different shape past
+ *    the consumer boundary (the projection prohibition, §3.3.3, holds even if
+ *    the far side does not enforce it correctly).
+ *  - `freshness` and each note's `trust`/`review_status`/`provenance` are
+ *    passed through VERBATIM — never stripped, never re-labeled as verified.
+ *  - I5 fail-closed: an absent port, or one that throws/rejects, REFUSES —
+ *    never a silent `notes: []` that reads as "no memories exist". A refusal
+ *    is a structurally distinct shape (`refused: true` + `reason`, `notes: []`)
+ *    from a genuine empty recall (`refused: false, notes: []`), so a caller
+ *    cannot conflate "asked and got nothing" with "could not ask".
+ *  - I1: `ctx.principal_owner` travels through opaque and unexamined — this
+ *    module never derives, parses or keys on it (same reservation as
+ *    `note-builder.ts`).
+ *  - I4: no new capabilities/taxonomy vocabulary opens here — the
+ *    human-subject predicate is REUSED from `note-builder.ts`
+ *    (`isHumanMemorySubject`), never redefined.
+ */
+import { isHumanMemorySubject } from "./note-builder.js";
+function refuse(reason) {
+    return { refused: true, reason, notes: [] };
+}
+/**
+ * Dispatch `query` through `port.recallMemory(query, ctx)` for the wake path.
+ * `port` is injected and may be `undefined`/`null` (I5: fail-closed default,
+ * not a wiring error — the real recall factory does not exist yet).
+ */
+export async function recallMemory(query, ctx, port) {
+    if (!port) {
+        return refuse("no memory recall port injected — refusing (fail-closed, I5)");
+    }
+    let result;
+    try {
+        result = await port.recallMemory(query, ctx);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return refuse(`memory recall port unreachable: ${reason}`);
+    }
+    if (result.projection !== "notes-only") {
+        return refuse(`memory recall port returned projection "${String(result.projection)}", expected "notes-only" — refusing rather than trusting an unverified shape`);
+    }
+    return {
+        refused: false,
+        notes: result.notes,
+        freshness: result.freshness,
+        projection: result.projection,
+        requestingPrincipal: result.requestingPrincipal,
+        unpaged: result.unpaged
+    };
+}
+/**
+ * The ONE grouping/summary helper this consumer offers, and it deliberately
+ * cannot be used to assemble a human-subject profile: any `human:<id>`
+ * subject note is EXCLUDED from the grouping (counted, never aggregated).
+ * Only non-human subjects (e.g. `"agent-work"`) are grouped. This mirrors the
+ * projection prohibition (§3.3.3) at the consumer boundary, so the
+ * prohibition holds even if a caller composes only this module's own exports
+ * — there is no way to reach a `Record<humanSubject, notes[]>` through it.
+ */
+export function groupAgentWorkNotesBySubject(notes) {
+    const grouped = {};
+    let excludedHumanSubjectCount = 0;
+    for (const note of notes) {
+        if (isHumanMemorySubject(note.subject)) {
+            excludedHumanSubjectCount += 1;
+            continue;
+        }
+        const bucket = grouped[note.subject] ?? (grouped[note.subject] = []);
+        bucket.push(note);
+    }
+    return { grouped, excludedHumanSubjectCount };
+}
+//# sourceMappingURL=recall-client.js.map

package/dist/runtime/memory/recall-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-client.js","sourceRoot":"","sources":["../../../src/runtime/memory/recall-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AA2BzD,SAAS,MAAM,CAAC,MAAc;IAC5B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,GAAkB,EAClB,IAAyC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,MAAM,CAAC,6DAA6D,CAAC,CAAC;IAC/E,CAAC;IAED,IAAI,MAA8B,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,OAAO,MAAM,CAAC,mCAAmC,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,MAAM,CAAC,UAAU,KAAK,YAAY,EAAE,CAAC;QACvC,OAAO,MAAM,CACX,2CAA2C,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,8EAA8E,CACnJ,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;AACJ,CAAC;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAC1C,KAAwC;IAExC,MAAM,OAAO,GAA6C,EAAE,CAAC;IAC7D,IAAI,yBAAyB,GAAG,CAAC,CAAC;IAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,yBAAyB,IAAI,CAAC,CAAC;YAC/B,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACrE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/h2a",
-  "version": "0.96.0",
+  "version": "0.96.2",
   "description": "h2a — the unified CLI + core for human-to-agent coordination.",
   "license": "MIT",
   "type": "module",
@@ -52,10 +52,13 @@
     "@hono/mcp": "^0.3.0",
     "@hono/node-server": "^2.0.12",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@sentropic/track": "^0.96.0",
+    "@sentropic/cluster-mesh": "0.9.0",
+    "@sentropic/contracts": "^0.3.0",
+    "@sentropic/events": "^0.2.0",
+    "@sentropic/track": "^0.96.1",
     "hono": "^4.12.32"
   },
   "peerDependencies": {
-    "@sentropic/h2a-runtime": "^0.96.0"
+    "@sentropic/h2a-runtime": "^0.96.1"
   }
 }

package/skills/h2a-run/SKILL.md

@@ -8,7 +8,7 @@ description: Translate a friendly launch intent ("terra 5.6 xhigh", "codex sol h
 ## When to use this
 
 - The user names a launch by nickname + effort ("terra 5.6 xhigh", "sol en max", "relance codex en xhigh") instead of a provider model id.
-- The user wants a background or interactive Claude/Codex session with a specific reasoning effort, with or without the llm-mesh gateway, and needs the exact CLI flags or MCP parameters.
+- The user wants a background or interactive Claude/Codex/AGY session with a specific reasoning effort, with or without the llm-mesh gateway, and needs the exact CLI flags or MCP parameters.
 - **Not** for deciding *which* flavor is best for a task (that is a human/model-delegation call, not this skill's job), and **not** for resolving alias→upstream-provider routing — that table is owned by the llm-mesh gateway, not this skill (see Step 2).
 
 ## Hard rule: never call the raw `h2a` binary from Bash
@@ -19,9 +19,9 @@ This plugin's PreToolUse hook (`packages/h2a/hooks/deny-manual-h2a-cli.mjs`) blo
 
 None of these require knowing a provider model id up front:
 
-1. **Profile** — `claude` or `codex` (which CLI to launch). Default to whichever CLI the user is already in if unstated; ask if genuinely ambiguous.
+1. **Profile** — `claude`, `codex`, or `agy` (which CLI to launch). Default to whichever CLI the user is already in if unstated; ask if genuinely ambiguous.
 2. **Model flavor** — a nickname like *terra*, *sol* (aka *fable*), *luna*, or unstated (→ the CLI's own default model). Resolves to a `--model` / `model` value (Step 2).
-3. **Effort** — `low | medium | high | xhigh`. "max" said by the user means `xhigh` — there is no higher tier for `h2a run` / `h2a_run` today.
+3. **Effort** — `low | medium | high | xhigh`. For Claude/Codex, "max" means `xhigh`; AGY accepts only `low | medium | high` and rejects both `xhigh` and "max".
 
 ## Step 2 — resolve the model flavor (source-of-truth caveat)
 
@@ -39,11 +39,13 @@ Any non-default flavor needs the llm-mesh gateway to translate the Anthropic-sha
 - CLI: `--gw` (alias `--llm-gateway`) forces it on, `--no-gw` (alias `--no-llm-gateway`) forces it off, omit for the CLI's own default.
 - MCP `h2a_run`: `gateway: "required"` forces it on, `"off"` forces it off, `"auto"` (default) decides. **`"required"` is rejected when `profile` is `"codex"`** — codex already talks to llm-mesh over an Anthropic-compatible surface, use `"auto"` there.
 
+AGY is the exception to the named-flavor rule: it talks to its provider directly. Use `gateway: "off"` for `profile: "agy"`; `"required"` is rejected. AGY accepts effort `low|medium|high`, not `xhigh`, and supports run-once mode through its verified `--print` stdin contract. Resolve the exact AGY model with `agy models`; for example, the displayed "Gemini 3.7 Flash (High)" id is `gemini-3.7-flash-high`.
+
 ## Step 4 — compose the call
 
 ### `h2a_run` MCP tool (what this agent must use)
 
-Required: `profile` (`"claude"|"codex"`), `name` (`^[A-Za-z0-9_-]{1,64}$`), `workspace` (absolute path, must exist, must stay inside the MCP server's startup workspace root), `prompt` (1–65536 UTF-8 bytes, sent on stdin — never put it in argv), `background` (must be literal `true`). Optional: `model` (free-text, format-checked only — see Step 2 for the value), `effort` (`"low"|"medium"|"high"|"xhigh"`), `gateway` (`"auto"|"required"|"off"`, default `"auto"`), `headless` (default `false`), `h2aSidecar` (default `!headless`; cannot be `true` together with `headless: true`).
+Required: `profile` (`"claude"|"codex"|"agy"`), `name` (`^[A-Za-z0-9_-]{1,64}$`), `workspace` (absolute path, must exist, must stay inside the MCP server's startup workspace root), `prompt` (1–65536 UTF-8 bytes, sent on stdin — never put it in argv), `background` (must be literal `true`). Optional: `agent` (AGY only; for example `"stp"`), `model` (free-text, format-checked only — see Step 2 for the value), `effort` (`"low"|"medium"|"high"|"xhigh"`; AGY rejects `xhigh`), `gateway` (`"auto"|"required"|"off"`, default `"auto"`; AGY uses `"off"`), `headless` (default `false`; AGY maps `true` to `--print`), `h2aSidecar` (default `!headless`; cannot be `true` together with `headless: true`).
 
 Example — "terra, xhigh, headless, on this repo":
 
@@ -63,6 +65,24 @@ Example — "terra, xhigh, headless, on this repo":
 
 The tool returns an `h2a.run.result` contract with `session.tmuxSession`, `session.pane`, `session.gateway` (`"gateway"|"direct"`). Read those fields back to confirm what actually launched — do not assume the request was honored silently.
 
+Example — direct AGY run-once:
+
+```json
+{
+  "profile": "agy",
+  "name": "gemini-review",
+  "workspace": "/abs/path/to/repo",
+  "prompt": "<initial instructions>",
+  "background": true,
+  "agent": "stp",
+  "model": "gemini-3.7-flash-high",
+  "effort": "high",
+  "gateway": "off",
+  "headless": true,
+  "h2aSidecar": false
+}
+```
+
 ### `h2a run` CLI (reference only — non-Claude-Code hosts / humans at a terminal)
 
 ```
@@ -75,10 +95,23 @@ Interactive/attached form (drop the background-launch flags, add nothing else):
 h2a run claude . --model gpt-5.6-terra --effort xhigh --gw --name terra-review
 ```
 
+Direct AGY run-once form (prompt delivered on stdin):
+
+```
+h2a run agy . --agent stp --model gemini-3.7-flash-high --effort high --no-gw --name gemini-review --no-attach --background --json --headless --no-h2a --prompt-stdin
+```
+
+Interactive AGY keeps the TUI and accepts the same prompt-over-stdin contract; resume uses AGY's native `--conversation` argv through h2a's `-r/--resume` option:
+
+```
+h2a run agy . --agent stp --model gemini-3.7-flash-high --effort high --no-gw --name gemini-review --prompt-stdin
+h2a run agy . -r <conversation-id> --agent stp --model gemini-3.7-flash-high --effort high --no-gw --name gemini-review
+```
+
 Other `h2a run` flags worth knowing:
 
-- `-r, --resume <convId>` — continue a conversation; combine with `--model`/`--effort` to relaunch the same conversation at a different flavor/effort.
-- `--headless` — run once, record output under `.h2a/runs/<name>`, then exit (cannot combine with `--h2a`).
+- `-r, --resume <convId>` — continue a conversation; combine with `--model`/`--effort` to relaunch the same conversation at a different flavor/effort (AGY maps this to `--conversation <convId>`).
+- `--headless` — run once, record output under `.h2a/runs/<name>`, then exit (cannot combine with `--h2a`; AGY uses `--input-format stream-json --output-format stream-json`, with one escaped `user` event on stdin).
 - `--count <n>` — fan out N fresh sessions; incompatible with `--model`/`--effort`/`--resume`/any structured launch (each fanned session is a fresh conversation).
 - `--h2a` / `--no-h2a` — start (or skip) the side-window h2a MCP server; defaults on unless `--headless`.
 - `--name <label>` — tmux slug + tab label; defaults to the workspace dirname. Pick one deliberately when launching more than one session against the same repo.