@groundnuty/macf-core 0.2.44 → 0.2.46

package/dist/guest.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Cross-fleet GUEST bindings — DR-036 Amendment A (groundnuty/macf#679).
+ *
+ * A consumer fleet depends on a specialist agent that lives in ANOTHER fleet
+ * (the worked example: `icsoc-2026` depends on `ppam-2026/code-agent`, the
+ * `onedata-mcp` specialist). The consumer carries a LOCAL, consumer-side
+ * "guest" binding naming that external agent + the perspectival role it plays
+ * from the consumer's viewpoint. The external agent neither sees nor agrees to
+ * it — topology-autonomy is preserved (a consumer only ANNOTATES its own view;
+ * it cannot impose membership on a peer).
+ *
+ * The load-bearing invariant (DR-036 Amendment A): **visibility is split from
+ * supervision**. A guest MAY be SHOWN in the consumer's `macf fleet status` /
+ * `/macf-peers`, clearly marked external + unsupervised — but it is NEVER a
+ * supervised member (never owned by the consumer's registry, never under its
+ * DR-031 liveness / reconciliation / restart / prune machinery). Only the
+ * no-supervision half is mandatory; the visibility half is the new capability.
+ *
+ * The binding lives in the fleet-scope config `.github/macf-fleet.json`
+ * (macf#614 — the same file that carries the `routing_fleet` opt-OUT marker),
+ * so this schema describes the WHOLE file, not just the guests array. The
+ * `routing_fleet` key is preserved here so the one config file has one schema.
+ */
+import { z } from 'zod';
+import { MacfError } from './errors.js';
+/**
+ * How the consumer reaches the guest (DR-036 §two enabler paths, Amendment A):
+ *  - `route`          — the guest is App-scoped + GitHub-@mention-routable
+ *                       (paths a/b). Cross-reachable → a live `/health` probe is
+ *                       meaningful; the guest shows its live online/offline state.
+ *  - `operator-relay` — the guest is a local-mode / private-mesh agent (path c):
+ *                       no App, a local-CA mTLS mesh on a host the consumer can't
+ *                       reach. A cross-fleet `/health` probe is NOT meaningful (it
+ *                       would hit the consumer's own localhost or fail), so the
+ *                       guest renders registry-derived state ONLY — never "down".
+ */
+export declare const GUEST_DELEGATE_VIA: readonly ["route", "operator-relay"];
+export declare const GuestDelegateViaSchema: z.ZodEnum<{
+    route: "route";
+    "operator-relay": "operator-relay";
+}>;
+export type GuestDelegateVia = z.infer<typeof GuestDelegateViaSchema>;
+/**
+ * One consumer-side guest binding (DR-036 Amendment A). Consumer-LOCAL: the
+ * external agent is unaware. Perspectival — `local_role` is the consumer's
+ * vocabulary for the role the guest plays here, NOT a role the guest adopts.
+ */
+export declare const GuestBindingSchema: z.ZodObject<{
+    agent: z.ZodString;
+    local_role: z.ZodString;
+    purpose: z.ZodString;
+    delegate_via: z.ZodEnum<{
+        route: "route";
+        "operator-relay": "operator-relay";
+    }>;
+    until: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+}, z.core.$strip>;
+export type GuestBinding = z.infer<typeof GuestBindingSchema>;
+/**
+ * The whole `.github/macf-fleet.json` fleet-scope config (macf#614 + #679).
+ * Non-strict: unknown keys are stripped, so a future additive key doesn't
+ * reject the file. `guests` defaults to `[]` so a config with no guests (or the
+ * plain `routing_fleet`-only marker) parses to an empty guest list.
+ */
+export declare const MacfFleetConfigSchema: z.ZodObject<{
+    routing_fleet: z.ZodOptional<z.ZodBoolean>;
+    guests: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        local_role: z.ZodString;
+        purpose: z.ZodString;
+        delegate_via: z.ZodEnum<{
+            route: "route";
+            "operator-relay": "operator-relay";
+        }>;
+        until: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type MacfFleetConfig = z.infer<typeof MacfFleetConfigSchema>;
+/** Raised when a `.github/macf-fleet.json` value violates the schema. */
+export declare class GuestConfigError extends MacfError {
+    constructor(message: string);
+}
+/**
+ * Parse + validate a raw `.github/macf-fleet.json` value. Throws
+ * `GuestConfigError` (with the first Zod issue path + message) on any schema
+ * violation so a malformed binding fails LOUD rather than silently dropping a
+ * guest. Callers that must DEGRADE instead (a config read on a hot path) can use
+ * `MacfFleetConfigSchema.safeParse` directly and fall back to an empty config.
+ */
+export declare function parseMacfFleetConfig(raw: unknown): MacfFleetConfig;
+/**
+ * Split a `<home-project>/<name>` guest ref into its two segments. Assumes the
+ * ref already passed `GuestBindingSchema` (exactly one `/`); throws
+ * `GuestConfigError` defensively for a malformed ref reaching this path.
+ */
+export declare function parseGuestAgentRef(agent: string): {
+    readonly homeProject: string;
+    readonly name: string;
+};
+//# sourceMappingURL=guest.d.ts.map

package/dist/guest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,sCAAuC,CAAC;AACvE,eAAO,MAAM,sBAAsB;;;EAA6B,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAUtE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;iBAgB7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAShC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,yEAAyE;AACzE,qBAAa,gBAAiB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CASlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAQA"}

package/dist/guest.js

@@ -0,0 +1,120 @@
+/**
+ * Cross-fleet GUEST bindings — DR-036 Amendment A (groundnuty/macf#679).
+ *
+ * A consumer fleet depends on a specialist agent that lives in ANOTHER fleet
+ * (the worked example: `icsoc-2026` depends on `ppam-2026/code-agent`, the
+ * `onedata-mcp` specialist). The consumer carries a LOCAL, consumer-side
+ * "guest" binding naming that external agent + the perspectival role it plays
+ * from the consumer's viewpoint. The external agent neither sees nor agrees to
+ * it — topology-autonomy is preserved (a consumer only ANNOTATES its own view;
+ * it cannot impose membership on a peer).
+ *
+ * The load-bearing invariant (DR-036 Amendment A): **visibility is split from
+ * supervision**. A guest MAY be SHOWN in the consumer's `macf fleet status` /
+ * `/macf-peers`, clearly marked external + unsupervised — but it is NEVER a
+ * supervised member (never owned by the consumer's registry, never under its
+ * DR-031 liveness / reconciliation / restart / prune machinery). Only the
+ * no-supervision half is mandatory; the visibility half is the new capability.
+ *
+ * The binding lives in the fleet-scope config `.github/macf-fleet.json`
+ * (macf#614 — the same file that carries the `routing_fleet` opt-OUT marker),
+ * so this schema describes the WHOLE file, not just the guests array. The
+ * `routing_fleet` key is preserved here so the one config file has one schema.
+ */
+import { z } from 'zod';
+import { MacfError } from './errors.js';
+/**
+ * How the consumer reaches the guest (DR-036 §two enabler paths, Amendment A):
+ *  - `route`          — the guest is App-scoped + GitHub-@mention-routable
+ *                       (paths a/b). Cross-reachable → a live `/health` probe is
+ *                       meaningful; the guest shows its live online/offline state.
+ *  - `operator-relay` — the guest is a local-mode / private-mesh agent (path c):
+ *                       no App, a local-CA mTLS mesh on a host the consumer can't
+ *                       reach. A cross-fleet `/health` probe is NOT meaningful (it
+ *                       would hit the consumer's own localhost or fail), so the
+ *                       guest renders registry-derived state ONLY — never "down".
+ */
+export const GUEST_DELEGATE_VIA = ['route', 'operator-relay'];
+export const GuestDelegateViaSchema = z.enum(GUEST_DELEGATE_VIA);
+/**
+ * `<home-project>/<name>` — the guest's home fleet + agent name. One `/`; no
+ * whitespace or additional slashes in either segment. Resolves in the shared
+ * registry scope as `<HOME_PROJECT>_AGENT_<NAME>` (DR-006 profile scope; the
+ * cross-scope union per macf#621 when the guest lives under a different scope).
+ */
+const GUEST_AGENT_REF_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+/**
+ * One consumer-side guest binding (DR-036 Amendment A). Consumer-LOCAL: the
+ * external agent is unaware. Perspectival — `local_role` is the consumer's
+ * vocabulary for the role the guest plays here, NOT a role the guest adopts.
+ */
+export const GuestBindingSchema = z.object({
+    /** `<home-project>/<name>` — home fleet + agent (resolves in the shared registry). */
+    agent: z
+        .string()
+        .regex(GUEST_AGENT_REF_RE, 'guest.agent must be "<home-project>/<name>" (one slash, no spaces)'),
+    /** The perspectival role the guest plays from the consumer's viewpoint (e.g. `onedata-specialist`). */
+    local_role: z.string().min(1, 'guest.local_role must be non-empty'),
+    /** Why this dependency exists (e.g. `data-access dependency (onedata-mcp)`). */
+    purpose: z.string().min(1, 'guest.purpose must be non-empty'),
+    /** How the consumer reaches the guest — decides path-aware reachability rendering. */
+    delegate_via: GuestDelegateViaSchema,
+    /**
+     * Optional expiry → "temporary" membership. `null` (or absent) = open-ended.
+     * A consumer-side annotation scoped in time with no change on the guest's side.
+     */
+    until: z.string().nullable().optional().default(null),
+});
+/**
+ * The whole `.github/macf-fleet.json` fleet-scope config (macf#614 + #679).
+ * Non-strict: unknown keys are stripped, so a future additive key doesn't
+ * reject the file. `guests` defaults to `[]` so a config with no guests (or the
+ * plain `routing_fleet`-only marker) parses to an empty guest list.
+ */
+export const MacfFleetConfigSchema = z.object({
+    /**
+     * macf#614 routing-fleet opt-OUT marker: a pinned agent-router-caller repo
+     * declares itself non-fleet (`false`) to be excluded from `routing doctor`'s
+     * `pins_consistent` verdict. Preserved here so one file has one schema.
+     */
+    routing_fleet: z.boolean().optional(),
+    /** Consumer-side cross-fleet guest bindings (DR-036 Amendment A, #679). */
+    guests: z.array(GuestBindingSchema).default([]),
+});
+/** Raised when a `.github/macf-fleet.json` value violates the schema. */
+export class GuestConfigError extends MacfError {
+    constructor(message) {
+        super('GUEST_CONFIG_ERROR', message);
+        this.name = 'GuestConfigError';
+    }
+}
+/**
+ * Parse + validate a raw `.github/macf-fleet.json` value. Throws
+ * `GuestConfigError` (with the first Zod issue path + message) on any schema
+ * violation so a malformed binding fails LOUD rather than silently dropping a
+ * guest. Callers that must DEGRADE instead (a config read on a hot path) can use
+ * `MacfFleetConfigSchema.safeParse` directly and fall back to an empty config.
+ */
+export function parseMacfFleetConfig(raw) {
+    const result = MacfFleetConfigSchema.safeParse(raw);
+    if (!result.success) {
+        const first = result.error.issues[0];
+        const where = first && first.path.length > 0 ? ` at ${first.path.join('.')}` : '';
+        const why = first ? first.message : 'invalid config';
+        throw new GuestConfigError(`Invalid .github/macf-fleet.json${where}: ${why}`);
+    }
+    return result.data;
+}
+/**
+ * Split a `<home-project>/<name>` guest ref into its two segments. Assumes the
+ * ref already passed `GuestBindingSchema` (exactly one `/`); throws
+ * `GuestConfigError` defensively for a malformed ref reaching this path.
+ */
+export function parseGuestAgentRef(agent) {
+    const slash = agent.indexOf('/');
+    if (slash <= 0 || slash !== agent.lastIndexOf('/') || slash === agent.length - 1) {
+        throw new GuestConfigError(`guest.agent "${agent}" is not "<home-project>/<name>" (one slash required)`);
+    }
+    return { homeProject: agent.slice(0, slash), name: agent.slice(slash + 1) };
+}
+//# sourceMappingURL=guest.js.map

package/dist/guest.js.map

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

package/dist/index.d.ts

@@ -17,7 +17,15 @@ export * from './config.js';
 export * from './token.js';
 export * from './types.js';
 export * from './semver.js';
+export * from './discovery.js';
+export * from './fleet-driver.js';
+export * from './fleet-reconcile.js';
+export * from './verify-green.js';
+export * from './fleet-upgrade.js';
 export * from './reflection.js';
+export * from './prompt-responses.js';
+export * from './stall-signatures.js';
+export * from './guest.js';
 export * from './norm.js';
 export * from './protected-invariant-norms.js';
 export * from './mtls-health-ping.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AAIpC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC5F,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AAIpC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC5F,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -17,7 +17,15 @@ export * from './config.js';
 export * from './token.js';
 export * from './types.js';
 export * from './semver.js';
+export * from './discovery.js';
+export * from './fleet-driver.js';
+export * from './fleet-reconcile.js';
+export * from './verify-green.js';
+export * from './fleet-upgrade.js';
 export * from './reflection.js';
+export * from './prompt-responses.js';
+export * from './stall-signatures.js';
+export * from './guest.js';
 export * from './norm.js';
 export * from './protected-invariant-norms.js';
 export * from './mtls-health-ping.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AAEpC,kEAAkE;AAClE,oEAAoE;AACpE,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AAEpC,kEAAkE;AAClE,oEAAoE;AACpE,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/norm.d.ts

@@ -115,8 +115,8 @@ export declare const ConditionSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>
 export type Condition = (typeof CONDITION_TOKENS)[number];
 /** The three deontic modalities. */
 export declare const DeonticSchema: z.ZodEnum<{
-    obligation: "obligation";
     permission: "permission";
+    obligation: "obligation";
     prohibition: "prohibition";
 }>;
 export type Deontic = z.infer<typeof DeonticSchema>;
@@ -150,8 +150,8 @@ export declare const NormSchema: z.ZodObject<{
         deployment: "deployment";
     }>>;
     deontic: z.ZodEnum<{
-        obligation: "obligation";
         permission: "permission";
+        obligation: "obligation";
         prohibition: "prohibition";
     }>;
     action: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{

package/dist/prompt-responses.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Interactive-prompt auto-responder — config schema, the Inv-2 ceremony-only
+ * classifier, and the pure Inv-1/Inv-3 frame matcher (DR-033, groundnuty/macf#645).
+ *
+ * SAFETY-CRITICAL. This module holds the *pure* logic behind the auto-responder:
+ * the config the operator curates in `.claude/.macf/prompt-responses.json`, the
+ * rules for what may go on the allowlist, and the frame-matching that decides
+ * whether a captured tmux pane is a KNOWN ceremony prompt we may answer. The
+ * shell watcher (`scripts/macf-prompt-watcher.sh`) reimplements the SAME
+ * algorithm in bash+jq for runtime; this module is the tested reference spec +
+ * the validator the CLI runs at `macf init/update/rules refresh`. The two MUST
+ * stay in lockstep — a change here is a change there.
+ *
+ * The three constitutional invariants (DR-033 §Decision):
+ *
+ *   Inv 1 — allowlist-only. Only auto-answer a prompt matching a vetted entry.
+ *     An unrecognized prompt-like frame → the caller ALERTs and does NOT answer.
+ *     `matchPromptFrame` returns `unknown-prompt` for that case; the watcher
+ *     turns it into a loud forensic-log + stderr alert. Silence-on-unknown beats
+ *     a wrong answer.
+ *
+ *   Inv 2 — ceremony-acks ONLY. The config loader HARD-REFUSES (drops) any entry
+ *     whose signature material contains an authorization/destructive substring
+ *     (`delete` / `overwrite` / `trust`) and LOUD-WARNS (keeps, operator-owned
+ *     risk) on `(y/n)` / `allow` / `permission` / `grant`. This constrains what
+ *     may go ON the allowlist — the stronger sibling of Inv 1.
+ *
+ *   Inv 3 — the signature GUARANTEES the `send` still means the intended option.
+ *     A structured signature (`frame_contains` + `option_text` at the `send`
+ *     ordinal's rendered position) — NOT a fragile substring. A menu reorder /
+ *     reword / insert breaks the match → falls through to Inv 1 (alert, don't
+ *     answer) rather than firing a now-wrong ordinal. The signature is not "what
+ *     prompt is this"; it is "is the world still exactly as the `send` assumes".
+ */
+import { z } from 'zod';
+import { MacfError } from './errors.js';
+/** Config schema version. Bump on a breaking shape change. */
+export declare const PROMPT_RESPONSES_SCHEMA_VERSION: "1";
+/**
+ * Inv 2 — HARD-REFUSE substrings. An entry whose signature material contains any
+ * of these (case-insensitive) is DROPPED at load: the auto-responder must never
+ * answer a destructive-confirmation or a folder/tool-trust prompt, even if an
+ * operator tries to allowlist it (DR-033 OQ1 lean: hard-refuse the most
+ * dangerous). Kept in lockstep with `PROMPT_REFUSE_SUBSTRINGS` in the watcher.
+ * `revoke`/`remove` are the security/destructive siblings of `delete`/`trust`
+ * ("revoke token?" / "remove collaborator?") — same never-even-if-allowlisted
+ * class (science review of macf#645).
+ */
+export declare const PROMPT_REFUSE_SUBSTRINGS: readonly ["delete", "overwrite", "trust", "revoke", "remove"];
+/**
+ * Inv 2 — LOUD-WARN substrings. An entry whose signature material contains any
+ * of these is KEPT (operator-owned risk) but flagged loudly at load: these lean
+ * authorization-shaped, so the operator should confirm they meant a ceremony ack
+ * and not a permission grant. Kept in lockstep with the watcher.
+ */
+export declare const PROMPT_WARN_SUBSTRINGS: readonly ["(y/n)", "allow", "permission", "grant"];
+/** Thrown when the prompt-responses config fails schema validation. */
+export declare class PromptResponderError extends MacfError {
+    constructor(message: string);
+}
+/**
+ * A single allowlist entry — the STRUCTURED signature that resolves DR-033 OQ2
+ * (Inv 3). `frame_contains` identifies WHICH prompt (all substrings must be
+ * present); `option_text` is the EXACT rendered text at the `send` ordinal's
+ * line, so `send`↔option binding is machine-checkable, not a fragile substring.
+ *
+ *   - `frame_contains` — substrings that MUST ALL be present in the captured
+ *     frame (Inv 1 identity). Requiring all present also doubles as the
+ *     "wait for the full frame rendered" gate.
+ *   - `option_text` — the exact rendered option text at the `send` position
+ *     (Inv 3 binding). Must appear on a menu line numbered `send`.
+ *   - `send` — the keystroke(s) to send, typically a menu ordinal ("1" / "2").
+ *   - `verify_contains` — OPTIONAL expected substring of the POST-answer
+ *     next-screen (Inv-A "verify the RIGHT outcome"). When set, the watcher
+ *     asserts it appears after sending; when unset the watcher verifies
+ *     signature-clearance only + logs that the outcome check was weaker.
+ *   - `max_fires` — per-prompt fire cap (default 1). An auto-responder that
+ *     fires repeatedly on a recurring pattern is itself a hazard.
+ *
+ * `.strict()` so an operator typo in a field name (e.g. `frame_contain`) is a
+ * loud validation error, not a silently-ignored field.
+ */
+export declare const PromptResponseEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    frame_contains: z.ZodArray<z.ZodString>;
+    option_text: z.ZodString;
+    send: z.ZodString;
+    verify_contains: z.ZodOptional<z.ZodString>;
+    max_fires: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type PromptResponseEntry = z.infer<typeof PromptResponseEntrySchema>;
+/**
+ * The whole config. Top-level is deliberately NON-strict (unknown keys stripped,
+ * not rejected) so the shipped seed can carry a `_comment` operator-note field
+ * without failing validation. Entries stay strict.
+ */
+export declare const PromptResponsesConfigSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"1">;
+    entries: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        frame_contains: z.ZodArray<z.ZodString>;
+        option_text: z.ZodString;
+        send: z.ZodString;
+        verify_contains: z.ZodOptional<z.ZodString>;
+        max_fires: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>>;
+}, z.core.$strip>;
+export type PromptResponsesConfig = z.infer<typeof PromptResponsesConfigSchema>;
+/** Inv-2 classification of a single entry's signature material. */
+export type SignatureClass = 'refuse' | 'warn' | 'ok';
+/**
+ * Classify an entry against the Inv-2 substring lists. `refuse` wins over `warn`
+ * (the destructive/trust list is checked first). Substring match is intentional
+ * and over-refuse-safe: better to reject a benignly-worded entry than to admit a
+ * dangerous one.
+ */
+export declare function classifyPromptSignature(entry: PromptResponseEntry): SignatureClass;
+/** One refused/warned entry + the substring that triggered the classification. */
+export interface ClassifiedEntry {
+    readonly entry: PromptResponseEntry;
+    readonly matched: string;
+}
+/**
+ * The result of loading + Inv-2-filtering a config: the `accepted` entries the
+ * watcher may act on (refused entries DROPPED per Inv 2 hard-refuse), plus the
+ * `refused` + `warned` lists so the caller can surface them loudly.
+ */
+export interface LoadedPromptResponses {
+    readonly accepted: readonly PromptResponseEntry[];
+    readonly refused: readonly ClassifiedEntry[];
+    readonly warned: readonly ClassifiedEntry[];
+}
+/**
+ * Validate + Inv-2-filter a parsed config object. Throws `PromptResponderError`
+ * on a schema-invalid shape (loud — never silently proceed on a malformed
+ * config). Refuse-classified entries are dropped from `accepted`; warn-classified
+ * entries stay in `accepted` (operator-owned risk) but are also listed in
+ * `warned`.
+ */
+export declare function loadPromptResponses(raw: unknown): LoadedPromptResponses;
+/**
+ * Prompt-like frame detector (Inv 1). A frame that matches no allowlist entry
+ * but LOOKS like an interactive prompt (a `❯` selector or a `(y/n)`-style
+ * confirmation) is the dangerous case: an unknown prompt we must NOT answer.
+ * Broad on purpose — false-positive (alert on a non-prompt) is cheap; a
+ * false-negative (miss a real unknown prompt) is the hazard.
+ */
+export declare function looksPromptLike(frame: string): boolean;
+/**
+ * Inv 3 binding: does `optionText` render on a menu line numbered `send`?
+ *
+ * For a numeric `send` (the common menu-ordinal case), the line containing
+ * `optionText` must, after stripping any leading selector glyph / whitespace
+ * (`❯ 1. …`), START with the `send` ordinal followed by a boundary — so a menu
+ * reorder that moves `optionText` to a differently-numbered line breaks the
+ * match. For a non-numeric `send` there is no ordinal to bind to, so presence of
+ * `optionText` is the binding (weaker; the seeds + realistic launch menus are
+ * numbered).
+ */
+export declare function optionOnSendLine(frame: string, optionText: string, send: string): boolean;
+/**
+ * Does the frame match this specific allowlist entry? All `frame_contains`
+ * present (Inv 1 identity + full-render gate) AND `option_text` present AND
+ * `option_text` on a line numbered `send` (Inv 3 binding).
+ */
+export declare function entryMatchesFrame(frame: string, entry: PromptResponseEntry): boolean;
+/** Outcome of matching a captured frame against the accepted allowlist. */
+export type MatchResult = {
+    readonly kind: 'match';
+    readonly entry: PromptResponseEntry;
+} | {
+    readonly kind: 'unknown-prompt';
+} | {
+    readonly kind: 'none';
+};
+/**
+ * Match a captured tmux frame against the accepted allowlist (Inv 1 + Inv 3).
+ * Returns the first matching entry; else `unknown-prompt` when the frame looks
+ * prompt-like (→ caller alerts, never answers); else `none` (no prompt / the
+ * agent's own output).
+ */
+export declare function matchPromptFrame(frame: string, entries: readonly PromptResponseEntry[]): MatchResult;
+/** Per-prompt fire cap (Inv operational guard): may this entry fire again? */
+export declare function canFire(entry: PromptResponseEntry, firedCount: number): boolean;
+/**
+ * Outcome verification after a send (DR-033 "verify the RIGHT outcome"):
+ *   - `not-cleared` — the same signature STILL matches: the send had no effect
+ *     (the RC typed-but-no-Enter hazard, silent-fallback Instance 3). Retry/alert.
+ *   - `wrong-outcome` — signature cleared BUT `verify_contains` (the expected
+ *     next-screen marker) is absent: a *wrong* answer also clears the prompt.
+ *   - `ok` — signature cleared AND `verify_contains` present.
+ *   - `weak-ok` — signature cleared, no `verify_contains` configured: the
+ *     watcher can only confirm clearance, not correctness (logged as weaker).
+ */
+export type VerifyResult = 'ok' | 'weak-ok' | 'not-cleared' | 'wrong-outcome';
+export declare function verifyOutcome(afterFrame: string, entry: PromptResponseEntry): VerifyResult;
+/**
+ * The canonical seed config `macf init` writes when no `prompt-responses.json`
+ * exists yet. Two ceremony-ack entries vetted to Inv 2 (neither signature
+ * contains a refuse/warn substring). The exact rendered text of a launch prompt
+ * can only be confirmed by an OPERATOR live-verify (the prompts don't render in
+ * `-p` mode), so a seed that doesn't exactly match a real prompt fails SAFE —
+ * the frame falls through to Inv 1 (unknown-prompt alert), never a wrong answer.
+ * Operators tune the exact `frame_contains` / `option_text` against the real
+ * pane, then the ceremony auto-clears.
+ */
+export declare const PROMPT_RESPONSES_SEED: PromptResponsesConfig;
+//# sourceMappingURL=prompt-responses.d.ts.map

package/dist/prompt-responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-responses.d.ts","sourceRoot":"","sources":["../src/prompt-responses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,8DAA8D;AAC9D,eAAO,MAAM,+BAA+B,EAAG,GAAY,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,+DAAgE,CAAC;AAEtG;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,oDAAqD,CAAC;AAEzF,uEAAuE;AACvE,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,yBAAyB;;;;;;;kBAS3B,CAAC;AACZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;iBAGtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,mEAAmE;AACnE,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;AAkBtD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,CAIlF;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CAwBvE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAgBzF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAMpF;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,mBAAmB,EAAE,GACtC,WAAW,CAKb;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,eAAe,CAAC;AAE9E,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,YAAY,CAM1F;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,qBAkBnC,CAAC"}