@mnemom/mnemom 0.17.34-next.1 → 0.17.34-next.3

package/dist/vendor/shared/durable-contract/admission.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Gateway admission for mnm_ds_ keys: one total pure function over the resolver's `durable`
+ * object plus the request pin and posture (design §3.6 steps 1-4; C06-R14/R15; C08-R13/R14;
+ * C09-R08/R11; C11-R33; rulings I03, I12, I20, r3 I01). Data, not branches, wherever possible:
+ * ADMISSION_PRECEDENCE is the order the oracle reads, and `admissionTruthTable()` enumerates the
+ * cross product the eval compares against.
+ *
+ * Precedence, first match wins:
+ *   1 unknown or invalid key            -> the baseline unknown-key answer for the path and mode
+ *   2 resolver fault or bad schema      -> 503 durable_admission_unavailable
+ *   3 key_state revoked                 -> 401 durable_key_revoked
+ *   4 pin absent or mismatched          -> 409 durable_identity_mismatch
+ *   5 durable_mode tracked              -> 410 durable_unlocked
+ *   6 effective terminal                -> 410 durable_session_ended {state, state_reason}
+ *   7 fenced (unless nofence)           -> 409 durable_lease_fenced
+ *   8 paused or non-admitting suspended -> 423 durable_session_stopped {state, state_reason}
+ *   9 posture: attended admits; unattended -> 503 durable_guard_unavailable on a guard fault,
+ *     else 503 durable_unattended_unavailable (M1 refuses all unattended work).
+ * The one exception (wave-0 fix ruling 22): a POST /v1/messages/count_tokens with no chain= (header
+ * absent, or no chain on the newest entry) runs steps 1-8 and skips step 9: it is admitted as
+ * admit_unchained, with no chain row and no posture insert. Every other request is unchanged.
+ * Hello transition: only an admitted attended request moves an effectively resuming session to
+ * running (helloTransition). admit_unchained never does and writes nothing (a resuming session
+ * stays resuming).
+ * The door (normalizeCellId(CELL_ID) vs home_cell) is diagnostic only in M1.
+ * An attended guard fault is admitted (today's behaviour) and reported (C08-R14).
+ */
+import type { GatewayRefusalCode } from "./codes.js";
+import { type EffectiveState, type SessionState, type StateReason } from "./states.js";
+import { type CanonicalCellId } from "./cell-id.js";
+export declare const KEY_STATES: readonly ["active", "revoked"];
+export type KeyState = (typeof KEY_STATES)[number];
+export declare const POSTURES: readonly ["attended", "unattended"];
+export type Posture = (typeof POSTURES)[number];
+export declare const EXECUTOR_KINDS: readonly ["host", "fleet", "container"];
+export type ExecutorKind = (typeof EXECUTOR_KINDS)[number];
+export declare const OUTAGE_MODES: readonly ["stop", "continue"];
+/** Field types of the resolver's `durable` object (the per-field schema, C06-R15). */
+export type FieldType = "uuid" | "string" | "boolean" | "integer" | "timestamp" | "object" | "enum";
+export interface FieldSpec {
+    readonly type: FieldType;
+    readonly nullable: boolean;
+    /** For enum fields: the closed value set. */
+    readonly values?: readonly string[];
+    /** What null means, for a nullable field. */
+    readonly nullMeans?: string;
+}
+/**
+ * The resolver per-field schema. A missing field, wrong type, unknown enum value, or null on a
+ * non-nullable field is a schema fault: 503 durable_admission_unavailable, never a throw.
+ */
+export declare const RESOLVER_SCHEMA: Readonly<Record<string, FieldSpec>>;
+export interface ResolverDurable {
+    key_state: KeyState;
+    session_id: string;
+    aip_session_id: string;
+    durable_mode: "tracked" | "locked";
+    state: SessionState;
+    effective_state: EffectiveState;
+    state_reason: StateReason | null;
+    epoch: number;
+    fenced: boolean;
+    agent_id: string;
+    home_cell: CanonicalCellId;
+    posture: Posture | null;
+    executor_kind: ExecutorKind;
+    host_unattended: boolean;
+    unattended_enabled: boolean;
+    grant_live: boolean;
+    expires_at: string | null;
+    lease_expires_at: string | null;
+    lease_executor_id: string | null;
+    attach_until: string | null;
+    attach_live: boolean | null;
+    sealed: boolean;
+    outage_mode: "stop" | "continue" | null;
+    charter_hash: string | null;
+    guard_state: Record<string, unknown> | null;
+    has_pointer: boolean;
+}
+/** One resolver field against its spec (pure; exported for its direct test). */
+export declare function fieldOk(spec: FieldSpec, v: unknown): boolean;
+/**
+ * Validate a resolver answer. Returns the typed object, or null for any schema fault (missing
+ * field, wrong type, unknown enum, null on non-nullable, an illegal state_reason for the state, an
+ * effective state the derivation cannot produce, or a locked row with no charter).
+ */
+export declare function parseResolverDurable(raw: unknown): ResolverDurable | null;
+/** Whether a locked session's guard_state is usable (C08-R13): an object carrying numeric spend_usd. */
+export declare function guardStateOk(guard: Record<string, unknown> | null): boolean;
+/**
+ * Canonical guard_state fixtures for the case datasets (`$S1.GUARD_STATE_OK` / `$S1.GUARD_STATE_FAULT`,
+ * written as jsonb): OK passes guardStateOk; FAULT is a present object of the wrong shape (spend_usd
+ * not a number), the C08-R13 / claim check 7 fault, never null so it exercises the shape check.
+ */
+export declare const GUARD_STATE_OK: Readonly<{
+    spend_usd: number;
+}>;
+export declare const GUARD_STATE_FAULT: Readonly<{
+    spend_usd: string;
+}>;
+/** Whether DURABLE_ADMIT is honoured: only the exact bytes "nofence" (NOFENCE_M1, r3 I01). */
+export declare function nofenceHonoured(durableAdmit: string | undefined): boolean;
+export type AdmissionStep = "unknown_key" | "resolver_fault" | "revoked" | "identity" | "tracked" | "terminal" | "fenced" | "stopped" | "posture" | "admit";
+/** The order the oracle reads (C11-R33). */
+export declare const ADMISSION_PRECEDENCE: readonly AdmissionStep[];
+export declare const ADMISSION_STEP_CODE: {
+    readonly [S in Exclude<AdmissionStep, "unknown_key" | "posture" | "admit">]: GatewayRefusalCode;
+};
+/** Persisted or effective states that admit an attended chain (design §3.6 step 4 table). */
+export declare function attendedAdmits(effective: EffectiveState, reason: StateReason | null): boolean;
+export type FenceSource = "fresh" | "nofence";
+/** The count_tokens route (wave-0 fix ruling 22), path without a query string, as the proxy sends it upstream. */
+export declare const COUNT_TOKENS_PATH = "/v1/messages/count_tokens";
+/** The same route at the gateway door (provider-prefixed). */
+export declare const GATEWAY_COUNT_TOKENS_PATH = "/anthropic/v1/messages/count_tokens";
+/** Whether a path (no query string) is the count_tokens route, bare or at the gateway door. */
+export declare function isCountTokensPath(path: string): boolean;
+/** The request facts admission needs beyond the key (wave-0 fix ruling 22). */
+export interface AdmissionRequest {
+    method: string;
+    /** The request path without a query string. */
+    path: string;
+    /** Whether a chain= element was sent on the newest x-mnemom-turn entry (false: header absent or no chain). */
+    chain: boolean;
+}
+/** Whether a request skips the posture step: POST /v1/messages/count_tokens with no chain (ruling 22). */
+export declare function isUnchainedCountTokens(r: AdmissionRequest): boolean;
+export interface AdmissionInput {
+    /** null: no row for the key hash (unknown or invalid key). "fault": resolver down, hung, 5xx, PGRST202 or malformed. */
+    resolver: unknown;
+    /** x-mnemom-agent-id as sent (null when absent). */
+    pinAgentId: string | null;
+    /** The chain posture the resolver returned, else the candidate (unknown = unattended). */
+    posture: Posture | null;
+    durableAdmit: string | undefined;
+    /** The request (ruling 22). Absent: decided as any request other than an unchained count_tokens. */
+    request?: AdmissionRequest;
+}
+export type AdmissionVerdict = {
+    kind: "baseline_unknown_key";
+    step: "unknown_key";
+} | {
+    kind: "refuse";
+    step: Exclude<AdmissionStep, "unknown_key" | "admit">;
+    code: GatewayRefusalCode;
+    state?: SessionState;
+    state_reason?: string | null;
+    posture: Posture;
+    fenceSource: FenceSource;
+} | {
+    kind: "admit";
+    step: "admit";
+    posture: "attended";
+    guardFault: boolean;
+    fenceSource: FenceSource;
+    /** True when the session is effectively resuming: this request moves it to running. */
+    helloTransition: boolean;
+} | {
+    /** Ruling 22: an unchained count_tokens passed steps 1-8; the gateway writes no chain row and no posture.
+     * Its response arm is m1Arm(durableAdmit, "none") (ruling 22.1). */
+    kind: "admit_unchained";
+    step: "admit";
+    posture: null;
+    guardFault: boolean;
+    fenceSource: FenceSource;
+    /** Never: a resuming session stays resuming. */
+    helloTransition: false;
+    /** The gateway writes nothing for it (no chain row, no posture, no state change). */
+    writes: false;
+};
+export declare const RESOLVER_FAULT: "fault";
+/** The admission function. Total: every input maps to exactly one verdict; it never throws. */
+export declare function admit(input: AdmissionInput): AdmissionVerdict;
+export declare const ADMISSION_REQUEST_KINDS: readonly ["standard", "count_tokens_unchained"];
+export type AdmissionRequestKind = (typeof ADMISSION_REQUEST_KINDS)[number];
+export interface TruthRow {
+    state: SessionState;
+    state_reason: StateReason | null;
+    effective_state: EffectiveState;
+    fenced: boolean;
+    key_state: KeyState;
+    durable_mode: "tracked" | "locked";
+    posture: Posture;
+    guard_ok: boolean;
+    nofence: boolean;
+    pin: "match" | "absent" | "mismatch";
+    /** standard: any request but an unchained count_tokens; count_tokens_unchained: ruling 22. */
+    request: AdmissionRequestKind;
+    /** Whether the request moves the session from resuming to running (an attended admit only). */
+    hello_transition: boolean;
+    /** "admit", "admit_unchained", "baseline_unknown_key" or the refusal code. */
+    outcome: string;
+    status: number | null;
+}
+/** HTTP status of a truth-table outcome (null = the baseline unknown-key answer); throws on an unknown outcome. */
+export declare function admissionStatusOf(outcome: string): number | null;
+/** A well-formed resolver object for a row of the truth table. */
+export declare function fixtureResolver(over?: Partial<ResolverDurable>): ResolverDurable;
+/** Every (persisted state, reason) pair, with its persisted effective state and the derived ones. */
+export declare function stateRows(): {
+    state: SessionState;
+    state_reason: StateReason | null;
+    effective_state: EffectiveState;
+}[];
+/** The full cross product over the admission dimensions, each row decided by `admit`. */
+export declare function admissionTruthTable(): TruthRow[];
+/** Golden vectors: a 3-dim toy sweep (every line) and C06 SWEEP_A (count, first 3 lines, digest). */
+export declare const ADMIT_SWEEP_VECTORS_PATH = "src/vectors/admit-sweep-vectors.json";
+/**
+ * A pure admission sweep as the C06 case passes it: `dims` is an ORDERED array (an object's key
+ * order does not survive canonicalisation, so it is refused). Each dimension names a resolver or
+ * request input in the C06 case vocabulary; see ADMIT_SWEEP_VALUES.
+ */
+export interface AdmitSweep {
+    readonly name: string;
+    readonly dims: readonly {
+        readonly name: string;
+        readonly values: readonly unknown[];
+    }[];
+}
+/**
+ * The closed value set of each C06 sweep dimension (gen/fam-a.mjs SWEEP_A / SWEEP_B vocabulary).
+ * A null on a non-nullable resolver field reaches admit() as that null (a schema fault, 503).
+ * stored_state is "state" or "state:reason" ("null" for a NULL reason), state a SESSION_STATES value.
+ */
+export declare const ADMIT_SWEEP_VALUES: Readonly<Record<string, readonly unknown[]>>;
+/**
+ * The sweep's verdict text: an odometer over `dims` (first entry slowest, values in array order),
+ * one sweepLine per tuple, each followed by LF (also after the last). Throws on a bad sweep.
+ */
+export declare function admitSweepText(sweep: AdmitSweep): {
+    tuples: number;
+    text: string;
+};
+/** verdicts_sha256: lowercase hex sha256 of the UTF-8 bytes of admitSweepText(sweep).text. */
+export declare function admitSweepDigest(sweep: AdmitSweep): Promise<{
+    tuples: number;
+    verdicts_sha256: string;
+}>;