@ggui-ai/protocol-conformance 0.13.0 → 0.15.0

package/dist/refusal-envelope-conformance/cases/refuse-after-fix-caller.json

@@ -0,0 +1,27 @@
+{
+    "name": "refuse-after-fix-caller",
+    "description": "An after-fix refusal the CALLER can act on itself: the projector emits an isError result whose text leads with the code, carries outcome 'refused' plus the refusal and nothing else, and exposes no _meta. This is the only fixBy class an agent may retry on its own.",
+    "refusal": {
+        "code": "model_not_in_tier",
+        "message": "the requested model is not among those this app may use",
+        "fix": "pick a model the app is allowed to use and call again with the same handshakeId",
+        "retry": "after-fix",
+        "handshake": "intact"
+    },
+    "expect": {
+        "isError": true,
+        "text": "model_not_in_tier: the requested model is not among those this app may use pick a model the app is allowed to use and call again with the same handshakeId",
+        "structuredContent": {
+            "outcome": "refused",
+            "refusal": {
+                "code": "model_not_in_tier",
+                "message": "the requested model is not among those this app may use",
+                "fix": "pick a model the app is allowed to use and call again with the same handshakeId",
+                "retry": "after-fix",
+                "handshake": "intact"
+            }
+        },
+        "hasMeta": false,
+        "identityFields": []
+    }
+}

package/dist/refusal-envelope-conformance/cases/refuse-after-fix-owner-with-balance.json

@@ -0,0 +1,29 @@
+{
+    "name": "refuse-after-fix-owner-with-balance",
+    "description": "An after-fix refusal whose fix belongs to the app OWNER, carrying the optional balance the refusing check read. The optional field rides the envelope unchanged \u2014 a projector must not drop it, and an agent must not auto-retry a fix it cannot perform.",
+    "refusal": {
+        "code": "insufficient_credit",
+        "message": "the balance this deployment funds the app from is exhausted",
+        "fix": "the app owner adds funds; the same handshakeId is still valid afterwards",
+        "retry": "after-fix",
+        "handshake": "intact",
+        "balanceCentsAtCheck": 0
+    },
+    "expect": {
+        "isError": true,
+        "text": "insufficient_credit: the balance this deployment funds the app from is exhausted the app owner adds funds; the same handshakeId is still valid afterwards",
+        "structuredContent": {
+            "outcome": "refused",
+            "refusal": {
+                "code": "insufficient_credit",
+                "message": "the balance this deployment funds the app from is exhausted",
+                "fix": "the app owner adds funds; the same handshakeId is still valid afterwards",
+                "retry": "after-fix",
+                "handshake": "intact",
+                "balanceCentsAtCheck": 0
+            }
+        },
+        "hasMeta": false,
+        "identityFields": []
+    }
+}

package/dist/refusal-envelope-conformance/cases/refuse-later.json

@@ -0,0 +1,27 @@
+{
+    "name": "refuse-later",
+    "description": "A transient refusal: unbounded time rather than a period boundary. Handshake intact, so the SAME id is valid on the retry the fix invites \u2014 the case exists so a projector cannot special-case the retryable class.",
+    "refusal": {
+        "code": "issuer_rate_limited",
+        "message": "calls under this issuing identity are over the rate this deployment allows",
+        "fix": "retry shortly \u2014 time restores it",
+        "retry": "later",
+        "handshake": "intact"
+    },
+    "expect": {
+        "isError": true,
+        "text": "issuer_rate_limited: calls under this issuing identity are over the rate this deployment allows retry shortly \u2014 time restores it",
+        "structuredContent": {
+            "outcome": "refused",
+            "refusal": {
+                "code": "issuer_rate_limited",
+                "message": "calls under this issuing identity are over the rate this deployment allows",
+                "fix": "retry shortly \u2014 time restores it",
+                "retry": "later",
+                "handshake": "intact"
+            }
+        },
+        "hasMeta": false,
+        "identityFields": []
+    }
+}

package/dist/refusal-envelope-conformance/cases/refuse-never.json

@@ -0,0 +1,27 @@
+{
+    "name": "refuse-never",
+    "description": "A refusal no caller action can lift. It still projects to a normal isError tool result — a terminal refusal is a wire state, never a thrown error. Carried on `billing_mode_anomaly` since registry v9 retired `tier_unrecognized`; the graded property is the `never` retry class, not the particular code.",
+    "refusal": {
+        "code": "billing_mode_anomaly",
+        "message": "the app record declares a funding mode this deployment does not recognise",
+        "fix": "no caller or owner action restores rendering under this identity; the operator reconciles the record",
+        "retry": "never",
+        "handshake": "intact"
+    },
+    "expect": {
+        "isError": true,
+        "text": "billing_mode_anomaly: the app record declares a funding mode this deployment does not recognise no caller or owner action restores rendering under this identity; the operator reconciles the record",
+        "structuredContent": {
+            "outcome": "refused",
+            "refusal": {
+                "code": "billing_mode_anomaly",
+                "message": "the app record declares a funding mode this deployment does not recognise",
+                "fix": "no caller or owner action restores rendering under this identity; the operator reconciles the record",
+                "retry": "never",
+                "handshake": "intact"
+            }
+        },
+        "hasMeta": false,
+        "identityFields": []
+    }
+}

package/dist/refusal-envelope-conformance/cases/refuse-next-period.json

@@ -0,0 +1,27 @@
+{
+    "name": "refuse-next-period",
+    "description": "A next-period refusal names no party at all \u2014 time restores it. The envelope is otherwise identical, which is the point: the retry class is data on the wire, not a different shape.",
+    "refusal": {
+        "code": "hard_cap_exceeded",
+        "message": "the app reached the hard ceiling set for the current period",
+        "fix": "the ceiling resets at the start of the next period; no action restores it sooner",
+        "retry": "next-period",
+        "handshake": "intact"
+    },
+    "expect": {
+        "isError": true,
+        "text": "hard_cap_exceeded: the app reached the hard ceiling set for the current period the ceiling resets at the start of the next period; no action restores it sooner",
+        "structuredContent": {
+            "outcome": "refused",
+            "refusal": {
+                "code": "hard_cap_exceeded",
+                "message": "the app reached the hard ceiling set for the current period",
+                "fix": "the ceiling resets at the start of the next period; no action restores it sooner",
+                "retry": "next-period",
+                "handshake": "intact"
+            }
+        },
+        "hasMeta": false,
+        "identityFields": []
+    }
+}

package/dist/refusal-envelope-conformance/cases/refuse-non-render-surface.json

@@ -0,0 +1,12 @@
+{
+    "name": "refuse-non-render-surface",
+    "description": "A REGISTERED code whose surfaces exclude the render gate. It has no render envelope at all, so a conformant projector produces nothing for it. Projecting it anyway is the drift the per-surface namespace rule forbids \u2014 this case is what makes that rule observable rather than prose.",
+    "refusal": {
+        "code": "subscription_exists",
+        "message": "an active plan already exists on this app",
+        "fix": "cancel the existing plan first, then call again",
+        "retry": "after-fix",
+        "handshake": "intact"
+    },
+    "expect": null
+}

package/dist/refusal-envelope-conformance/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The refusal a deployment's gate returned, as the projector receives
+ * it. Authored here rather than imported from `@ggui-ai/protocol`:
+ * this is the kit's own vocabulary, and `code` is typed loosely on
+ * purpose so a catalog case can carry a registered code from ANY
+ * surface — including one that must not project.
+ */
+export interface PreGenerationRefusalInput {
+    /** A code from the deployment's refusal registry. */
+    readonly code: string;
+    /** Precise diagnostic — what was checked, against what. */
+    readonly message: string;
+    /** The one recovery step, addressed to the party that can take it. */
+    readonly fix: string;
+    /** How the call becomes possible again. */
+    readonly retry: string;
+    /** Always `intact` — a refusal reads nothing, so it consumes nothing. */
+    readonly handshake: string;
+    /** Present only when the refusing check read a balance. */
+    readonly balanceCentsAtCheck?: number;
+}
+/**
+ * The observable shape of the tool result a conformant server emits for
+ * a refusal. Deliberately flattened to the four facts the obligation is
+ * about, so an implementation in any language can report them without
+ * reproducing an MCP result object.
+ */
+export interface ProjectedRefusalResult {
+    /** MUST be true — a refusal is an in-result error, never a throw. */
+    readonly isError: boolean;
+    /** `content[0].text` — leads with the code, then message and fix. */
+    readonly text: string;
+    /** The whole `structuredContent`. */
+    readonly structuredContent: {
+        readonly outcome: string;
+        readonly refusal: PreGenerationRefusalInput;
+    };
+    /** Whether the result carries any `_meta`. MUST be false. */
+    readonly hasMeta: boolean;
+    /**
+     * Identity fields the projector put on the envelope. MUST be empty —
+     * a refusal commits nothing, so any identity field means the
+     * projection leaked state that does not exist.
+     */
+    readonly identityFields: readonly string[];
+}
+/**
+ * One refusal-envelope case. Authored as JSON under `./cases/`,
+ * consumed via {@link refusalEnvelopeCases}, graded by
+ * {@link runRefusalEnvelopeConformance}.
+ *
+ * The shape IS the public API — additive changes only.
+ */
+export interface RefusalEnvelopeConformanceCase {
+    /** Unique case name. MUST match the JSON filename without `.json`. */
+    readonly name: string;
+    /** Which projection obligation this case proves. */
+    readonly description: string;
+    /** The refusal fed to the projector. */
+    readonly refusal: PreGenerationRefusalInput;
+    /**
+     * The result a spec-conformant projector MUST produce — or `null`
+     * when the code has no render envelope at all (its registered
+     * surfaces exclude the render gate).
+     */
+    readonly expect: ProjectedRefusalResult | null;
+}
+/**
+ * Every refusal-envelope case the kit ships, in deterministic order:
+ * the projectable cases by retry class (after-fix, next-period, later,
+ * never), then the non-projectable surface case.
+ */
+export declare const refusalEnvelopeCases: readonly RefusalEnvelopeConformanceCase[];
+/** One case the projector under test graded wrong. */
+export interface RefusalEnvelopeMismatch {
+    readonly name: string;
+    /** What the catalog says a conformant projector MUST produce. */
+    readonly expected: ProjectedRefusalResult | null;
+    /**
+     * What the projector produced — or, when it THREW instead of
+     * returning, a one-line report of the throw. A gate that throws to
+     * refuse is non-conformant, so the throw is graded, never rethrown.
+     */
+    readonly actual: ProjectedRefusalResult | null | string;
+}
+/** Outcome of grading a projector against the catalog. */
+export interface RefusalEnvelopeConformanceResult {
+    /** Names of cases the projector graded correctly. */
+    readonly passed: readonly string[];
+    /** Cases the projector graded wrong — empty iff fully conformant. */
+    readonly failed: readonly RefusalEnvelopeMismatch[];
+}
+/**
+ * Grade a refusal projector against the catalog.
+ *
+ * `project` MUST be a pure computation of `(refusal) → result | null`,
+ * where `null` means "this code has no render envelope". The kit
+ * deliberately does NOT import a concrete projector — adopters pass
+ * their own. A conformant projector produces an empty `failed` array.
+ *
+ * `project` is invoked exactly once per case, in
+ * {@link refusalEnvelopeCases} order. It MUST NOT throw: throwing to
+ * refuse is precisely the non-conformance this catalog exists to
+ * catch, so a throw is recorded as a graded FAILURE on that case
+ * rather than escaping the run.
+ */
+export declare function runRefusalEnvelopeConformance(project: (refusal: PreGenerationRefusalInput) => ProjectedRefusalResult | null): RefusalEnvelopeConformanceResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/refusal-envelope-conformance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/refusal-envelope-conformance/index.ts"],"names":[],"mappings":"AA4DA;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,iBAAiB,EAAE;QAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;KAC7C,CAAC;IACF,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,8BAA8B;IAC7C,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,8BAA8B,EAOzE,CAAC;AAEF,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,GAAG,MAAM,CAAC;CACzD;AAED,0DAA0D;AAC1D,MAAM,WAAW,gCAAgC;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACrD;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,CACP,OAAO,EAAE,yBAAyB,KAC/B,sBAAsB,GAAG,IAAI,GACjC,gCAAgC,CAwBlC"}

package/dist/refusal-envelope-conformance/index.js

@@ -0,0 +1,119 @@
+/**
+ * Refusal-envelope conformance catalog — the projection obligation for a
+ * PRE-GENERATION refusal (SPEC §7.1's refused arm, ggui#786).
+ *
+ * ## Why this is a pure-function catalog
+ *
+ * Given a refusal a deployment's gate returned, the tool result a
+ * conformant server emits is a pure, deterministic projection — no
+ * render, no transport, no wire frame. So it gets the same treatment as
+ * the wire schema (`../schema-conformance`) and the gadget URL resolver
+ * (`../resolution-conformance`): a catalog of cases graded against a
+ * caller-supplied projector.
+ *
+ * The obligation, restated from SPEC §7.1 so an implementer never has
+ * to guess:
+ *
+ *   - The result is an `isError: true` TOOL RESULT — never a thrown
+ *     error, never a JSON-RPC error. A gate that throws instead of
+ *     returning a refusal is non-conformant, which is why the runner
+ *     grades a throwing projector as a failure on every case rather
+ *     than letting the exception escape.
+ *   - `content[0].text` LEADS with the code, then the message and the
+ *     fix. A courtesy line for the model; the machine-readable code is
+ *     the mechanism.
+ *   - `structuredContent` is `{outcome: 'refused', refusal}` and
+ *     NOTHING else. A refusal commits nothing, so no identity field
+ *     may appear on it.
+ *   - No `_meta`. A refusal exposes no mount affordance.
+ *   - A code whose registered surfaces exclude the render gate has NO
+ *     render envelope; a conformant projector produces none.
+ *
+ * ## Polyglot, decoupled
+ *
+ * Each case ships as raw JSON under `./cases/`.
+ * {@link runRefusalEnvelopeConformance} takes the projector as a
+ * callback — the kit never imports a concrete server here, so adopters
+ * drive their OWN. The reference binding
+ * (`./refusal-envelope-conformance.test.ts`) builds a faithful in-test
+ * projector from `@ggui-ai/protocol` primitives only; the drift-catch
+ * against a SHIPPING projector belongs implementation-side, in the
+ * package that owns it.
+ *
+ * ## Not a WS fixture
+ *
+ * These cases are deliberately NOT registered in `fixturesByContract`.
+ * The obligation is a projection, not a WebSocket-observable behavior,
+ * so registering it there would be a permanent skip on every run —
+ * exactly the false gate the kit's exact skip-set pinning prevents.
+ * `runConformance()` / the CLI / the reporter are untouched; the entry
+ * point is the programmatic runner below.
+ */
+import refuseAfterFixCaller from './cases/refuse-after-fix-caller.json' with { type: 'json' };
+import refuseAfterFixOwnerWithBalance from './cases/refuse-after-fix-owner-with-balance.json' with { type: 'json' };
+import refuseLater from './cases/refuse-later.json' with { type: 'json' };
+import refuseNever from './cases/refuse-never.json' with { type: 'json' };
+import refuseNextPeriod from './cases/refuse-next-period.json' with { type: 'json' };
+import refuseNonRenderSurface from './cases/refuse-non-render-surface.json' with { type: 'json' };
+import { jsonEqual } from '../json-equal.js';
+/**
+ * Every refusal-envelope case the kit ships, in deterministic order:
+ * the projectable cases by retry class (after-fix, next-period, later,
+ * never), then the non-projectable surface case.
+ */
+export const refusalEnvelopeCases = [
+    refuseAfterFixCaller,
+    refuseAfterFixOwnerWithBalance,
+    refuseNextPeriod,
+    refuseLater,
+    refuseNever,
+    refuseNonRenderSurface,
+];
+function projectionEqual(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return (a.isError === b.isError &&
+        a.text === b.text &&
+        a.hasMeta === b.hasMeta &&
+        jsonEqual([...a.identityFields], [...b.identityFields]) &&
+        jsonEqual(a.structuredContent, b.structuredContent));
+}
+/**
+ * Grade a refusal projector against the catalog.
+ *
+ * `project` MUST be a pure computation of `(refusal) → result | null`,
+ * where `null` means "this code has no render envelope". The kit
+ * deliberately does NOT import a concrete projector — adopters pass
+ * their own. A conformant projector produces an empty `failed` array.
+ *
+ * `project` is invoked exactly once per case, in
+ * {@link refusalEnvelopeCases} order. It MUST NOT throw: throwing to
+ * refuse is precisely the non-conformance this catalog exists to
+ * catch, so a throw is recorded as a graded FAILURE on that case
+ * rather than escaping the run.
+ */
+export function runRefusalEnvelopeConformance(project) {
+    const passed = [];
+    const failed = [];
+    for (const testCase of refusalEnvelopeCases) {
+        let actual;
+        try {
+            actual = project(testCase.refusal);
+        }
+        catch (err) {
+            failed.push({
+                name: testCase.name,
+                expected: testCase.expect,
+                actual: `threw instead of returning a refusal envelope: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            continue;
+        }
+        if (projectionEqual(actual, testCase.expect)) {
+            passed.push(testCase.name);
+        }
+        else {
+            failed.push({ name: testCase.name, expected: testCase.expect, actual });
+        }
+    }
+    return { passed, failed };
+}

package/dist/registry-completeness/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Registry-completeness catalog — the structural obligations a
+ * deployment's refusal-code registry MUST satisfy (ggui#786, ruling
+ * 5b).
+ *
+ * ## Why this is a pure-function catalog, graded differently
+ *
+ * Unlike every other catalog here, this one grades DATA rather than a
+ * function: the closed set of refusal codes a deployment declares. The
+ * caller passes the registry; each pin inspects every row and reports
+ * the rows that violate it.
+ *
+ * ## The four PORTABLE pins, and the two that are deliberately absent
+ *
+ * Ruling 5b names six checks. Four are portable — a third-party adopter
+ * with their own registry can run them, and they are the four below.
+ *
+ * Two read repo SOURCE and therefore cannot ship as conformance: the
+ * docstring rule ("an agent MUST NOT auto-retry an after-fix refusal
+ * whose fixBy is not caller") and the grep for code literals minted
+ * outside the registry file. This package publishes only `dist` +
+ * `README.md`, so a source walk could never run for an adopter, and the
+ * files that rule names live outside this tree entirely. Both live in
+ * `@ggui-ai/protocol`'s own suite, where the invariant is owned and the
+ * paths are stable. The omission is DECLARED here rather than hidden.
+ *
+ * ## Why the `fixBy` pin is one-directional
+ *
+ * The pin below asserts only that an `after-fix` row NAMES who acts. It
+ * does not assert `fixBy` is absent elsewhere, because that is a naming
+ * discipline rather than a reader-observable obligation: a reader
+ * branches on `retry`, and a `fixBy` beside a `never` misleads a human
+ * without changing what any implementation does.
+ *
+ * ggui's own registry is stricter — `fixBy` is REQUIRED on `after-fix`,
+ * PERMITTED on `later` (the operator who restores a transiently
+ * unavailable surface) and FORBIDDEN on `next-period` and `never` — and
+ * enforces it at the type level in its definer, pinned in
+ * `@ggui-ai/protocol`'s own suite. Adopters are welcome to that rule;
+ * the kit does not make it a conformance obligation. The one thing that
+ * must never happen, and IS graded here, is an `after-fix` row that
+ * does not say WHO acts — the one an agent could misread as its own to
+ * retry.
+ */
+/** One registry row, in the kit's own loose vocabulary. */
+export interface RefusalRegistryRow {
+    /** MUST equal the row's key in the registry. */
+    readonly code: string;
+    /** MUST be non-empty — the surfaces this state is refused on. */
+    readonly surfaces: readonly string[];
+    /** MUST be one of the four recognized retry classes. */
+    readonly retry: string;
+    /** Who acts. REQUIRED when `retry` is `after-fix`. */
+    readonly fixBy?: string | undefined;
+    /** Where the code is produced. */
+    readonly emitter: string;
+    /** What state the code names. */
+    readonly description: string;
+}
+/**
+ * A registry as the kit reads it: code → row. Decoupled from
+ * `@ggui-ai/protocol`'s own types on purpose — an adopter's registry is
+ * graded through this view, and a deliberately broken registry must be
+ * expressible for the negative cases.
+ */
+export type RefusalRegistryView = {
+    readonly [code: string]: RefusalRegistryRow;
+};
+/** One structural pin, applied to every row of a registry. */
+export interface RegistryCompletenessPin {
+    /** Unique pin name. */
+    readonly name: string;
+    /** The obligation this pin fixes in place. */
+    readonly description: string;
+    /**
+     * Report why `row` (declared under `code`) violates the pin, or
+     * `null` when it satisfies it.
+     */
+    readonly violation: (code: string, row: RefusalRegistryRow) => string | null;
+}
+/** Every portable pin the kit ships, in deterministic order. */
+export declare const registryCompletenessPins: readonly RegistryCompletenessPin[];
+/** One pin a registry failed, with every offending row named. */
+export interface RegistryCompletenessMismatch {
+    readonly name: string;
+    readonly description: string;
+    /** One entry per violating row: `<code>: <why>`. */
+    readonly violations: readonly string[];
+}
+/** Outcome of grading a registry against the pins. */
+export interface RegistryCompletenessResult {
+    /** Names of pins the registry satisfies. */
+    readonly passed: readonly string[];
+    /** Pins the registry violates — empty iff fully conformant. */
+    readonly failed: readonly RegistryCompletenessMismatch[];
+}
+/**
+ * Grade a refusal registry against {@link registryCompletenessPins}.
+ *
+ * Every pin is applied to every row, in declaration order; a pin passes
+ * only when NO row violates it. A conformant registry produces an empty
+ * `failed` array.
+ */
+export declare function runRegistryCompletenessConformance(registry: RefusalRegistryView): RegistryCompletenessResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/registry-completeness/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registry-completeness/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAAC;CAC7C,CAAC;AAUF,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,KAAK,MAAM,GAAG,IAAI,CAAC;CAC9E;AAED,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,EAAE,SAAS,uBAAuB,EAoCtE,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,sDAAsD;AACtD,MAAM,WAAW,0BAA0B;IACzC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,mBAAmB,GAC5B,0BAA0B,CAiB5B"}

package/dist/registry-completeness/index.js

@@ -0,0 +1,110 @@
+/**
+ * Registry-completeness catalog — the structural obligations a
+ * deployment's refusal-code registry MUST satisfy (ggui#786, ruling
+ * 5b).
+ *
+ * ## Why this is a pure-function catalog, graded differently
+ *
+ * Unlike every other catalog here, this one grades DATA rather than a
+ * function: the closed set of refusal codes a deployment declares. The
+ * caller passes the registry; each pin inspects every row and reports
+ * the rows that violate it.
+ *
+ * ## The four PORTABLE pins, and the two that are deliberately absent
+ *
+ * Ruling 5b names six checks. Four are portable — a third-party adopter
+ * with their own registry can run them, and they are the four below.
+ *
+ * Two read repo SOURCE and therefore cannot ship as conformance: the
+ * docstring rule ("an agent MUST NOT auto-retry an after-fix refusal
+ * whose fixBy is not caller") and the grep for code literals minted
+ * outside the registry file. This package publishes only `dist` +
+ * `README.md`, so a source walk could never run for an adopter, and the
+ * files that rule names live outside this tree entirely. Both live in
+ * `@ggui-ai/protocol`'s own suite, where the invariant is owned and the
+ * paths are stable. The omission is DECLARED here rather than hidden.
+ *
+ * ## Why the `fixBy` pin is one-directional
+ *
+ * The pin below asserts only that an `after-fix` row NAMES who acts. It
+ * does not assert `fixBy` is absent elsewhere, because that is a naming
+ * discipline rather than a reader-observable obligation: a reader
+ * branches on `retry`, and a `fixBy` beside a `never` misleads a human
+ * without changing what any implementation does.
+ *
+ * ggui's own registry is stricter — `fixBy` is REQUIRED on `after-fix`,
+ * PERMITTED on `later` (the operator who restores a transiently
+ * unavailable surface) and FORBIDDEN on `next-period` and `never` — and
+ * enforces it at the type level in its definer, pinned in
+ * `@ggui-ai/protocol`'s own suite. Adopters are welcome to that rule;
+ * the kit does not make it a conformance obligation. The one thing that
+ * must never happen, and IS graded here, is an `after-fix` row that
+ * does not say WHO acts — the one an agent could misread as its own to
+ * retry.
+ */
+/** The four recognized retry classes (ggui#786 rulings v2 + v4). */
+const RECOGNIZED_RETRIES = [
+    'after-fix',
+    'next-period',
+    'later',
+    'never',
+];
+/** Every portable pin the kit ships, in deterministic order. */
+export const registryCompletenessPins = [
+    {
+        name: 'surfaces-non-empty',
+        description: 'Every entry lists at least one surface it is emitted on. A row nobody emits anywhere is a name reserved with no obligation behind it, which is the drift a closed registry exists to prevent. One code MAY list several surfaces — one state can surface in more than one place.',
+        violation: (_code, row) => row.surfaces.length > 0 ? null : 'surfaces is empty',
+    },
+    {
+        name: 'code-equals-key',
+        description: "Every entry's `code` equals the key it is declared under. The key is what emitters look a row up by and the code is what reaches the wire; if they disagree, the registry stops being the single namespace it claims to be.",
+        violation: (code, row) => row.code === code ? null : `code '${row.code}' does not equal key '${code}'`,
+    },
+    {
+        name: 'after-fix-names-fixby',
+        description: "Every `after-fix` entry names WHO acts, in `fixBy`. Without it, 'retry after the fix' cannot be told apart from 'retry now' — and an agent may only act on a fix that is its own. A row whose `retry` is not a recognized class ALSO fails this pin: the obligation is undecidable for it, and a pin that silently passes a row it could not evaluate is a false gate.",
+        violation: (_code, row) => {
+            if (!RECOGNIZED_RETRIES.includes(row.retry)) {
+                return `retry '${row.retry}' is not a recognized class, so the fixBy obligation cannot be evaluated`;
+            }
+            if (row.retry !== 'after-fix')
+                return null;
+            return row.fixBy === undefined ? 'after-fix entry carries no fixBy' : null;
+        },
+    },
+    {
+        name: 'retry-in-closed-set',
+        description: "Every entry's `retry` is one of `after-fix`, `next-period`, `later`, `never`. The class is what a reader branches on to decide whether to wait, act, or stop; an unrecognized value leaves it with no defined behaviour.",
+        violation: (_code, row) => RECOGNIZED_RETRIES.includes(row.retry)
+            ? null
+            : `retry '${row.retry}' is outside the closed set`,
+    },
+];
+/**
+ * Grade a refusal registry against {@link registryCompletenessPins}.
+ *
+ * Every pin is applied to every row, in declaration order; a pin passes
+ * only when NO row violates it. A conformant registry produces an empty
+ * `failed` array.
+ */
+export function runRegistryCompletenessConformance(registry) {
+    const entries = Object.entries(registry);
+    const passed = [];
+    const failed = [];
+    for (const pin of registryCompletenessPins) {
+        const violations = [];
+        for (const [code, row] of entries) {
+            const why = pin.violation(code, row);
+            if (why !== null)
+                violations.push(`${code}: ${why}`);
+        }
+        if (violations.length === 0) {
+            passed.push(pin.name);
+        }
+        else {
+            failed.push({ name: pin.name, description: pin.description, violations });
+        }
+    }
+    return { passed, failed };
+}

package/dist/reporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAM9B,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,sBAA2B,GACnC,mBAAmB,CA0CrB;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAmBjE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAW/D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,CAW9E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAStE"}
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAM9B,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,sBAA2B,GACnC,mBAAmB,CA0CrB;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAejE;AAyBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAW/D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,CAW9E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAStE"}