instar 1.3.747 → 1.3.749

package/dist/core/machineCoherenceManifest.d.ts

@@ -0,0 +1,133 @@
+/**
+ * machineCoherenceManifest.ts — the coherence-critical manifest (spec §3.1).
+ *
+ * A fleet-uniform, code-shipped catalog of the flags/versions whose skew across
+ * an agent's OWN machines silently halves a cross-machine guarantee (the F4
+ * incident class). The manifest ships ATOMIC with the code — every machine on
+ * version V evaluates the SAME set — so a key present on one side only is
+ * VERSION skew (already alarmed by the version dimension), never phantom flag
+ * skew. Spec: docs/specs/machine-coherence-guard.md §3.1/§3.3.
+ *
+ * Purity contract: this module is pure + deterministic (no I/O, no clock, no
+ * LLM). The evaluator (MachineCoherenceSentinel) and the advert builder both
+ * consume it; the manifest-size ratchet + membership-drift guard (§3.1 "N5")
+ * are unit tests over the exports here.
+ *
+ * Faithful elaborations of the spec's §3.1 interface sketch (documented, not
+ * silent — see the side-effects artifact):
+ *   - `dryRunConfigPath?` — the spec's `resolution: 'dev-gate+dryRun'` (and the
+ *     "(+ dryRun)" raw rows) inherently need to know WHERE the dry-run flag
+ *     lives; the sketch omitted it. It is folded into the effective value.
+ *   - The F4 pair (`ws13PinReplicate` + `ws13Reconcile`) is TWO independent
+ *     entries sharing one guarantee line, so each key is compared on its own —
+ *     strictly finer-grained than a compound row, never coarser.
+ */
+/** How the effective value is computed. */
+export type CoherenceResolution = 'raw' | 'dev-gate' | 'dev-gate+dryRun';
+/** Where a manifest entry's REAL consumer reads its input from (spec §3.1 M8). */
+export type CoherenceReadSource = 'boot' | 'live';
+export interface CoherenceCriticalFlag {
+    /** Stable key, e.g. 'seamlessness.ws13PinReplicate'. */
+    key: string;
+    /** Dotted config path to the entry's input value. */
+    configPath: string;
+    /** How the effective value is computed. */
+    resolution: CoherenceResolution;
+    /**
+     * Dotted config path to the dry-run flag folded into the effective value.
+     * Present for every `dev-gate+dryRun` entry and for the "(+ dryRun)" raw
+     * rows. Absent → dry-run is not a dimension for this key.
+     */
+    dryRunConfigPath?: string;
+    /**
+     * Where the entry's REAL consumer reads it from (spec §3.1 M8): 'boot' = the
+     * boot-time config object (a change needs a restart to take effect) | 'live'
+     * = liveConfig (a PATCH /config changes behavior with NO restart, e.g.
+     * sessionPool.stage). The resolver MUST read each entry the way its real
+     * consumer does, or the advert lies about effective behavior.
+     */
+    readSource: CoherenceReadSource;
+    /** One line: the cross-machine guarantee a mixed pool halves (alarm body). */
+    guarantee: string;
+}
+/**
+ * The 7 WS2 replicated stores whose per-store `enabled` (+ dryRun) is
+ * coherence-critical (replicated-memory reach: a non-advertising peer silently
+ * drops the kind). Shipped as a CODE constant, NOT config-derived, so the
+ * manifest is fleet-uniform (a fleet config with no stateSync block still
+ * carries all 7 rows — same set on every machine at version V).
+ */
+export declare const COHERENCE_STATE_SYNC_STORES: readonly ["preferences", "relationships", "learnings", "knowledge", "evolutionActions", "userRegistry", "topicOperator"];
+/**
+ * COHERENCE_CRITICAL_FLAGS — the manifest (spec §3.1 table). Fleet-uniform,
+ * code-shipped. Order is stable (drives manifestHash determinism after sort).
+ */
+export declare const COHERENCE_CRITICAL_FLAGS: CoherenceCriticalFlag[];
+/**
+ * Explicit membership-exclusion list (spec §3.1 "N5" membership drift guard):
+ * every `multiMachine.*` DEV_GATED_FEATURES entry not in the manifest must be
+ * named here with a one-line reason. Adding a new coherence-relevant dev-gated
+ * flag without a manifest decision fails the drift-guard build test — the F4
+ * class cannot be silently re-created for future flags.
+ */
+export interface CoherenceManifestExclusion {
+    configPath: string;
+    reason: string;
+}
+export declare const COHERENCE_MANIFEST_EXCLUSIONS: CoherenceManifestExclusion[];
+export declare const MC_MAX_ENTRIES = 64;
+export declare const MC_KEY_MAX = 64;
+export declare const MC_VALUE_MAX = 32;
+/** fixed-fields + flags portion of the advert, serialized. */
+export declare const MC_FLAGS_BYTES_MAX = 2048;
+/** the §3.2 alarm marker sub-budget. */
+export declare const MC_MARKER_BYTES_MAX = 1536;
+/** whole coherenceAdvert block. */
+export declare const MC_BLOCK_BYTES_MAX = 3584;
+/** alarm marker rowIdentityHashes clamp (>= any ratchet-passing manifest's row count). */
+export declare const MC_MARKER_ROWS_MAX = 72;
+/** per-row identity hash length (truncated, hex). */
+export declare const MC_ROW_HASH_LEN = 16;
+/** Effective-value alphabet for a clamped scalar (spec §3.1/M4/R5-N3). */
+export declare const MC_VALUE_ALPHABET: RegExp;
+/** instarVersion alphabet (spec §3.2 M4 receive clamp). */
+export declare const MC_VERSION_ALPHABET: RegExp;
+/** manifestHash: 64 lowercase hex. */
+export declare const MC_MANIFEST_HASH_RE: RegExp;
+/** episodeId format (spec §3.2 N4). */
+export declare const MC_EPISODE_ID_RE: RegExp;
+/** Read a dotted config path off a plain object (undefined on any miss). */
+export declare function getByPath(obj: unknown, dotted: string): unknown;
+/** The config view the resolver reads: a boot config object + optional live getter. */
+export interface CoherenceConfigView {
+    /** The full boot-time agent config object. */
+    boot: Record<string, unknown>;
+    /**
+     * Optional live-config getter (liveConfig.get(path, fallback)). Used for
+     * `readSource: 'live'` entries so a PATCH /config change is reflected with no
+     * restart. Absent → live entries fall back to the boot value.
+     */
+    liveGet?: (path: string, fallback: unknown) => unknown;
+}
+/**
+ * Resolve one manifest entry's effective value against a config view.
+ * Deterministic; identical across two machines on the same manifest generation.
+ * Returns a clamped scalar string ('live' | 'dry-run' | 'off' | a stage class).
+ */
+export declare function resolveFlagValue(entry: CoherenceCriticalFlag, view: CoherenceConfigView): string;
+/**
+ * Build the manifest-resolved effective-value map (advert `flags`). Keys are the
+ * manifest keys, values clamped scalars. Deterministic + pure.
+ */
+export declare function buildCoherenceFlags(view: CoherenceConfigView): Record<string, string>;
+/**
+ * Compute the manifest hash — sha256 over the sorted ENTRIES (key + resolution
+ * + readSource), NOT just the key list (spec §3.1 M7: two builds can share keys
+ * but differ in resolution semantics). Lowercase hex, 64 chars.
+ */
+export declare function computeManifestHash(flags?: CoherenceCriticalFlag[]): string;
+/** The manifest hash for THIS build's shipped manifest (memoized-safe, pure). */
+export declare function selfManifestHash(): string;
+/** Protocol version this build advertises (mirrors the seamlessness layer). */
+export declare function selfProtocolVersion(): number;
+//# sourceMappingURL=machineCoherenceManifest.d.ts.map

package/dist/core/machineCoherenceManifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machineCoherenceManifest.d.ts","sourceRoot":"","sources":["../../src/core/machineCoherenceManifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,2CAA2C;AAC3C,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,UAAU,GAAG,iBAAiB,CAAC;AAEzE,kFAAkF;AAClF,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,UAAU,EAAE,mBAAmB,CAAC;IAChC,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,0HAQ9B,CAAC;AAaX;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,qBAAqB,EAoF3D,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,6BAA6B,EAAE,0BAA0B,EAqBrE,CAAC;AAGF,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,wCAAwC;AACxC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,mCAAmC;AACnC,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,qDAAqD;AACrD,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,QAAsB,CAAC;AACrD,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAC5D,sCAAsC;AACtC,eAAO,MAAM,mBAAmB,QAAmB,CAAC;AACpD,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQ/D;AAED,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;CACxD;AAOD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAuDhG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,qBAAqB,EAA6B,GAAG,MAAM,CAMrG;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/core/machineCoherenceManifest.js

@@ -0,0 +1,293 @@
+/**
+ * machineCoherenceManifest.ts — the coherence-critical manifest (spec §3.1).
+ *
+ * A fleet-uniform, code-shipped catalog of the flags/versions whose skew across
+ * an agent's OWN machines silently halves a cross-machine guarantee (the F4
+ * incident class). The manifest ships ATOMIC with the code — every machine on
+ * version V evaluates the SAME set — so a key present on one side only is
+ * VERSION skew (already alarmed by the version dimension), never phantom flag
+ * skew. Spec: docs/specs/machine-coherence-guard.md §3.1/§3.3.
+ *
+ * Purity contract: this module is pure + deterministic (no I/O, no clock, no
+ * LLM). The evaluator (MachineCoherenceSentinel) and the advert builder both
+ * consume it; the manifest-size ratchet + membership-drift guard (§3.1 "N5")
+ * are unit tests over the exports here.
+ *
+ * Faithful elaborations of the spec's §3.1 interface sketch (documented, not
+ * silent — see the side-effects artifact):
+ *   - `dryRunConfigPath?` — the spec's `resolution: 'dev-gate+dryRun'` (and the
+ *     "(+ dryRun)" raw rows) inherently need to know WHERE the dry-run flag
+ *     lives; the sketch omitted it. It is folded into the effective value.
+ *   - The F4 pair (`ws13PinReplicate` + `ws13Reconcile`) is TWO independent
+ *     entries sharing one guarantee line, so each key is compared on its own —
+ *     strictly finer-grained than a compound row, never coarser.
+ */
+import { resolveDevAgentGate } from './devAgentGate.js';
+import { SEAMLESSNESS_PROTOCOL_VERSION } from './seamlessnessConfig.js';
+import crypto from 'node:crypto';
+/**
+ * The 7 WS2 replicated stores whose per-store `enabled` (+ dryRun) is
+ * coherence-critical (replicated-memory reach: a non-advertising peer silently
+ * drops the kind). Shipped as a CODE constant, NOT config-derived, so the
+ * manifest is fleet-uniform (a fleet config with no stateSync block still
+ * carries all 7 rows — same set on every machine at version V).
+ */
+export const COHERENCE_STATE_SYNC_STORES = [
+    'preferences',
+    'relationships',
+    'learnings',
+    'knowledge',
+    'evolutionActions',
+    'userRegistry',
+    'topicOperator',
+];
+function stateSyncEntries() {
+    return COHERENCE_STATE_SYNC_STORES.map((store) => ({
+        key: `stateSync.${store}.enabled`,
+        configPath: `multiMachine.stateSync.${store}.enabled`,
+        resolution: 'dev-gate+dryRun',
+        dryRunConfigPath: `multiMachine.stateSync.${store}.dryRun`,
+        readSource: 'boot',
+        guarantee: `replicated ${store} reach — a non-advertising machine silently drops this store's replicated kind`,
+    }));
+}
+/**
+ * COHERENCE_CRITICAL_FLAGS — the manifest (spec §3.1 table). Fleet-uniform,
+ * code-shipped. Order is stable (drives manifestHash determinism after sort).
+ */
+export const COHERENCE_CRITICAL_FLAGS = [
+    {
+        key: 'seamlessness.ws13PinReplicate',
+        configPath: 'multiMachine.seamlessness.ws13PinReplicate',
+        resolution: 'dev-gate+dryRun',
+        dryRunConfigPath: 'multiMachine.seamlessness.ws13DryRun',
+        readSource: 'boot',
+        guarantee: 'cross-machine conversation-move actuation (the F4 pair)',
+    },
+    {
+        key: 'seamlessness.ws13Reconcile',
+        configPath: 'multiMachine.seamlessness.ws13Reconcile',
+        resolution: 'dev-gate+dryRun',
+        dryRunConfigPath: 'multiMachine.seamlessness.ws13DryRun',
+        readSource: 'boot',
+        guarantee: 'cross-machine conversation-move actuation (the F4 pair)',
+    },
+    {
+        key: 'seamlessness.ws43JournalLease',
+        configPath: 'multiMachine.seamlessness.ws43JournalLease',
+        resolution: 'dev-gate+dryRun',
+        dryRunConfigPath: 'multiMachine.seamlessness.ws43JournalLeaseDryRun',
+        readSource: 'boot',
+        guarantee: 'job-claim single-ownership (a mixed pool keeps the whole pool on the legacy bus)',
+    },
+    {
+        key: 'seamlessness.ws44PoolLinks',
+        configPath: 'multiMachine.seamlessness.ws44PoolLinks',
+        resolution: 'dev-gate',
+        readSource: 'boot',
+        guarantee: 'cross-machine private-view link serving',
+    },
+    {
+        key: 'seamlessness.ws44PoolCache',
+        configPath: 'multiMachine.seamlessness.ws44PoolCache',
+        resolution: 'dev-gate',
+        readSource: 'boot',
+        guarantee: 'pool-cache fan-out honesty (a mixed pool re-fans per surface)',
+    },
+    ...stateSyncEntries(),
+    {
+        key: 'pollFollowsLease.enabled',
+        configPath: 'multiMachine.pollFollowsLease.enabled',
+        resolution: 'raw',
+        dryRunConfigPath: 'multiMachine.pollFollowsLease.dryRun',
+        readSource: 'boot',
+        guarantee: 'ingress-follows-lease (the July-1 silent-loss shape)',
+    },
+    {
+        key: 'sessionPool.stage',
+        configPath: 'multiMachine.sessionPool.stage',
+        resolution: 'raw',
+        readSource: 'live',
+        guarantee: 'whether the pool routes real traffic at all (+ the exactlyOnceIngress default it drives)',
+    },
+    {
+        key: 'exactlyOnceIngress',
+        configPath: 'multiMachine.exactlyOnceIngress',
+        resolution: 'raw',
+        readSource: 'live',
+        guarantee: 'per-message dedup ledger on every machine',
+    },
+    {
+        key: 'meshTransport.enabled',
+        configPath: 'multiMachine.meshTransport.enabled',
+        resolution: 'raw',
+        readSource: 'boot',
+        guarantee: 'multi-rope mesh reachability',
+    },
+    {
+        key: 'developmentAgent',
+        configPath: 'developmentAgent',
+        resolution: 'raw',
+        readSource: 'boot',
+        guarantee: 'the ROOT of the F4 class — every omitted-flag resolution flips with it',
+    },
+    {
+        key: 'monitoring.machineCoherence',
+        configPath: 'monitoring.machineCoherence.enabled',
+        resolution: 'dev-gate+dryRun',
+        dryRunConfigPath: 'monitoring.machineCoherence.dryRun',
+        readSource: 'boot',
+        guarantee: 'the machine-coherence guard itself (a half-dark pool has halved its own alarm redundancy)',
+    },
+];
+export const COHERENCE_MANIFEST_EXCLUSIONS = [
+    { configPath: 'multiMachine.coherenceJournal.enabled', reason: 'content-free local lifecycle journal; a mixed pool degrades to no-journal on one side, not a data guarantee the guard owns' },
+    { configPath: 'multiMachine.meshTransport.recoveryProbeEnabled', reason: 'per-machine transport self-heal probe; its own U4.3 episode alarm owns its skew' },
+    { configPath: 'multiMachine.secretSync.enabled', reason: 'receive-only by default + per-machine sealed keys; a non-receiver simply re-enters a secret, no silent data-loss' },
+    { configPath: 'multiMachine.seamlessness.ws3OneVoice', reason: 'per-machine speaker-election posture; the single-negotiator lease is the coherence authority, not this flag' },
+    { configPath: 'multiMachine.writeAdmission.enabled', reason: 'per-machine write-admission gate (ships typed-refusal); a mixed pool degrades to the legacy standby-read-only boolean, not silent loss' },
+    { configPath: 'multiMachine.seamlessness.ws41DurableAck', reason: 'durable remote-ack: a non-participant degrades to today\'s in-memory ack, surfaced by its own route' },
+    { configPath: 'multiMachine.accountFollowMe.enabled', reason: 'account/quota metadata projection; operator-mandate-gated per machine, not a silent guarantee' },
+    { configPath: 'multiMachine.seamlessness.ws43RoleGuard', reason: 'spawn-boundary role re-check; a non-participant keeps today\'s behavior, raises its own deduped item' },
+    { configPath: 'multiMachine.durableOwnership.enabled', reason: 'per-machine durable-ownership record; ownership placement has its own coherence surface' },
+    { configPath: 'multiMachine.ownershipFollowsLiveWork', reason: 'placement heuristic; per-machine, no cross-machine data-loss guarantee' },
+    { configPath: 'multiMachine.sessionPool.staleOwnerRelease.enabled', reason: 'failover reconciler; its own /pool/stale-owner-release telemetry owns its state' },
+    { configPath: 'multiMachine.sessionPool.enabled', reason: 'legacy pool gate; sessionPool.stage (in manifest) is the coherence-relevant routing key' },
+    { configPath: 'multiMachine.sessionPool.inboundQueue.enabled', reason: 'per-machine durable inbound queue; its own /pool/queue loss-notices surface skew' },
+    { configPath: 'multiMachine.sessionPool.holdForStability.enabled', reason: 'per-machine hold policy; trails inboundQueue by one rung, no cross-machine data guarantee' },
+    { configPath: 'multiMachine.sessionPool.ownershipCheckedSpawn.enabled', reason: 'per-machine spawn ownership check; no silent cross-machine guarantee' },
+    { configPath: 'multiMachine.leaseSelfHeal.staleHolderTakeover.enabled', reason: 'lease self-heal reconciler; the lease/split-brain machinery owns its coherence' },
+    { configPath: 'multiMachine.leaseSelfHeal.silentStandbyRelinquish.enabled', reason: 'lease self-heal reconciler; lease-layer owned' },
+    { configPath: 'multiMachine.leaseSelfHeal.soloCaptainHold.enabled', reason: 'lease self-heal reconciler; lease-layer owned' },
+    { configPath: 'multiMachine.leaseSelfHeal.preferredCaptainHandback.enabled', reason: 'lease self-heal reconciler; lease-layer owned + operator latch' },
+    { configPath: 'multiMachine.stateSync.threadlinePairing.enabled', reason: 'verified-pairing store; a non-participant fails-closed on credential share (its own gate), not a silent memory-reach loss like the 7 WS2 stores' },
+];
+// ─── Clamp + byte bounds (spec §3.1) ─────────────────────────────────────
+export const MC_MAX_ENTRIES = 64;
+export const MC_KEY_MAX = 64;
+export const MC_VALUE_MAX = 32;
+/** fixed-fields + flags portion of the advert, serialized. */
+export const MC_FLAGS_BYTES_MAX = 2048;
+/** the §3.2 alarm marker sub-budget. */
+export const MC_MARKER_BYTES_MAX = 1536;
+/** whole coherenceAdvert block. */
+export const MC_BLOCK_BYTES_MAX = 3584;
+/** alarm marker rowIdentityHashes clamp (>= any ratchet-passing manifest's row count). */
+export const MC_MARKER_ROWS_MAX = 72;
+/** per-row identity hash length (truncated, hex). */
+export const MC_ROW_HASH_LEN = 16;
+/** Effective-value alphabet for a clamped scalar (spec §3.1/M4/R5-N3). */
+export const MC_VALUE_ALPHABET = /^[a-z0-9-]{1,32}$/;
+/** instarVersion alphabet (spec §3.2 M4 receive clamp). */
+export const MC_VERSION_ALPHABET = /^[0-9A-Za-z.+-]{1,32}$/;
+/** manifestHash: 64 lowercase hex. */
+export const MC_MANIFEST_HASH_RE = /^[0-9a-f]{64}$/;
+/** episodeId format (spec §3.2 N4). */
+export const MC_EPISODE_ID_RE = /^mc-\d{1,29}$/;
+/** Read a dotted config path off a plain object (undefined on any miss). */
+export function getByPath(obj, dotted) {
+    if (obj == null)
+        return undefined;
+    let cur = obj;
+    for (const seg of dotted.split('.')) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+function clampValue(v) {
+    const s = String(v).toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, MC_VALUE_MAX);
+    return s.length ? s : 'unknown';
+}
+/**
+ * Resolve one manifest entry's effective value against a config view.
+ * Deterministic; identical across two machines on the same manifest generation.
+ * Returns a clamped scalar string ('live' | 'dry-run' | 'off' | a stage class).
+ */
+export function resolveFlagValue(entry, view) {
+    const cfg = view.boot;
+    // Special-cased scalars (non-boolean effective values).
+    switch (entry.key) {
+        case 'developmentAgent':
+            return cfg?.developmentAgent === true ? 'true' : 'false';
+        case 'meshTransport.enabled': {
+            const raw = getByPath(cfg, 'multiMachine.meshTransport.enabled');
+            // meshTransport ships ENABLED by default (Layers 0-2 additive).
+            return raw === false ? 'off' : 'live';
+        }
+        case 'sessionPool.stage': {
+            const pool = view.liveGet
+                ? view.liveGet('multiMachine.sessionPool', getByPath(cfg, 'multiMachine.sessionPool'))
+                : getByPath(cfg, 'multiMachine.sessionPool');
+            const stage = pool && typeof pool.stage === 'string' ? pool.stage : 'dark';
+            return clampValue(stage);
+        }
+        case 'exactlyOnceIngress': {
+            const mm = getByPath(cfg, 'multiMachine');
+            const pool = view.liveGet
+                ? view.liveGet('multiMachine.sessionPool', getByPath(cfg, 'multiMachine.sessionPool'))
+                : getByPath(cfg, 'multiMachine.sessionPool');
+            const explicit = mm ? mm.exactlyOnceIngress : undefined;
+            const stage = pool && typeof pool.stage === 'string' ? pool.stage : undefined;
+            const resolved = typeof explicit === 'boolean'
+                ? explicit
+                : stage === 'live-transfer' || stage === 'rebalance';
+            return resolved ? 'live' : 'off';
+        }
+        default:
+            break;
+    }
+    // Boolean-fold path (raw / dev-gate / dev-gate+dryRun with an optional dryRun fold).
+    const rawEnabled = getByPath(cfg, entry.configPath);
+    let enabled;
+    if (entry.resolution === 'raw') {
+        enabled = rawEnabled === true;
+    }
+    else {
+        enabled = resolveDevAgentGate(typeof rawEnabled === 'boolean' ? rawEnabled : undefined, cfg);
+    }
+    if (!enabled)
+        return 'off';
+    if (entry.dryRunConfigPath) {
+        const dry = getByPath(cfg, entry.dryRunConfigPath);
+        // Convention: a dev-gated dry-run defaults TRUE (first rung); a raw dry-run
+        // (pollFollowsLease) defaults FALSE (live once enabled).
+        const dryDefault = entry.resolution !== 'raw';
+        const isDry = typeof dry === 'boolean' ? dry : dryDefault;
+        return isDry ? 'dry-run' : 'live';
+    }
+    return 'live';
+}
+/**
+ * Build the manifest-resolved effective-value map (advert `flags`). Keys are the
+ * manifest keys, values clamped scalars. Deterministic + pure.
+ */
+export function buildCoherenceFlags(view) {
+    const out = {};
+    for (const entry of COHERENCE_CRITICAL_FLAGS) {
+        out[entry.key] = clampValue(resolveFlagValue(entry, view));
+    }
+    return out;
+}
+/**
+ * Compute the manifest hash — sha256 over the sorted ENTRIES (key + resolution
+ * + readSource), NOT just the key list (spec §3.1 M7: two builds can share keys
+ * but differ in resolution semantics). Lowercase hex, 64 chars.
+ */
+export function computeManifestHash(flags = COHERENCE_CRITICAL_FLAGS) {
+    const canonical = flags
+        .map((f) => `${f.key}|${f.resolution}|${f.readSource}`)
+        .sort()
+        .join('\n');
+    return crypto.createHash('sha256').update(canonical).digest('hex');
+}
+/** The manifest hash for THIS build's shipped manifest (memoized-safe, pure). */
+export function selfManifestHash() {
+    return computeManifestHash(COHERENCE_CRITICAL_FLAGS);
+}
+/** Protocol version this build advertises (mirrors the seamlessness layer). */
+export function selfProtocolVersion() {
+    return SEAMLESSNESS_PROTOCOL_VERSION;
+}
+//# sourceMappingURL=machineCoherenceManifest.js.map

package/dist/core/machineCoherenceManifest.js.map

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

package/dist/core/types.d.ts

@@ -1957,6 +1957,27 @@ export interface MachineCapacity {
      *  restarts via the durable last-known store, so a dark peer renders with
      *  its honest age. */
     guardPostureReceivedAt?: string;
+    /** Machine-coherence advert (machine-coherence-guard §3.2): running version,
+     *  protocol version, manifest hash, the guard's own posture, and the
+     *  manifest-resolved effective flag values. Emission is UNCONDITIONAL (M3 —
+     *  ships live with the code; only the evaluator/alarm are dev-gated); absent
+     *  = the peer predates the guard (classified `unknown` → version-class after
+     *  grace). Receive side is CLAMPED (M4) — a rejected advert is replaced by
+     *  `coherenceAdvertRejected`, never carried forward as current posture. */
+    coherenceAdvert?: import('./machineCoherenceAdvert.js').CoherenceAdvert;
+    /** RECEIVER-side receipt time (ISO) of the LAST beat that actually CARRIED a
+     *  coherenceAdvert (M5): carry-forward must never impersonate freshness — the
+     *  evaluator degrades an advert older than `advertStaleMs` to `advert-stale`
+     *  even while liveness (`routerReceivedAt`) stays fresh via git beats. */
+    coherenceAdvertReceivedAt?: string;
+    /** Clamp-rejection marker (M4): set when the peer's LAST advert failed the
+     *  receive clamp. REPLACES the stored advert for evaluation purposes
+     *  (rejected ≠ absent — surfaced as `advert-rejected`, a LOUD named
+     *  condition, never silence); cleared by the next clean advert. */
+    coherenceAdvertRejected?: {
+        atMs: number;
+        reason: string;
+    };
 }
 /** The compact posture block that rides the capacity heartbeat
  *  (GUARD-POSTURE-ENDPOINT-SPEC §2.3). Counts plus per-key detail for ONLY