@aiwg/cli 2026.10.1 → 2026.10.3

package/dist/src/mission-protocol/codecs.js

@@ -1,4 +1,10 @@
-import { MISSION_API_VERSION, } from './types.js';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { HEALTH_ACTIVITY_SUMMARY_MAX_UTF8_BYTES, HEALTH_KNOWN_REASON_CODES, MISSION_API_VERSION, WORKER_BASELINE_FEATURES, WORKER_CONTRACT_REVISION, WORKER_DEFINITIONS, WORKER_DEFINITION_PRODUCERS, WORKER_KNOWN_FEATURES, WorkerContractError, } from './types.js';
 const TERMINAL = new Set(['completed', 'failed', 'incomplete', 'cancelled']);
 function object(value, label = 'Mission input') {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -132,6 +138,7 @@ function assertSupported(version) {
 }
 export function validateCanonicalMission(value) {
     const record = object(value, 'Canonical Mission');
+    assertMissionWorkerHandoff(record, 'canonical');
     if (record.apiVersion !== MISSION_API_VERSION)
         throw new Error(`Unsupported canonical Mission version '${String(record.apiVersion)}'.`);
     if (record.kind !== 'Mission')
@@ -153,6 +160,7 @@ export function validateCanonicalMission(value) {
 }
 export function decodeMission(input, source) {
     const record = object(input);
+    assertMissionWorkerHandoff(record, source);
     if (source === 'canonical') {
         const value = validateCanonicalMission(record);
         return { value, sourceVersion: MISSION_API_VERSION, warnings: [], preservedExtensions: structuredClone(value.extensions ?? {}), lossReport: [] };
@@ -219,6 +227,7 @@ function projectionLosses(value, target) {
     return losses;
 }
 export function encodeMission(value, target, options = {}) {
+    assertMissionWorkerHandoff(value, target);
     const mission = validateCanonicalMission(value);
     if (target === 'canonical')
         return { value: mission, targetVersion: MISSION_API_VERSION, warnings: [], lossReport: [] };
@@ -262,4 +271,633 @@ export function encodeMission(value, target, options = {}) {
         projected = { id: mission.metadata.id, objective: mission.spec.objective, status: mission.status.state, completion: mission.spec.completionCriterion, artifacts: base.artifacts, partialOutput: base.partialOutput, extensions: base.extensions };
     return { value: projected, targetVersion: target, warnings: lossReport.map(loss => `${loss.path}: ${loss.reason}`), lossReport };
 }
+let cachedWorkerValidators;
+function missionPackageRoot(start) {
+    let current = resolve(start);
+    for (;;) {
+        try {
+            const packageJson = JSON.parse(readFileSync(join(current, 'package.json'), 'utf8'));
+            if (packageJson.name === 'aiwg' || packageJson.name === '@aiwg/cli')
+                return current;
+        }
+        catch {
+            // Keep walking; source and compiled modules have different depths.
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            throw new Error('worker contracts: could not locate the aiwg package root');
+        current = parent;
+    }
+}
+function loadWorkerValidators() {
+    if (!cachedWorkerValidators) {
+        const schemaPath = join(missionPackageRoot(dirname(fileURLToPath(import.meta.url))), 'schemas/mission-v1.schema.json');
+        const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+        if (typeof schema.$id !== 'string')
+            throw new WorkerContractError('OG_CONTRACT_INVALID', 'Worker contract owner has no schema $id.');
+        const ajv = addFormats(new Ajv2020({ strict: false, allErrors: true }));
+        ajv.addSchema(schema);
+        const validators = new Map();
+        for (const definition of WORKER_DEFINITIONS)
+            validators.set(definition, ajv.compile({ $ref: `${schema.$id}#/$defs/${definition}` }));
+        cachedWorkerValidators = { schemaId: schema.$id, bundleDigest: workerBundleDigestFor(schema), validators };
+    }
+    return cachedWorkerValidators;
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function workerBundleDigestFor(schema) {
+    const defs = schema.$defs;
+    const workerDefs = Object.fromEntries(WORKER_DEFINITIONS.filter(definition => definition in defs).map(definition => [definition, defs[definition]]));
+    return `sha256:${createHash('sha256').update(stableJson(workerDefs)).digest('hex')}`;
+}
+/** Digest of the shipped worker definition bundle; consumers advertise it back during negotiation. */
+export function workerDefinitionBundleDigest() {
+    return loadWorkerValidators().bundleDigest;
+}
+export function workerContractSchemaId() {
+    return loadWorkerValidators().schemaId;
+}
+// 05 §5.1: complete JSON payloads are bounded independently of field limits.
+export const WORKER_MAX_JSON_BYTES = 262_144;
+export const WORKER_MAX_NESTING_DEPTH = 16;
+function workerSemanticErrors(value) {
+    const ancestors = new Set();
+    function visit(node, depth) {
+        if (!node || typeof node !== 'object')
+            return undefined;
+        if (depth > WORKER_MAX_NESTING_DEPTH)
+            return `JSON nesting depth exceeds ${WORKER_MAX_NESTING_DEPTH}`;
+        if (ancestors.has(node))
+            return 'Worker JSON must not contain cycles';
+        ancestors.add(node);
+        for (const child of Object.values(node)) {
+            const error = visit(child, depth + 1);
+            if (error)
+                return error;
+        }
+        ancestors.delete(node);
+        return undefined;
+    }
+    // Root object/array is depth 1; scalar leaves do not add a nesting level.
+    const depthError = visit(value, 1);
+    if (depthError)
+        return [depthError];
+    try {
+        const bytes = JSON.stringify(value);
+        if (bytes === undefined)
+            return ['Worker payload must be JSON serializable'];
+        if (Buffer.byteLength(bytes, 'utf8') > WORKER_MAX_JSON_BYTES)
+            return [`Serialized UTF-8 JSON exceeds ${WORKER_MAX_JSON_BYTES} bytes`];
+    }
+    catch {
+        return ['Worker payload must be JSON serializable'];
+    }
+    return [];
+}
+/** Validate a worker payload against its bundled definition. Closed shapes reject unknown fields. */
+export function validateWorkerPayload(definition, value) {
+    const semanticErrors = workerSemanticErrors(value);
+    if (semanticErrors.length)
+        return { valid: false, errors: semanticErrors };
+    const validate = loadWorkerValidators().validators.get(definition);
+    if (!validate)
+        throw new WorkerContractError('OG_CONTRACT_INVALID', `Unknown worker definition '${definition}'.`);
+    const valid = validate(value);
+    const errors = valid ? [] : (validate.errors ?? []).map(error => `${error.instancePath || '/'} ${error.message ?? error.keyword}`);
+    if (valid) {
+        const checkHealth = (health) => {
+            if (health.checkSeconds > health.startupSeconds)
+                errors.push('Health checkSeconds must not exceed startupSeconds');
+            if (health.quietSeconds >= health.stallSeconds)
+                errors.push('Health quietSeconds must be less than stallSeconds');
+        };
+        if (definition === 'workerEffectiveHealth')
+            checkHealth(value);
+        if (definition === 'workerResolvedInvocation') {
+            // Legacy and preparatory descriptors may omit health. Preserve that
+            // omission in codecs; resolution and observers supply runtime defaults.
+            const health = value.health;
+            if (health !== undefined)
+                checkHealth(health);
+        }
+    }
+    return { valid: valid && errors.length === 0, errors };
+}
+export function assertValidWorkerPayload(definition, value) {
+    const { valid, errors } = validateWorkerPayload(definition, value);
+    if (!valid)
+        throw new WorkerContractError('OG_CONTRACT_INVALID', `Invalid ${definition}: ${errors.join('; ') || 'shape mismatch'}.`);
+}
+/** The producer is supplied by trusted calling code, never read from payload data. */
+export function decodeWorkerProducedPayload(definition, producer, value) {
+    if (WORKER_DEFINITION_PRODUCERS[definition] !== producer) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', `Producer ${producer} cannot author ${definition}.`);
+    }
+    return decodeWorkerPayload(definition, value);
+}
+export function assertWorkerTerminal(observation) {
+    if (!observation || !['shell', 'mcp'].includes(observation.transport)
+        || observation.status !== 'completed' || observation.termination !== 'confirmed'
+        || (observation.transport === 'shell' ? observation.exitCode !== 0 : observation.exitCode !== null && observation.exitCode !== 0)
+        || (observation.isError !== undefined && observation.isError !== false)) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Worker terminal evidence is missing, erroneous or uncertain; exit zero alone is insufficient.');
+    }
+}
+/**
+ * Assemble detached, immutable evidence from separately attributed producers.
+ * artifactBytes are read by the conductor from the exact artifact (or protected
+ * canonical tree manifest) being verified/integrated, never a worker digest.
+ * This is a shared value operation; no Mission/lease/store is needed in direct mode.
+ */
+// Ordered weakest-to-strongest, matching WorkerExecution['identityQuality'] exactly
+// (05 §5.1 / BLOCKER #2890): a required tier is satisfied by that tier or any
+// stronger one. Keep this the single source of truth for both the valid-value
+// check and the ordering comparison below, so a renamed/added quality tier
+// cannot silently resurrect the former `requiredIdentity: 'runtime-configured'`
+// no-op (the option never matched any real `identityQuality` value).
+const IDENTITY_QUALITY_ORDER = ['unavailable', 'runtime-configured-only', 'backend-attested'];
+export function assembleWorkerResult(input, previous) {
+    if (input.requiredIdentity !== undefined && !IDENTITY_QUALITY_ORDER.includes(input.requiredIdentity)) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Unknown required identity evidence.');
+    }
+    const direct = 'mode' in input.brief && input.brief.mode === 'direct';
+    const briefDefinition = direct ? 'workerDirectBrief' : 'workerBrief';
+    const brief = decodeWorkerProducedPayload(briefDefinition, 'conductor', input.brief);
+    const execution = decodeWorkerProducedPayload('workerExecution', 'adapter', input.execution);
+    const worker = input.worker === null ? null : decodeWorkerProducedPayload('workerClaims', 'worker', input.worker);
+    const verification = decodeWorkerProducedPayload(direct ? 'workerDirectVerification' : 'workerVerification', 'verifier', input.verification);
+    if (stableJson(execution.requested) !== stableJson(brief.selected)) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Adapter requested identity differs from the bound brief.');
+    }
+    if (verification.status === 'accepted') {
+        if (execution.status !== 'completed' || execution.termination !== 'confirmed'
+            || execution.endedAt === null || Date.parse(execution.endedAt) < Date.parse(execution.startedAt) || execution.failure !== null
+            || (execution.exitCode !== null && execution.exitCode !== 0) || worker?.status !== 'completed') {
+            throw new WorkerContractError('OG_CONTRACT_INVALID', 'Acceptance requires completed claims and confirmed successful execution.');
+        }
+        if (execution.identityQuality === 'unavailable' || !execution.identityEvidence.length
+            || (input.requiredIdentity !== undefined
+                && IDENTITY_QUALITY_ORDER.indexOf(execution.identityQuality) < IDENTITY_QUALITY_ORDER.indexOf(input.requiredIdentity))
+            || execution.observedModel !== brief.selected.model || execution.observedFamily !== brief.selected.family
+            || stableJson(execution.observedEffort) !== stableJson(brief.selected.effort)) {
+            throw new WorkerContractError('OG_CONTRACT_INVALID', 'Acceptance requires matching qualified observed identity.');
+        }
+        if (!(input.artifactBytes instanceof Uint8Array)
+            || `sha256:${createHash('sha256').update(input.artifactBytes).digest('hex')}` !== verification.artifactDigest) {
+            throw new WorkerContractError('OG_CONTRACT_INVALID', 'Verified artifact digest differs from the exact artifact bytes.');
+        }
+    }
+    const briefSnapshot = encodeWorkerPayloadSnapshot(briefDefinition, brief);
+    return encodeWorkerPayloadSnapshot(direct ? 'workerDirectResult' : 'workerResult', {
+        version: WORKER_CONTRACT_REVISION,
+        taskId: brief.intent.taskId,
+        invocationId: brief.invocationId,
+        briefDigest: briefSnapshot.artifact.digest,
+        execution, worker, verification,
+        ...(direct ? { mode: 'direct' } : {}),
+    }, previous);
+}
+/**
+ * Fail-closed negotiation before any task data handoff. Absent or unknown
+ * required features, incompatible digests/revisions, or codecs without
+ * lossless round trips yield OG_CONTRACT_UNSUPPORTED.
+ */
+export function workerSupportBlockers(consumer, required) {
+    const blockers = [];
+    if (consumer.revision !== WORKER_CONTRACT_REVISION)
+        blockers.push(`unsupported revision ${String(consumer.revision)}; required ${WORKER_CONTRACT_REVISION}`);
+    if (consumer.bundleDigest !== required.bundleDigest)
+        blockers.push('definition-bundle digest mismatch');
+    if (consumer.lossless !== true)
+        blockers.push('codec does not guarantee lossless round trips');
+    if (!Array.isArray(consumer.features))
+        blockers.push('absent consumer feature metadata');
+    else {
+        for (const feature of required.requiredFeatures) {
+            if (!WORKER_KNOWN_FEATURES.includes(feature))
+                blockers.push(`unknown required feature '${feature}'`);
+            else if (!consumer.features.includes(feature))
+                blockers.push(`missing required feature '${feature}'`);
+        }
+    }
+    return blockers;
+}
+export function negotiateWorkerSupport(consumer, required) {
+    return workerSupportBlockers(consumer, required).length ? 'OG_CONTRACT_UNSUPPORTED' : 'supported';
+}
+/** Block old consumers before payload handling or spawn. */
+export function assertWorkerConsumerSupported(consumer, required) {
+    const blockers = workerSupportBlockers(consumer, required);
+    if (blockers.length)
+        throw new WorkerContractError('OG_CONTRACT_UNSUPPORTED', `OG_CONTRACT_UNSUPPORTED: ${blockers.join('; ')}.`);
+}
+function gateRequest(gate) {
+    return {
+        requiredFeatures: [...(gate.requiredFeatures ?? WORKER_BASELINE_FEATURES)],
+        bundleDigest: gate.bundleDigest ?? workerDefinitionBundleDigest(),
+    };
+}
+/** Trusted registration for the codec only; runtime consumers remain unqualified. */
+function canonicalWorkerSupport() {
+    return { revision: WORKER_CONTRACT_REVISION, bundleDigest: workerDefinitionBundleDigest(), features: [...WORKER_KNOWN_FEATURES], lossless: true };
+}
+function workerDispatchRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Invalid workerDispatch: must be an object.');
+    }
+    return value;
+}
+/**
+ * Existing Mission/native owners call this before cloning, projection or launch.
+ * Only the canonical codec has qualified worker preservation. An open native
+ * extension map never qualifies an executor, renderer or runtime by itself.
+ */
+export function assertMissionWorkerHandoff(input, consumer) {
+    const seen = new Set();
+    const seenRecords = new Set();
+    function visitExtensions(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value) || seen.has(value))
+            return;
+        seen.add(value);
+        const record = value;
+        if (Object.hasOwn(record, 'aiwg.worker-dispatch')) {
+            const dispatch = workerDispatchRecord(record['aiwg.worker-dispatch']);
+            if (dispatch.version !== WORKER_CONTRACT_REVISION) {
+                throw new WorkerContractError('OG_CONTRACT_UNSUPPORTED', `OG_CONTRACT_UNSUPPORTED: unsupported worker revision ${String(dispatch.version)}.`);
+            }
+            const support = canonicalWorkerSupport();
+            assertWorkerConsumerSupported({ ...support, lossless: consumer === 'canonical', ...(consumer === 'canonical' ? {} : { features: [] }) }, {
+                requiredFeatures: Array.isArray(dispatch.requiredFeatures) ? dispatch.requiredFeatures : [...WORKER_BASELINE_FEATURES],
+                bundleDigest: workerDefinitionBundleDigest(),
+            });
+            assertValidWorkerPayload('workerDispatch', dispatch);
+        }
+        // aiwg.source.* contains preserved native extension maps and records.
+        // Other vendor values and output data are opaque, even if their keys
+        // happen to match a worker extension name.
+        for (const [key, child] of Object.entries(record))
+            if (key.startsWith('aiwg.source.')) {
+                visitExtensions(child);
+                visitRecord(child);
+            }
+    }
+    function visitRecord(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value) || seenRecords.has(value))
+            return;
+        seenRecords.add(value);
+        const record = value;
+        // All mission-v1 carriers: /extensions and /status/artifacts/*/extensions.
+        visitExtensions(record.extensions);
+        const status = record.status;
+        if (Array.isArray(status?.artifacts))
+            for (const artifact of status.artifacts)
+                visitRecord(artifact);
+        // Native protocols carry extensions in metadata and top-level artifacts.
+        visitExtensions(record.metadata);
+        if (Array.isArray(record.artifacts))
+            for (const artifact of record.artifacts)
+                visitRecord(artifact);
+    }
+    visitRecord(input);
+}
+function assertWorkerPayloadHandoff(definition, value, gate) {
+    const consumer = gate?.consumer ?? canonicalWorkerSupport();
+    const request = gate ? gateRequest(gate) : { requiredFeatures: [...WORKER_BASELINE_FEATURES], bundleDigest: workerDefinitionBundleDigest() };
+    assertWorkerConsumerSupported(consumer, request);
+    if (definition === 'workerDispatch') {
+        const dispatch = workerDispatchRecord(value);
+        if (dispatch.version !== WORKER_CONTRACT_REVISION)
+            throw new WorkerContractError('OG_CONTRACT_UNSUPPORTED', 'OG_CONTRACT_UNSUPPORTED: unsupported worker revision.');
+        // Payload requirements are authoritative even if a caller supplies a gate
+        // with a weaker list. Negotiation cannot be bypassed through options.
+        assertWorkerConsumerSupported(consumer, {
+            ...request,
+            requiredFeatures: [...new Set([...request.requiredFeatures, ...(Array.isArray(dispatch.requiredFeatures) ? dispatch.requiredFeatures : [])])],
+        });
+    }
+    assertValidWorkerPayload(definition, value);
+}
+/**
+ * Validate and losslessly clone a worker payload for transmission. When a
+ * consumer gate is absent, the trusted codec registration is used. Unsupported
+ * consumers are blocked before validation/cloning. Decoding mirrors encoding:
+ * no normalization is applied,
+ * so decode(encode(value)) is deep-equal to value.
+ */
+export function encodeWorkerPayload(definition, value, gate) {
+    assertWorkerPayloadHandoff(definition, value, gate);
+    return structuredClone(value);
+}
+export function decodeWorkerPayload(definition, value, gate) {
+    assertWorkerPayloadHandoff(definition, value, gate);
+    return structuredClone(value);
+}
+/**
+ * 05 §5.1 / 06 §7: retain hashed bytes and link a successor rather than rewrite
+ * the pending version. Tier 0 callers can keep these in context; Tier 1 owners
+ * persist them in existing Mission/Flow/Ralph artifacts (S2+).
+ */
+export function encodeWorkerPayloadSnapshot(definition, value, previous) {
+    const encoded = encodeWorkerPayload(definition, value);
+    if (previous) {
+        if (previous.definition !== definition || `sha256:${createHash('sha256').update(previous.bytes, 'utf8').digest('hex')}` !== previous.artifact.digest) {
+            throw new WorkerContractError('OG_CONTRACT_INVALID', 'Prior worker snapshot definition or digest does not match its preserved bytes.');
+        }
+        const prior = decodeWorkerPayload(definition, JSON.parse(previous.bytes));
+        const next = encoded;
+        for (const identity of ['taskId', 'requestId', 'invocationId', 'briefDigest']) {
+            if (prior[identity] !== next[identity])
+                throw new WorkerContractError('OG_CONTRACT_INVALID', `Worker successor changes ${identity}.`);
+        }
+        if (definition === 'workerDispatch') {
+            const link = next.previousRecord;
+            if (link?.digest !== previous.artifact.digest || link?.ref !== previous.artifact.ref) {
+                throw new WorkerContractError('OG_CONTRACT_INVALID', 'Worker dispatch successor must link previousRecord to its prior snapshot.');
+            }
+        }
+    }
+    const bytes = JSON.stringify(encoded);
+    const digest = `sha256:${createHash('sha256').update(bytes, 'utf8').digest('hex')}`;
+    return Object.freeze({ definition, bytes, artifact: Object.freeze({ ref: `artifact:${digest}`, digest }), previousRecord: previous ? Object.freeze({ ...previous.artifact }) : null });
+}
+// S1 health-to-lease and Mission reconciliation mapping (B-OG-54 / #2916,
+// 05 §8, ADR-OG-10/13). Pure functions over validated shapes: no scheduler,
+// store, Mission runtime or managed import. S2 owners (B-OG-12/16) wire these
+// verdicts into actual renew/fence/stop/settle/release runtime.
+const HEALTH_TERMINAL_LIKE = new Set(['completed', 'failed', 'cancelled', 'crashed', 'failed-to-start']);
+/**
+ * Classify supervision evidence into a distinct shared-trace kind. Quiet,
+ * stalled and uncertain map distinctly. Heartbeat/lease-only observation
+ * yields activity-only, never productive work. A crashed or failed-to-start
+ * worker without confirmed termination is terminal-unconfirmed: fail-stop is
+ * claimed but a live descendant may survive, so it is never stop proof
+ * (ADR-OG-10). Precondition: schema-valid workerHealthSummary.
+ */
+export function classifyHealthTrace(health) {
+    if (health.termination === 'confirmed' && HEALTH_TERMINAL_LIKE.has(health.state))
+        return 'terminal-proof';
+    if (HEALTH_TERMINAL_LIKE.has(health.state))
+        return 'terminal-unconfirmed';
+    // Confirmed termination with a non-terminal state is contradictory owner
+    // evidence (finish() never produces it): downgrade, never productive.
+    if (health.termination === 'confirmed')
+        return 'uncertain';
+    if (health.termination === 'uncertain')
+        return 'uncertain';
+    switch (health.state) {
+        case 'launching':
+        case 'started':
+            return 'setup';
+        case 'active':
+            return health.lastProgressAt === null ? 'activity-only' : 'productive';
+        case 'quiet':
+            return 'quiet';
+        case 'stalled':
+        case 'hung':
+            return 'stalled';
+        default:
+            return 'uncertain';
+    }
+}
+const TRACE_TRUNCATION_MARKER = '…[truncated]';
+/** Strip control/format characters and cap at maxUtf8Bytes (marker included). */
+export function boundTraceText(text, maxUtf8Bytes) {
+    const clean = String(text).replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]/g, '');
+    if (maxUtf8Bytes <= 0)
+        return '';
+    if (Buffer.byteLength(clean, 'utf8') <= maxUtf8Bytes)
+        return clean;
+    const markerBytes = Buffer.byteLength(TRACE_TRUNCATION_MARKER, 'utf8');
+    if (maxUtf8Bytes < markerBytes) {
+        // The budget cannot hold even the marker: return the longest
+        // character-boundary prefix of the marker that fits, so the output
+        // never exceeds the budget.
+        let bytes = 0;
+        let end = 0;
+        for (const char of TRACE_TRUNCATION_MARKER) {
+            const size = Buffer.byteLength(char, 'utf8');
+            if (bytes + size > maxUtf8Bytes)
+                break;
+            bytes += size;
+            end += char.length;
+        }
+        return TRACE_TRUNCATION_MARKER.slice(0, end);
+    }
+    let bytes = 0;
+    let end = 0;
+    for (const char of clean) {
+        const size = Buffer.byteLength(char, 'utf8');
+        if (bytes + size > maxUtf8Bytes - markerBytes)
+            break;
+        bytes += size;
+        end += char.length;
+    }
+    return clean.slice(0, end) + TRACE_TRUNCATION_MARKER;
+}
+/**
+ * Allowlisted reason label for the shared trace. Unlisted codes (including
+ * any free text carrying secret material) project as UNCLASSIFIED#digest:
+ * stable and bounded, never verbatim.
+ */
+export function healthReasonLabel(reasonCode) {
+    if (HEALTH_KNOWN_REASON_CODES.includes(reasonCode))
+        return reasonCode;
+    const digest = createHash('sha256').update(reasonCode, 'utf8').digest('hex').slice(0, 12);
+    return `UNCLASSIFIED#${digest}`;
+}
+/**
+ * Digest-only lifecycle reference for the effect ledger. Only enum, counter,
+ * digest and timestamp fields enter the digest; no payload content crosses.
+ */
+export function healthLifecycleDigest(health) {
+    assertValidWorkerPayload('workerHealthSummary', health);
+    const lifecycle = {
+        version: health.version,
+        state: health.state,
+        coverage: health.coverage,
+        handshake: health.handshake,
+        termination: health.termination,
+        confidence: health.confidence,
+        observerGeneration: health.observerGeneration,
+        transitionCount: health.transitionCount,
+        restartCount: health.restartCount,
+        lastObservedAt: health.lastObservedAt,
+        lastActivityAt: health.lastActivityAt,
+        lastProgressAt: health.lastProgressAt,
+    };
+    const digest = `sha256:${createHash('sha256').update(stableJson(lifecycle), 'utf8').digest('hex')}`;
+    return { ref: `artifact:${digest}`, digest };
+}
+/**
+ * Closed observed-state vocabulary for the previous-state channel. Free
+ * text (including leaked bearer material) never interpolates into the
+ * shared trace.
+ */
+const HEALTH_OBSERVED_STATES = new Set([
+    'launching', 'started', 'active', 'quiet', 'stalled', 'hung',
+    'crashed', 'failed-to-start', 'completed', 'failed', 'cancelled',
+]);
+/**
+ * Parse an ISO timestamp into epoch milliseconds for chronological
+ * comparison. Comparison must never fall back to string ordering: distinct
+ * representations of the same instant (e.g. '.000Z' vs 'Z') must compare
+ * equal, not greater/lesser. Unparseable values reject as having no
+ * timestamp evidence (null), never throw.
+ */
+function parseProgressTimestampMs(value) {
+    if (value === null)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Fresh-progress gate: credit requires genuinely new progress evidence.
+ * The health shape carries no progress sequence/key, so freshness is a
+ * NONDECREASING credit watermark: `previousWatermark` is not merely "the
+ * last observation" but the highest-ever CREDITED lastProgressAt, compared
+ * by parsed epoch milliseconds (never raw strings). Out-of-order or
+ * replayed snapshots (older than, or equal to, the watermark) earn no
+ * credit and never move the watermark backward; heartbeats (which advance
+ * activity/observed timestamps while the watermark is frozen) never
+ * re-credit historical progress. Unparseable timestamps earn no credit.
+ * Callers thread the watermark forward with `advanceProgressWatermark`.
+ */
+function isFreshProgressEvidence(health, previousWatermark) {
+    const currentMs = parseProgressTimestampMs(health.lastProgressAt);
+    if (currentMs === null)
+        return false;
+    if (previousWatermark === null || previousWatermark.lastProgressAt === null)
+        return true;
+    const watermarkMs = parseProgressTimestampMs(previousWatermark.lastProgressAt);
+    if (watermarkMs === null)
+        return false;
+    return currentMs > watermarkMs;
+}
+/**
+ * Pure watermark reducer (no store): callers thread the returned value into
+ * the next observation's `previousHealth`/watermark argument instead of
+ * re-passing the raw last observation. The watermark advances ONLY when the
+ * current observation was actually credited; a non-credited observation
+ * (replay, heartbeat, or an out-of-order/older snapshot) leaves the
+ * watermark exactly where it was. This is what makes real A -> B -> A -> B
+ * delivery sequences credit true,true,false,false instead of re-crediting
+ * B the second time it arrives: a naive caller that re-threads "the last
+ * observation" (rather than this reducer's output) regresses to that bug.
+ */
+export function advanceProgressWatermark(previousWatermark, credited, health) {
+    if (credited)
+        return { lastProgressAt: health.lastProgressAt };
+    return previousWatermark ?? { lastProgressAt: null };
+}
+/**
+ * Project one health observation into the shared trace. The activity summary
+ * is built only from enum/counter/generation fields plus the allowlisted
+ * reason label; completionCredit is always false because Mission/Flow
+ * completion gates stay authoritative. previousState must be a closed
+ * observed state (or null); anything else is rejected, never interpolated.
+ * progressCredit requires fresh progress evidence relative to
+ * previousHealth, which callers must maintain as the nondecreasing credit
+ * watermark (see advanceProgressWatermark) rather than the raw last
+ * observation (null for a first observation / no watermark yet).
+ */
+export function projectHealthTrace(health, previousState = null, previousHealth = null) {
+    assertValidWorkerPayload('workerHealthSummary', health);
+    if (previousState !== null && !HEALTH_OBSERVED_STATES.has(previousState)) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Invalid previous health state.');
+    }
+    const kind = classifyHealthTrace(health);
+    const summary = `health.${health.state}:${health.termination}`
+        + ` gen=${health.observerGeneration ?? 'none'} transitions=${health.transitionCount}`
+        + ` prev=${previousState ?? 'none'} reason=${healthReasonLabel(health.reasonCode)}`;
+    return {
+        kind,
+        progressCredit: kind === 'productive' && isFreshProgressEvidence(health, previousHealth),
+        completionCredit: false,
+        activitySummary: boundTraceText(summary, HEALTH_ACTIVITY_SUMMARY_MAX_UTF8_BYTES),
+        effectRef: healthLifecycleDigest(health),
+    };
+}
+/**
+ * Derive stop proof from owner-observed supervision evidence (ADR-OG-10).
+ * Only a terminal state with owner-confirmed termination is stop proof;
+ * terminal-unconfirmed and uncertain observations stay uncertain, and the
+ * absence of evidence is none. There is no free-form proof parameter:
+ * callers pass the health summary (or null) and the proof is derived.
+ * A late final after cancel-disconnect therefore never releases while
+ * termination is uncertain (ADR-OG-13: late results stay unaccepted
+ * evidence).
+ */
+export function stopProofFromHealth(health) {
+    if (health === null)
+        return 'none';
+    assertValidWorkerPayload('workerHealthSummary', health);
+    if (health.termination === 'confirmed') {
+        return HEALTH_TERMINAL_LIKE.has(health.state) ? 'confirmed' : 'uncertain';
+    }
+    if (HEALTH_TERMINAL_LIKE.has(health.state) || health.termination === 'uncertain')
+        return 'uncertain';
+    return 'none';
+}
+/**
+ * The generation the stop-proof evidence actually belongs to, bridging a
+ * missing observerGeneration to 0 (the bootstrap generation) for fencing —
+ * mirroring the same bridge decideLeaseMapping already applies to the
+ * caller-supplied leaseGeneration/observedGeneration fields. This is bound
+ * to the health summary's OWN observerGeneration field, which the caller
+ * cannot set independently of the evidence: a caller cannot claim generation
+ * 3 while attaching generation-2 evidence and have it treated as current.
+ */
+function stopProofGeneration(health) {
+    if (health === null)
+        return null;
+    return health.observerGeneration ?? 0;
+}
+/**
+ * Pure renewal/reconcile/release verdict over a mocked scheduler boundary.
+ * Fencing binds every action to the current generation: a stale observation
+ * denies renew, cancel, settle and accept alike. Expiry or cancel-disconnect
+ * without derived confirmed stop proof retains the uncertain reservation
+ * and releases nothing. Confirmed stop proof settles exactly once — and only
+ * when that proof's OWN generation (not merely the caller-asserted
+ * observedGeneration) matches the current leaseGeneration; a confirmed
+ * proof carried over from a stale generation never releases.
+ */
+export function decideLeaseMapping(input) {
+    let record;
+    try {
+        record = object(input, 'Lease mapping input');
+    }
+    catch {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Invalid lease mapping input.');
+    }
+    const leaseStates = ['admitted', 'expired', 'cancelled-disconnected'];
+    if (typeof record.leaseState !== 'string' || !leaseStates.includes(record.leaseState)
+        || !Number.isSafeInteger(record.leaseGeneration) || record.leaseGeneration < 0
+        || !Number.isSafeInteger(record.observedGeneration) || record.observedGeneration < 0
+        || typeof record.settled !== 'boolean'
+        || !('health' in record)
+        || (record.health !== null && !validateWorkerPayload('workerHealthSummary', record.health).valid)) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Invalid lease mapping input.');
+    }
+    const mapping = input;
+    if (mapping.observedGeneration !== mapping.leaseGeneration)
+        return 'deny-stale';
+    if (mapping.settled)
+        return 'deny-already-settled';
+    const stopProof = stopProofFromHealth(mapping.health);
+    const proofIsCurrent = stopProofGeneration(mapping.health) === mapping.leaseGeneration;
+    if (stopProof === 'confirmed' && proofIsCurrent)
+        return 'release-once';
+    if (stopProof === 'uncertain' || (stopProof === 'confirmed' && !proofIsCurrent) || mapping.leaseState !== 'admitted') {
+        return 'retain-uncertain';
+    }
+    return 'renew';
+}
 //# sourceMappingURL=codecs.js.map