instar 1.3.800 → 1.3.802

package/dist/monitoring/selfaction/anchor.d.ts

@@ -0,0 +1,82 @@
+/**
+ * selfaction/anchor.ts — the PROCESS-GLOBAL anchor + single-mint registry
+ * (companion §5.3, spec ADV8-1/ADV9-1).
+ *
+ * The mint registry AND the admission-state anchor live behind ONE
+ * `Symbol.for('instar.selfActionGovernor')` key on `globalThis`, storing a
+ * MINIMAL claim surface (never raw mutable maps). An accidental
+ * dual-package/duplicated-dist load duplicates the whole module graph — a
+ * module-scoped registry would see one clean claim per copy and guard nothing
+ * in exactly its named case; the global key makes cross-copy claims COLLIDE
+ * and shares ONE admission state so two copies can never run independent
+ * full-budget counters or clobber the durable snapshot as uncoordinated
+ * writers.
+ *
+ * Lifecycle: INIT-ONCE — the first claimant initializes, rehydrates, and owns
+ * the single flush loop; a later claimant ATTACHES read-write, never
+ * re-initializes, never starts a second flusher. A duplicate
+ * `governor.for(id)` mint fails LOUDLY: controller-scoped errored posture
+ * (never process-fatal) + a `mint-collision` audit row; the losing claimant's
+ * dead handles resolve through the per-class fail direction.
+ *
+ * Test lifecycle (SC9-1): under vitest each module graph gets a graph-LOCAL
+ * anchor by default (so unrelated test files never collide on a worker-shared
+ * globalThis), and the mandated bounce/dual-load fixtures OPT IN to a shared
+ * key via the key-salt override so they can exercise the collision + attach
+ * cases within one process.
+ */
+/** Test fixtures set `(globalThis as any)[Symbol.for(KEY_SALT_OVERRIDE)] = 'salt'`
+ *  to force two freshly-imported module copies onto ONE shared anchor. */
+export declare const KEY_SALT_OVERRIDE = "instar.selfActionGovernor.keySaltOverride";
+/**
+ * The MINIMAL claim surface stored behind the global key. Deliberately not the
+ * governor's raw maps: the anchor exposes claim/attach/mint bookkeeping plus
+ * ONE opaque shared-state slot the initializing claimant owns.
+ */
+export interface GovernorAnchor {
+    /** Monotonic claim generation (attach epochs). */
+    generation: number;
+    /** Whether an initializing claimant exists (owns rehydrate + flush loop). */
+    initialized: boolean;
+    /** Set of controller ids already minted (single-mint registry). */
+    mintedControllerIds: Set<string>;
+    /** Controller ids whose duplicate mint collided (dead-handle posture). */
+    collidedControllerIds: Set<string>;
+    /** The shared runtime state slot (owned by the first claimant; attached
+     *  read-write by later claimants). Opaque here by design. */
+    sharedState: unknown;
+    /** Collision callback (installed by the initializing claimant so a losing
+     *  mint from ANY copy lands one audit row). */
+    onMintCollision?: (controllerId: string) => void;
+}
+/** Get-or-create the anchor behind the process-global key. */
+export declare function getAnchor(): GovernorAnchor;
+export type MintResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'mint-collision';
+};
+/**
+ * Single-mint per controller id, process-global. A second mint of the SAME id
+ * (dual-load, copy-pasted marker file) COLLIDES: the second claimant's handle
+ * is DEAD (controller-scoped errored posture — never process-fatal).
+ */
+export declare function mintController(controllerId: string): MintResult;
+/**
+ * Claim the shared-state slot. INIT-ONCE: the first claimant provides the
+ * initializer and OWNS the flush loop; later claimants ATTACH to the existing
+ * state (never re-initialize, never start a second flusher).
+ */
+export declare function claimSharedState<T>(init: () => T): {
+    state: T;
+    role: 'initialized' | 'attached';
+};
+/**
+ * Test-only dispose/reset (SC9-1). Releases the anchor (mints + shared state)
+ * so fixtures can re-instantiate within one process. Refuses outside a test
+ * environment unless `force` — production code must never reset the anchor
+ * (that would hand a runaway loop a fresh mint + budget surface).
+ */
+export declare function resetAnchorForTest(force?: boolean): void;
+//# sourceMappingURL=anchor.d.ts.map

package/dist/monitoring/selfaction/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../src/monitoring/selfaction/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH;0EAC0E;AAC1E,eAAO,MAAM,iBAAiB,8CAA8C,CAAC;AAkB7E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,mEAAmE;IACnE,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,0EAA0E;IAC1E,qBAAqB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnC;iEAC6D;IAC7D,WAAW,EAAE,OAAO,CAAC;IACrB;mDAC+C;IAC/C,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,IAAI,cAAc,CAe1C;AAED,MAAM,MAAM,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAa/D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAA;CAAE,CAUjG;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,UAAQ,GAAG,IAAI,CAOtD"}

package/dist/monitoring/selfaction/anchor.js

@@ -0,0 +1,113 @@
+/**
+ * selfaction/anchor.ts — the PROCESS-GLOBAL anchor + single-mint registry
+ * (companion §5.3, spec ADV8-1/ADV9-1).
+ *
+ * The mint registry AND the admission-state anchor live behind ONE
+ * `Symbol.for('instar.selfActionGovernor')` key on `globalThis`, storing a
+ * MINIMAL claim surface (never raw mutable maps). An accidental
+ * dual-package/duplicated-dist load duplicates the whole module graph — a
+ * module-scoped registry would see one clean claim per copy and guard nothing
+ * in exactly its named case; the global key makes cross-copy claims COLLIDE
+ * and shares ONE admission state so two copies can never run independent
+ * full-budget counters or clobber the durable snapshot as uncoordinated
+ * writers.
+ *
+ * Lifecycle: INIT-ONCE — the first claimant initializes, rehydrates, and owns
+ * the single flush loop; a later claimant ATTACHES read-write, never
+ * re-initializes, never starts a second flusher. A duplicate
+ * `governor.for(id)` mint fails LOUDLY: controller-scoped errored posture
+ * (never process-fatal) + a `mint-collision` audit row; the losing claimant's
+ * dead handles resolve through the per-class fail direction.
+ *
+ * Test lifecycle (SC9-1): under vitest each module graph gets a graph-LOCAL
+ * anchor by default (so unrelated test files never collide on a worker-shared
+ * globalThis), and the mandated bounce/dual-load fixtures OPT IN to a shared
+ * key via the key-salt override so they can exercise the collision + attach
+ * cases within one process.
+ */
+const GLOBAL_KEY = 'instar.selfActionGovernor';
+/** Test fixtures set `(globalThis as any)[Symbol.for(KEY_SALT_OVERRIDE)] = 'salt'`
+ *  to force two freshly-imported module copies onto ONE shared anchor. */
+export const KEY_SALT_OVERRIDE = 'instar.selfActionGovernor.keySaltOverride';
+/** Module-LOCAL fallback symbol — unique per module graph (test isolation). */
+const MODULE_LOCAL_KEY = Symbol('instar.selfActionGovernor.moduleLocal');
+function isTestEnv() {
+    return Boolean(process.env.VITEST || process.env.NODE_ENV === 'test');
+}
+function anchorKey() {
+    const salt = globalThis[Symbol.for(KEY_SALT_OVERRIDE)];
+    if (typeof salt === 'string' && salt.length > 0) {
+        return Symbol.for(`${GLOBAL_KEY}:${salt}`);
+    }
+    if (isTestEnv())
+        return MODULE_LOCAL_KEY;
+    return Symbol.for(GLOBAL_KEY);
+}
+/** Get-or-create the anchor behind the process-global key. */
+export function getAnchor() {
+    const key = anchorKey();
+    const g = globalThis;
+    let anchor = g[key];
+    if (!anchor) {
+        anchor = {
+            generation: 0,
+            initialized: false,
+            mintedControllerIds: new Set(),
+            collidedControllerIds: new Set(),
+            sharedState: null,
+        };
+        g[key] = anchor;
+    }
+    return anchor;
+}
+/**
+ * Single-mint per controller id, process-global. A second mint of the SAME id
+ * (dual-load, copy-pasted marker file) COLLIDES: the second claimant's handle
+ * is DEAD (controller-scoped errored posture — never process-fatal).
+ */
+export function mintController(controllerId) {
+    const anchor = getAnchor();
+    if (anchor.mintedControllerIds.has(controllerId)) {
+        anchor.collidedControllerIds.add(controllerId);
+        try {
+            anchor.onMintCollision?.(controllerId);
+        }
+        catch {
+            /* collision reporting must never throw into a module-scope mint */
+        }
+        return { ok: false, reason: 'mint-collision' };
+    }
+    anchor.mintedControllerIds.add(controllerId);
+    return { ok: true };
+}
+/**
+ * Claim the shared-state slot. INIT-ONCE: the first claimant provides the
+ * initializer and OWNS the flush loop; later claimants ATTACH to the existing
+ * state (never re-initialize, never start a second flusher).
+ */
+export function claimSharedState(init) {
+    const anchor = getAnchor();
+    anchor.generation += 1;
+    if (anchor.initialized && anchor.sharedState !== null) {
+        return { state: anchor.sharedState, role: 'attached' };
+    }
+    const state = init();
+    anchor.sharedState = state;
+    anchor.initialized = true;
+    return { state, role: 'initialized' };
+}
+/**
+ * Test-only dispose/reset (SC9-1). Releases the anchor (mints + shared state)
+ * so fixtures can re-instantiate within one process. Refuses outside a test
+ * environment unless `force` — production code must never reset the anchor
+ * (that would hand a runaway loop a fresh mint + budget surface).
+ */
+export function resetAnchorForTest(force = false) {
+    if (!isTestEnv() && !force) {
+        throw new Error('resetAnchorForTest is test-only (set force to override deliberately)');
+    }
+    const key = anchorKey();
+    const g = globalThis;
+    delete g[key];
+}
+//# sourceMappingURL=anchor.js.map

package/dist/monitoring/selfaction/anchor.js.map

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

package/dist/monitoring/selfaction/governor.d.ts

@@ -0,0 +1,242 @@
+/**
+ * selfaction/governor.ts — the SelfActionGovernor runtime primitive
+ * (Increment B of docs/specs/unified-self-action-backpressure.md; the
+ * normative companion `unified-self-action-backpressure.companion.md` is the
+ * implementation authority).
+ *
+ * ONE in-process chokepoint every self-triggered, cost- or disruption-bearing
+ * action passes through to acquire permission to fire, keyed on a controller
+ * id. Ships OBSERVE-ONLY on every class, fleet-dark per the FD1 ladder: in
+ * observe mode admit() records would-verdicts and ALWAYS allows; no
+ * enforcement behavior is live by default. The enforce flip is the operator's
+ * per-class action later (FD8), gated by FD12 — and for pool-shared classes
+ * additionally by FD9/FD15 (this increment never enforces pool-shared with
+ * registered machine count > 1).
+ *
+ * This IS the governor module — it rides the usage-scan lint's SELF-SCOPE
+ * allowlist (companion INT9-2), never a controller marker.
+ */
+import type { ActionRef, Admission, AdmissionToken, AdmitOpts, DerivedTarget, GovernorAttentionItem, GovernorClassMode, GovernorClassPosture, PressureReading, PrincipalSurface, TransitionRow, TransitionRowType } from './types.js';
+export interface SelfActionGovernorDeps {
+    /** Agent state dir (durable snapshot + aggregates live under it). */
+    stateDir: string;
+    /** LIVE read of `intelligence.selfActionGovernor.emergencyDisable` — an
+     *  in-memory read (the PATCH /config route updates the runtime config), so
+     *  admitSync stays zero-I/O. */
+    readEmergencyDisable: () => boolean;
+    /** LIVE read of the sparse per-class overrides block (`...classes`). Read
+     *  once at init + on the slow tick — never per-admit. */
+    readClassesConfig: () => unknown;
+    /** Governor-owned census source — INDEPENDENT of any governed controller's
+     *  candidate enumeration (spec SC6-1(iii)). Sampled OFF the hot path. */
+    readCensus?: () => PressureReading | null;
+    /** Configured session cap (censusAbsoluteMax tighten input). */
+    configuredSessionCap?: () => number | undefined;
+    /** REGISTERED machine count (FD9 level gate) — re-evaluated on the slow
+     *  tick, never per-admit. */
+    registeredMachineCount?: () => number;
+    /** P17 funnel seam — the ONLY path for operator notices. */
+    emitAttention?: (item: GovernorAttentionItem) => void | Promise<void>;
+    now?: () => number;
+    /** Flush cadence (default 60s). */
+    flushIntervalMs?: number;
+    /** Token TTL (default 60s). */
+    tokenTtlMs?: number;
+}
+export declare class SelfActionGovernorCore {
+    private readonly state;
+    readonly role: 'initialized' | 'attached';
+    constructor();
+    /**
+     * INIT-ONCE (companion §5.3): the FIRST initializer rehydrates the durable
+     * snapshot and owns the single flush loop; a later init call ATTACHES —
+     * never re-initializes, never starts a second flusher.
+     */
+    init(deps: SelfActionGovernorDeps): 'initialized' | 'attached';
+    /** Graceful shutdown — flush + stop the flusher (FD14 graceful-shutdown flush). */
+    dispose(): void;
+    private now;
+    private nowIso;
+    private loadPolicies;
+    /** FD9 level gate: a pool-shared class may not ENFORCE when the REGISTERED
+     *  machine count > 1 (no pool-wide ceiling in this increment). Evaluated on
+     *  the slow tick / registration change — never per-admit. */
+    private applyPoolShareGate;
+    /**
+     * Mint the per-controller handle — module scope, once per controller file.
+     * A duplicate mint (dual-load / copy-pasted marker) yields a DEAD handle
+     * whose admits resolve through the per-class fail direction, loudly.
+     */
+    for(controllerId: string): SelfActionHandle;
+    /** Cache guard so a per-admit live read can never become per-admit I/O
+     *  (the injected reader may consult a disk-backed liveConfig). */
+    private disableReadCache;
+    private emergencyDisabled;
+    private onDisableFlip;
+    admitFor(controllerId: string, dead: boolean, target: DerivedTarget, opts?: AdmitOpts): Admission;
+    private classFor;
+    /** Test seam: force the NEXT evaluations for a controller to throw (the
+     *  fail-matrix fixtures need a genuinely-throwing admit path). */
+    private readonly throwOnAdmit;
+    setThrowOnAdmitForTest(controllerId: string, on: boolean): void;
+    /** The policy evaluation — the WOULD-verdict machinery (all modes). */
+    private evaluate;
+    /** Map a policy deny to the three-way disposition per mode + class shape. */
+    private nonAllow;
+    /** Fail matrix (companion §6): the disposition when admit() itself THROWS. */
+    private failDisposition;
+    private enqueue;
+    /** Failure-minimal enqueue (spec SC5-3): no policy evaluation, no I/O; a
+     *  double failure is an AUDITED drop folded into the dead-letter notice as
+     *  the `enqueue-drop` class. */
+    private minimalEnqueue;
+    private retryAfter;
+    /**
+     * Drain: re-admit + re-project + re-run the controller's eligibility
+     * predicate + incarnation-fence check. BOTH-unavailable = audited drop.
+     * Fairness: interactive before jobs, FIFO within (age-based promotion).
+     */
+    drainQueues(nowMs?: number): void;
+    /** Drain-time fence check used by retrofit sites that re-derive targets. */
+    fenceMatches(queued: string | undefined, current: string | undefined): boolean;
+    private recordShed;
+    private allow;
+    /**
+     * Runtime consume-once at the protected sink — the AUTHORITY (FD6/CX4).
+     * The sink pins its expected controllerId module-side; a token minted for
+     * any other controller is rejected. In OBSERVE mode a rejection is recorded
+     * but the sink PROCEEDS (signal-only — observe never blocks); in ENFORCE
+     * mode `proceed: false`.
+     */
+    consumeToken(token: AdmissionToken | null | undefined, expectedControllerId: string, opts?: {
+        targetKey?: string;
+        nowMs?: number;
+    }): {
+        proceed: boolean;
+        valid: boolean;
+        reason?: string;
+    };
+    /**
+     * Privileged, SEPARATE API — importable ONLY by the enumerated
+     * provenance-setting modules (lint-enforced). ALWAYS allow + per-admit
+     * audit row (the ONE deliberate per-event carve-out); NEVER paced — exempt
+     * from ceilings, the errored path, and the last-resort floor. A throwing
+     * principalAdmit resolves OPEN.
+     */
+    principalAdmit(surface: PrincipalSurface, action: ActionRef): Admission;
+    private countPrincipal;
+    private rollWindow;
+    private windowCount;
+    private recordAdmit;
+    /** Evict ONLY settled/expired per-target entries (never an active
+     *  at-ceiling entry — spec SC-m3). Returns true when a slot was freed. */
+    private evictSettled;
+    private refillRate;
+    private safeProjection;
+    /** Sample the census OFF the hot path (slow tick / window roll consumer). */
+    sampleCensus(nowMs?: number): void;
+    private recomputeReliefCeiling;
+    private safeSessionCap;
+    private openErroredEpisode;
+    private closeErroredEpisode;
+    /** Rate-bounded errored audit: first-N verbatim per episode, then aggregated. */
+    private auditErrored;
+    /** Latched relief demote (rate-relaxation loss). Alarm ONLY on heal
+     *  EXHAUSTION (N failed clean cooldowns) — transient cycles are audit-only. */
+    demoteReliefClass(controllerId: string, nowMs?: number): void;
+    /** Clean-cooldown re-promotion — the self-heal; audit-only (P22). */
+    repromoteReliefClass(controllerId: string, nowMs?: number): void;
+    private checkObserveLimbo;
+    private bump;
+    private audit;
+    auditRow(type: TransitionRowType, controllerId?: string, detail?: string): void;
+    private notify;
+    private snapshotPath;
+    private aggregatesPath;
+    private auditPath;
+    private eagerFlush;
+    /** The flush BARRIER for governor-process-killing actions (FD14). */
+    flushBarrier(): void;
+    flushSnapshot(clean: boolean): void;
+    flushAudit(): void;
+    private rehydrate;
+    private applyConservativePosture;
+    private slowTick;
+    /** Test seam: run one slow tick deterministically. */
+    runSlowTickForTest(): void;
+    /** Scrubbed, LOCK-FREE posture read (no target identities, no absolute
+     *  quota values — spec SEC6; the /test-runner-limiter PURE-read precedent). */
+    getPosture(): {
+        emergencyDisable: boolean;
+        initialized: boolean;
+        classes: GovernorClassPosture[];
+    };
+    /** Coherence-advert accessor (companion §10b): per-class scalar mode for
+     *  pool-shared classes, read LIVE from governor runtime state. */
+    getClassMode(controllerId: string): GovernorClassMode;
+    /** GuardRegistry runtime getter (enabled = emergencyDisable !== true).
+     *  Deliberately does NOT report observe-only as `dryRun`: the governor's
+     *  guard job — registration + measurement + kill-switch visibility — IS
+     *  live in observe mode; per-class enforce is the separate FD8/FD12 ladder
+     *  with its own observe-limbo loop-closer, so painting the whole guard
+     *  on-dry-run would manufacture a permanent loadBearingGap against the
+     *  spec's designed observe-first rollout. */
+    guardRuntimeStatus(): {
+        enabled: boolean;
+        lastTickAt: number;
+    };
+    /** Test seam: set a class's mode directly (enforce-path coverage — an
+     *  observe soak cannot certify machinery it never exercises; spec A7). */
+    setModeForTest(controllerId: string, mode: GovernorClassMode): void;
+    /** Test seam: force a breaker open. */
+    openBreakerForTest(controllerId: string, untilMs: number): void;
+    /** Read the buffered (unflushed) audit rows — test/inspection seam. */
+    peekAuditBuffer(): readonly TransitionRow[];
+    /** Test seam: ALL audit rows — the in-memory buffer PLUS any flushed file
+     *  rows (a slow tick flushes the buffer; assertions must not race that). */
+    readAllAuditRowsForTest(): TransitionRow[];
+}
+/**
+ * Per-controller handle minted once at registration. Ordinary handles CANNOT
+ * express `origin: 'principal'` — they stamp 'self' unconditionally (the
+ * privileged lane is `governor.principalAdmit`, a separate API).
+ */
+export declare class SelfActionHandle {
+    private readonly core;
+    readonly controllerId: string;
+    private readonly dead;
+    constructor(core: SelfActionGovernorCore, controllerId: string, dead: boolean);
+    /** Async admission (classes that may touch cross-process CAS later). */
+    admit(target: DerivedTarget, opts?: AdmitOpts): Promise<Admission>;
+    /** Zero-I/O synchronous admission (notify/age-kill-class hot paths). */
+    admitSync(target: DerivedTarget, opts?: AdmitOpts): Admission;
+    /** True when this handle lost a mint collision (dead-handle posture). */
+    isDead(): boolean;
+}
+/**
+ * The governor module surface. Emit sites hold `const gov = governor.for(id)`
+ * at module scope (raw string admit at emit sites is LINT-FORBIDDEN).
+ */
+export declare const governor: {
+    for(controllerId: string): SelfActionHandle;
+    /** Privileged principal lane — import-restricted by the usage-scan lint. */
+    principalAdmit(surface: PrincipalSurface, action: ActionRef): Admission;
+};
+/** Server-boot initialization (INIT-ONCE; later callers attach). */
+export declare function initSelfActionGovernor(deps: SelfActionGovernorDeps): SelfActionGovernorCore;
+/** The live core (route/advert/guard read surfaces). */
+export declare function getSelfActionGovernor(): SelfActionGovernorCore;
+/** Sink-side consume (FD6 — the runtime authority). Sinks pin their expected
+ *  controllerId module-side. */
+export declare function consumeAdmissionToken(token: AdmissionToken | null | undefined, expectedControllerId: string, opts?: {
+    targetKey?: string;
+    nowMs?: number;
+}): {
+    proceed: boolean;
+    valid: boolean;
+    reason?: string;
+};
+/** Test-only: drop the module-level core so a fixture can re-instantiate
+ *  (pairs with anchor.resetAnchorForTest — SC9-1). */
+export declare function resetSelfActionGovernorModuleForTest(): void;
+//# sourceMappingURL=governor.d.ts.map

package/dist/monitoring/selfaction/governor.d.ts.map

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