@ornexus/neocortex 4.60.41 → 4.60.43

package/packages/shared/dist/state/state-migration.d.ts

@@ -0,0 +1,58 @@
+export declare const STATE_MIGRATION_PLAN_SCHEMA: "StateMigrationPlan/1.0";
+export declare const STATE_MIGRATION_RECEIPT_SCHEMA: "StateMigrationReceipt/1.0";
+export type StateMigrationHardStopReason = 'state_not_object' | 'state_not_json' | 'state_projected_or_partial' | 'unsupported_schema_version' | 'invalid_epics_collection' | 'invalid_stories_collection' | 'invalid_epic_record' | 'invalid_story_record' | 'record_identity_conflict' | 'invalid_planning_container' | 'invalid_planning_current' | 'invalid_planning_history' | 'legacy_epic_id_missing' | 'legacy_story_shape_invalid' | 'legacy_story_id_missing' | 'migration_value_conflict';
+export declare class StateMigrationHardStopError extends Error {
+    readonly reasonCode: StateMigrationHardStopReason;
+    constructor(reasonCode: StateMigrationHardStopReason, message?: string);
+}
+export interface StateMigrationStepV1 {
+    readonly kind: 'initialize-collection' | 'merge-epic' | 'merge-story' | 'preserve-legacy' | 'remove-legacy' | 'set-schema-version';
+    readonly target: string;
+    readonly source?: string;
+}
+export interface StateMigrationPlanV1 {
+    readonly schemaVersion: typeof STATE_MIGRATION_PLAN_SCHEMA;
+    readonly operationId: string;
+    readonly sourceSchemaVersion: 0 | 1 | 'absent';
+    readonly targetSchemaVersion: 1;
+    readonly sourceCanonicalHash: string;
+    readonly targetCanonicalHash: string;
+    readonly targetState: Readonly<Record<string, unknown>>;
+    readonly steps: readonly StateMigrationStepV1[];
+    readonly migratedEpicIds: readonly string[];
+    readonly migratedStoryIds: readonly string[];
+    readonly preservedUnknownFieldCount: number;
+    readonly reasonCodes: readonly string[];
+}
+export type StateMigrationDecision = {
+    readonly kind: 'unchanged';
+    readonly sourceCanonicalHash: string;
+    readonly state: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: 'migrate';
+    readonly plan: StateMigrationPlanV1;
+};
+export interface StateMigrationReceiptV1 {
+    readonly schemaVersion: typeof STATE_MIGRATION_RECEIPT_SCHEMA;
+    readonly operationId: string;
+    readonly outcome: 'applied' | 'already-applied' | 'blocked';
+    readonly sourceBytesHash: string;
+    readonly targetBytesHash: string;
+    readonly sourceCanonicalHash: string;
+    readonly targetCanonicalHash: string;
+    readonly backupHash: string | null;
+    readonly rollbackStatus: 'not-required' | 'restored' | 'unverified';
+    readonly migratedEpicCount: number;
+    readonly migratedStoryCount: number;
+    readonly preservedUnknownFieldCount: number;
+    readonly reasonCodes: readonly string[];
+    readonly publicSafe: true;
+}
+export declare function stateMigrationDigest(value: unknown): string;
+/**
+ * Build a deterministic, no-I/O migration plan. Every destructive decision is
+ * preceded by complete structural validation and a lossless canonical merge.
+ */
+export declare function planStateMigration(state: unknown): StateMigrationDecision;
+export declare function assertStateMigrationPlanV1(value: unknown): asserts value is StateMigrationPlanV1;
+export declare function assertStateMigrationReceiptV1(value: unknown): asserts value is StateMigrationReceiptV1;

package/packages/shared/dist/state/state-migration.js

@@ -0,0 +1,404 @@
+import { createHash } from 'node:crypto';
+export const STATE_MIGRATION_PLAN_SCHEMA = 'StateMigrationPlan/1.0';
+export const STATE_MIGRATION_RECEIPT_SCHEMA = 'StateMigrationReceipt/1.0';
+export class StateMigrationHardStopError extends Error {
+    reasonCode;
+    constructor(reasonCode, message = reasonCode) {
+        super(message);
+        this.reasonCode = reasonCode;
+        this.name = 'StateMigrationHardStopError';
+    }
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function assertJsonValue(value, seen = new WeakSet()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (typeof value !== 'object')
+        throw new StateMigrationHardStopError('state_not_json');
+    if (seen.has(value))
+        throw new StateMigrationHardStopError('state_not_json');
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertJsonValue(item, seen);
+    }
+    else {
+        if (!isPlainObject(value))
+            throw new StateMigrationHardStopError('state_not_json');
+        for (const item of Object.values(value))
+            assertJsonValue(item, seen);
+    }
+    seen.delete(value);
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(',')}]`;
+    const object = value;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(object[key])}`).join(',')}}`;
+}
+export function stateMigrationDigest(value) {
+    return createHash('sha256')
+        .update('Neocortex/StateMigrationCanonicalJSON/1\0')
+        .update(canonicalize(value))
+        .digest('hex');
+}
+function countObjectFields(value) {
+    if (!isPlainObject(value))
+        return 0;
+    return Object.entries(value).reduce((count, [, child]) => count + 1 + countObjectFields(child), 0);
+}
+function preservedUnknownFieldCount(state) {
+    const rootKnown = new Set(['schema_version', 'config', 'project', 'epics', 'stories', 'planning']);
+    let count = Object.entries(state)
+        .filter(([key]) => !rootKnown.has(key))
+        .reduce((total, [, value]) => total + 1 + countObjectFields(value), 0);
+    const planning = isPlainObject(state.planning) ? state.planning : undefined;
+    if (planning) {
+        count += Object.entries(planning)
+            .filter(([key]) => key !== 'current' && key !== 'history')
+            .reduce((total, [, value]) => total + 1 + countObjectFields(value), 0);
+    }
+    const epicKnown = new Set(['epic_id', 'id', 'title', 'status', 'stories', 'created_at', 'updated_at', 'completed_at', 'completed_stories', 'total_stories']);
+    const storyKnown = new Set(['id', 'epic_id', 'title', 'status', 'depends_on', 'created_at', 'updated_at', 'completed_at']);
+    const countRecordUnknown = (record, known) => isPlainObject(record)
+        ? Object.entries(record).filter(([key]) => !known.has(key)).reduce((total, [, value]) => total + 1 + countObjectFields(value), 0)
+        : 0;
+    if (isPlainObject(planning?.current)) {
+        count += countRecordUnknown(planning.current, epicKnown);
+        if (Array.isArray(planning.current.stories)) {
+            count += planning.current.stories.reduce((total, story) => total + countRecordUnknown(story, storyKnown), 0);
+        }
+    }
+    if (Array.isArray(planning?.history)) {
+        count += planning.history.reduce((total, epic) => total + countRecordUnknown(epic, epicKnown), 0);
+    }
+    return count;
+}
+function equal(left, right) {
+    return canonicalize(left) === canonicalize(right);
+}
+function assertCompleteState(input) {
+    const scope = input.scope;
+    if (isPlainObject(scope)) {
+        const omittedStories = typeof scope.omittedStoryCount === 'number' ? scope.omittedStoryCount : 0;
+        const omittedEpics = typeof scope.omittedEpicCount === 'number' ? scope.omittedEpicCount : 0;
+        if (scope.kind === 'projected' || omittedStories > 0 || omittedEpics > 0) {
+            throw new StateMigrationHardStopError('state_projected_or_partial');
+        }
+    }
+}
+function validateCanonicalCollection(value, collection) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        throw new StateMigrationHardStopError(collection === 'epics' ? 'invalid_epics_collection' : 'invalid_stories_collection');
+    }
+    if (Object.keys(value).length > 4096) {
+        throw new StateMigrationHardStopError(collection === 'epics' ? 'invalid_epics_collection' : 'invalid_stories_collection');
+    }
+    for (const [id, record] of Object.entries(value)) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/.test(id)) {
+            throw new StateMigrationHardStopError(collection === 'epics' ? 'invalid_epic_record' : 'invalid_story_record');
+        }
+        if (!isPlainObject(record)) {
+            throw new StateMigrationHardStopError(collection === 'epics' ? 'invalid_epic_record' : 'invalid_story_record');
+        }
+        if (record.id !== undefined && record.id !== id) {
+            throw new StateMigrationHardStopError('record_identity_conflict', 'record identity conflicts with its map key');
+        }
+        if (collection === 'epics' && record.stories !== undefined && !Array.isArray(record.stories)) {
+            throw new StateMigrationHardStopError('invalid_epic_record', 'epic stories membership is not an array');
+        }
+    }
+}
+function storyIds(value, source) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new StateMigrationHardStopError('legacy_story_shape_invalid', `${source}.stories is not an array`);
+    if (value.length > 4096)
+        throw new StateMigrationHardStopError('legacy_story_shape_invalid', `${source}.stories is unbounded`);
+    const ids = [];
+    for (const [index, item] of value.entries()) {
+        const id = typeof item === 'string'
+            ? item
+            : isPlainObject(item) && typeof item.id === 'string'
+                ? item.id
+                : null;
+        if (!id || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/.test(id)) {
+            throw new StateMigrationHardStopError('legacy_story_id_missing', `${source}.stories[${index}] has no stable id`);
+        }
+        if (ids.includes(id))
+            throw new StateMigrationHardStopError('migration_value_conflict', `${source} repeats a story id`);
+        ids.push(id);
+    }
+    return ids;
+}
+function mergeWithoutLoss(target, candidate) {
+    const merged = clone(target);
+    for (const [key, value] of Object.entries(candidate)) {
+        if (!(key in merged)) {
+            merged[key] = clone(value);
+            continue;
+        }
+        if (!equal(merged[key], value)) {
+            throw new StateMigrationHardStopError('migration_value_conflict', 'canonical and legacy values are unequal');
+        }
+    }
+    return merged;
+}
+function legacyEpicCandidate(entry, epicId, history) {
+    const candidate = clone(entry);
+    delete candidate.epic_id;
+    candidate.id = epicId;
+    candidate.stories = storyIds(entry.stories, history ? `planning.history[${epicId}]` : 'planning.current');
+    if (candidate.status === undefined)
+        candidate.status = history ? 'done' : 'in-progress';
+    if (history && candidate.status !== 'done') {
+        throw new StateMigrationHardStopError('migration_value_conflict', `planning.history[${epicId}].status must be done`);
+    }
+    return candidate;
+}
+function mergeLegacyEpic(entry, source, history, epics, stories, operations) {
+    const epicId = typeof entry.epic_id === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/.test(entry.epic_id) ? entry.epic_id : null;
+    if (!epicId)
+        throw new StateMigrationHardStopError('legacy_epic_id_missing', `${source}.epic_id is required`);
+    const candidate = legacyEpicCandidate(entry, epicId, history);
+    const existingEpic = epics[epicId];
+    if (existingEpic !== undefined && !isPlainObject(existingEpic))
+        throw new StateMigrationHardStopError('invalid_epic_record');
+    epics[epicId] = existingEpic === undefined
+        ? candidate
+        : mergeWithoutLoss(existingEpic, candidate);
+    operations.push({ kind: 'merge-epic', source, target: `epics.${epicId}` });
+    if (Array.isArray(entry.stories)) {
+        for (const [index, item] of entry.stories.entries()) {
+            if (typeof item === 'string')
+                continue;
+            if (!isPlainObject(item))
+                throw new StateMigrationHardStopError('legacy_story_shape_invalid', `${source}.stories[${index}] is invalid`);
+            const storyId = typeof item.id === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/.test(item.id) ? item.id : null;
+            if (!storyId)
+                throw new StateMigrationHardStopError('legacy_story_id_missing');
+            const candidateStory = clone(item);
+            candidateStory.id = storyId;
+            candidateStory.epic_id = epicId;
+            const existingStory = stories[storyId];
+            if (existingStory !== undefined && !isPlainObject(existingStory))
+                throw new StateMigrationHardStopError('invalid_story_record');
+            stories[storyId] = existingStory === undefined
+                ? candidateStory
+                : mergeWithoutLoss(existingStory, candidateStory);
+            operations.push({ kind: 'merge-story', source: `${source}.stories[${index}]`, target: `stories.${storyId}` });
+        }
+    }
+}
+/**
+ * Build a deterministic, no-I/O migration plan. Every destructive decision is
+ * preceded by complete structural validation and a lossless canonical merge.
+ */
+export function planStateMigration(state) {
+    if (!isPlainObject(state))
+        throw new StateMigrationHardStopError('state_not_object');
+    assertJsonValue(state);
+    assertCompleteState(state);
+    if (state.schema_version !== undefined && state.schema_version !== 0 && state.schema_version !== 1) {
+        throw new StateMigrationHardStopError('unsupported_schema_version');
+    }
+    validateCanonicalCollection(state.epics, 'epics');
+    validateCanonicalCollection(state.stories, 'stories');
+    if (state.planning !== undefined && !isPlainObject(state.planning)) {
+        throw new StateMigrationHardStopError('invalid_planning_container');
+    }
+    const planning = isPlainObject(state.planning) ? state.planning : undefined;
+    if (planning?.current !== undefined && !isPlainObject(planning.current)) {
+        throw new StateMigrationHardStopError('invalid_planning_current');
+    }
+    if (planning?.history !== undefined && !Array.isArray(planning.history)) {
+        throw new StateMigrationHardStopError('invalid_planning_history');
+    }
+    if (Array.isArray(planning?.history) && planning.history.length > 4096) {
+        throw new StateMigrationHardStopError('invalid_planning_history');
+    }
+    const sourceCanonicalHash = stateMigrationDigest(state);
+    const hasLegacy = planning?.current !== undefined || planning?.history !== undefined;
+    const needsCollections = !isPlainObject(state.epics) || !isPlainObject(state.stories);
+    if (state.schema_version === 1 && !hasLegacy && !needsCollections) {
+        return { kind: 'unchanged', sourceCanonicalHash, state };
+    }
+    const target = clone(state);
+    const operations = [];
+    if (!isPlainObject(target.epics)) {
+        target.epics = {};
+        operations.push({ kind: 'initialize-collection', target: 'epics' });
+    }
+    if (!isPlainObject(target.stories)) {
+        target.stories = {};
+        operations.push({ kind: 'initialize-collection', target: 'stories' });
+    }
+    const epics = target.epics;
+    const stories = target.stories;
+    const targetPlanning = isPlainObject(target.planning) ? target.planning : undefined;
+    if (targetPlanning && targetPlanning.current !== undefined) {
+        if (!isPlainObject(targetPlanning.current))
+            throw new StateMigrationHardStopError('invalid_planning_current');
+        const currentEpicId = typeof targetPlanning.current.epic_id === 'string' && targetPlanning.current.epic_id.trim() !== '';
+        const currentStatus = typeof targetPlanning.current.status === 'string'
+            ? targetPlanning.current.status.trim().toLowerCase().replace(/[_\s]+/g, '-')
+            : '';
+        if (!currentEpicId && currentStatus === 'generated') {
+            const preservation = target.state_migration_legacy;
+            if (preservation !== undefined && !isPlainObject(preservation)) {
+                throw new StateMigrationHardStopError('migration_value_conflict', 'state_migration_legacy is not an object');
+            }
+            const envelope = isPlainObject(preservation) ? preservation : {};
+            if (envelope.planning_current !== undefined && !equal(envelope.planning_current, targetPlanning.current)) {
+                throw new StateMigrationHardStopError('migration_value_conflict', 'state_migration_legacy.planning_current conflicts');
+            }
+            envelope.planning_current = clone(targetPlanning.current);
+            target.state_migration_legacy = envelope;
+            operations.push({ kind: 'preserve-legacy', source: 'planning.current', target: 'state_migration_legacy.planning_current' });
+        }
+        else {
+            mergeLegacyEpic(targetPlanning.current, 'planning.current', false, epics, stories, operations);
+        }
+        delete targetPlanning.current;
+        operations.push({ kind: 'remove-legacy', target: 'planning.current' });
+    }
+    if (targetPlanning && targetPlanning.history !== undefined) {
+        if (!Array.isArray(targetPlanning.history))
+            throw new StateMigrationHardStopError('invalid_planning_history');
+        for (const [index, entry] of targetPlanning.history.entries()) {
+            if (!isPlainObject(entry))
+                throw new StateMigrationHardStopError('invalid_planning_history', `planning.history[${index}] is invalid`);
+            mergeLegacyEpic(entry, `planning.history[${index}]`, true, epics, stories, operations);
+        }
+        delete targetPlanning.history;
+        operations.push({ kind: 'remove-legacy', target: 'planning.history' });
+    }
+    if (targetPlanning && Object.keys(targetPlanning).length === 0)
+        delete target.planning;
+    if (target.schema_version !== 1) {
+        target.schema_version = 1;
+        operations.push({ kind: 'set-schema-version', target: 'schema_version' });
+    }
+    const targetCanonicalHash = stateMigrationDigest(target);
+    const steps = [...operations].sort((left, right) => {
+        const leftKey = `${left.kind}\0${left.source ?? ''}\0${left.target}`;
+        const rightKey = `${right.kind}\0${right.source ?? ''}\0${right.target}`;
+        return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+    });
+    const migratedEpicIds = Array.from(new Set(steps
+        .filter((step) => step.kind === 'merge-epic')
+        .map((step) => step.target.slice('epics.'.length)))).sort();
+    const migratedStoryIds = Array.from(new Set(steps
+        .filter((step) => step.kind === 'merge-story')
+        .map((step) => step.target.slice('stories.'.length)))).sort();
+    const operationId = `smig_${createHash('sha256')
+        .update(`${STATE_MIGRATION_PLAN_SCHEMA}\0${sourceCanonicalHash}\0${targetCanonicalHash}`)
+        .digest('hex')
+        .slice(0, 32)}`;
+    const plan = {
+        schemaVersion: STATE_MIGRATION_PLAN_SCHEMA,
+        operationId,
+        sourceSchemaVersion: state.schema_version === 0 || state.schema_version === 1 ? state.schema_version : 'absent',
+        targetSchemaVersion: 1,
+        sourceCanonicalHash,
+        targetCanonicalHash,
+        targetState: target,
+        steps,
+        migratedEpicIds,
+        migratedStoryIds,
+        preservedUnknownFieldCount: preservedUnknownFieldCount(state),
+        reasonCodes: ['validated_source', 'lossless_mapping_proven', 'deterministic_target'],
+    };
+    assertStateMigrationPlanV1(plan);
+    return {
+        kind: 'migrate',
+        plan,
+    };
+}
+function assertHash(value, field) {
+    if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) {
+        throw new StateMigrationHardStopError('migration_value_conflict', `${field} is not a SHA-256 digest`);
+    }
+}
+function assertBoundedStringArray(value, field, limit = 4096) {
+    if (!Array.isArray(value) || value.length > limit || value.some((entry) => typeof entry !== 'string' || entry.length === 0 || entry.length > 160 || !/^[A-Za-z0-9_.:+-]+$/.test(entry))) {
+        throw new StateMigrationHardStopError('migration_value_conflict', `${field} is invalid or unbounded`);
+    }
+}
+export function assertStateMigrationPlanV1(value) {
+    const allowedKeys = new Set([
+        'schemaVersion', 'operationId', 'sourceSchemaVersion', 'targetSchemaVersion',
+        'sourceCanonicalHash', 'targetCanonicalHash', 'targetState', 'steps',
+        'migratedEpicIds', 'migratedStoryIds', 'preservedUnknownFieldCount', 'reasonCodes',
+    ]);
+    if (!isPlainObject(value)
+        || Object.keys(value).some((key) => !allowedKeys.has(key))
+        || value.schemaVersion !== STATE_MIGRATION_PLAN_SCHEMA
+        || typeof value.operationId !== 'string' || !/^smig_[a-f0-9]{32}$/.test(value.operationId)
+        || ![0, 1, 'absent'].includes(value.sourceSchemaVersion)
+        || value.targetSchemaVersion !== 1
+        || !isPlainObject(value.targetState)
+        || typeof value.preservedUnknownFieldCount !== 'number'
+        || !Number.isSafeInteger(value.preservedUnknownFieldCount)
+        || value.preservedUnknownFieldCount < 0 || value.preservedUnknownFieldCount > 1_000_000) {
+        throw new StateMigrationHardStopError('migration_value_conflict', 'StateMigrationPlan/1.0 is invalid');
+    }
+    assertHash(value.sourceCanonicalHash, 'sourceCanonicalHash');
+    assertHash(value.targetCanonicalHash, 'targetCanonicalHash');
+    assertBoundedStringArray(value.migratedEpicIds, 'migratedEpicIds');
+    assertBoundedStringArray(value.migratedStoryIds, 'migratedStoryIds');
+    assertBoundedStringArray(value.reasonCodes, 'reasonCodes', 32);
+    if (!Array.isArray(value.steps) || value.steps.length > 8192 || value.steps.some((step) => !isPlainObject(step)
+        || Object.keys(step).some((key) => !['kind', 'source', 'target'].includes(key))
+        || !['initialize-collection', 'merge-epic', 'merge-story', 'preserve-legacy', 'remove-legacy', 'set-schema-version'].includes(String(step.kind))
+        || typeof step.target !== 'string' || step.target.length === 0 || step.target.length > 512 || !/^[A-Za-z0-9_.:[\]-]+$/.test(step.target)
+        || (step.source !== undefined && (typeof step.source !== 'string' || step.source.length > 512 || !/^[A-Za-z0-9_.:[\]-]+$/.test(step.source))))) {
+        throw new StateMigrationHardStopError('migration_value_conflict', 'steps are invalid or unbounded');
+    }
+    if (stateMigrationDigest(value.targetState) !== value.targetCanonicalHash) {
+        throw new StateMigrationHardStopError('migration_value_conflict', 'targetState hash mismatch');
+    }
+}
+export function assertStateMigrationReceiptV1(value) {
+    const allowedKeys = new Set([
+        'schemaVersion', 'operationId', 'outcome', 'sourceBytesHash', 'targetBytesHash',
+        'sourceCanonicalHash', 'targetCanonicalHash', 'backupHash', 'rollbackStatus',
+        'migratedEpicCount', 'migratedStoryCount', 'preservedUnknownFieldCount',
+        'reasonCodes', 'publicSafe',
+    ]);
+    if (!isPlainObject(value)
+        || Object.keys(value).some((key) => !allowedKeys.has(key))
+        || value.schemaVersion !== STATE_MIGRATION_RECEIPT_SCHEMA
+        || typeof value.operationId !== 'string' || !/^smig_[a-f0-9]{32}$/.test(value.operationId)
+        || !['applied', 'already-applied', 'blocked'].includes(String(value.outcome))
+        || !['not-required', 'restored', 'unverified'].includes(String(value.rollbackStatus))
+        || value.publicSafe !== true
+        || !Number.isSafeInteger(value.migratedEpicCount) || value.migratedEpicCount < 0 || value.migratedEpicCount > 4096
+        || !Number.isSafeInteger(value.migratedStoryCount) || value.migratedStoryCount < 0 || value.migratedStoryCount > 4096
+        || !Number.isSafeInteger(value.preservedUnknownFieldCount) || value.preservedUnknownFieldCount < 0 || value.preservedUnknownFieldCount > 1_000_000
+        || (value.backupHash !== null && typeof value.backupHash !== 'string')) {
+        throw new StateMigrationHardStopError('migration_value_conflict', 'StateMigrationReceipt/1.0 is invalid');
+    }
+    assertHash(value.sourceBytesHash, 'sourceBytesHash');
+    assertHash(value.targetBytesHash, 'targetBytesHash');
+    assertHash(value.sourceCanonicalHash, 'sourceCanonicalHash');
+    assertHash(value.targetCanonicalHash, 'targetCanonicalHash');
+    if (value.backupHash !== null)
+        assertHash(value.backupHash, 'backupHash');
+    assertBoundedStringArray(value.reasonCodes, 'reasonCodes', 32);
+}

package/packages/shared/dist/yoloop/canonical.js

@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto';
+export function canonicalYoloopJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalYoloopJson).join(',')}]`;
+    return `{${Object.entries(value)
+        .filter(([, child]) => child !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, child]) => `${JSON.stringify(key)}:${canonicalYoloopJson(child)}`)
+        .join(',')}}`;
+}
+export function yoloopDomainHash(domain, value) {
+    return createHash('sha256').update(`${domain}\0${canonicalYoloopJson(value)}`).digest('hex');
+}

package/packages/shared/dist/yoloop/operational-budget.js

@@ -0,0 +1,164 @@
+/**
+ * P220.11 -- Finite, tier-independent operational safety budget for yoloop.
+ *
+ * This contract deliberately does not model entitlement quota or graph
+ * retrieval limits.  It answers one question only: may an admitted run safely
+ * continue at this boundary?
+ */
+export const YOLOOP_OPERATIONAL_BUDGET_DIMENSIONS = [
+    'deadline',
+    'wall',
+    'turns',
+    'tokens',
+    'cost',
+    'toolCalls',
+    'attempts',
+    'feedback',
+    'depth',
+    'concurrency',
+    'risk',
+];
+export const DEFAULT_YOLOOP_OPERATIONAL_BUDGET_LIMITS = Object.freeze({
+    deadline: 6 * 60 * 60 * 1_000,
+    wall: 6 * 60 * 60 * 1_000,
+    turns: 256,
+    tokens: 5_000_000,
+    cost: 1_000_000,
+    toolCalls: 512,
+    attempts: 3,
+    feedback: 32,
+    depth: 1,
+    concurrency: 8,
+    risk: 100,
+});
+export const MAX_YOLOOP_OPERATIONAL_BUDGET_LIMITS = Object.freeze({
+    deadline: 24 * 60 * 60 * 1_000,
+    wall: 24 * 60 * 60 * 1_000,
+    turns: 1_024,
+    tokens: 20_000_000,
+    cost: 1_000_000,
+    toolCalls: 2_048,
+    attempts: 10,
+    feedback: 128,
+    depth: 1,
+    concurrency: 32,
+    risk: 100,
+});
+function isPositiveSafeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+/**
+ * Normalize operator input to finite limits. Invalid, absent, zero, negative,
+ * non-integer, non-finite and over-ceiling values fall back dimension by
+ * dimension; there is no unlimited sentinel.
+ */
+export function normalizeYoloopOperationalBudget(rawLimits, startedAtMs, defaults = DEFAULT_YOLOOP_OPERATIONAL_BUDGET_LIMITS, ceilings = MAX_YOLOOP_OPERATIONAL_BUDGET_LIMITS) {
+    if (!Number.isSafeInteger(startedAtMs) || startedAtMs < 0) {
+        throw new Error('YOLOOP_OPERATIONAL_BUDGET_INVALID');
+    }
+    const fallbackDimensions = [];
+    const limits = {};
+    for (const dimension of YOLOOP_OPERATIONAL_BUDGET_DIMENSIONS) {
+        const candidate = rawLimits?.[dimension];
+        const ceiling = ceilings[dimension];
+        const fallback = defaults[dimension];
+        if (!isPositiveSafeInteger(ceiling) || !isPositiveSafeInteger(fallback) || fallback > ceiling) {
+            throw new Error('YOLOOP_OPERATIONAL_BUDGET_INVALID');
+        }
+        if (!isPositiveSafeInteger(candidate) || candidate > ceiling) {
+            limits[dimension] = fallback;
+            fallbackDimensions.push(dimension);
+        }
+        else {
+            limits[dimension] = candidate;
+        }
+    }
+    return {
+        budget: {
+            schemaVersion: 'YoloopOperationalBudget/1.0',
+            startedAtMs,
+            limits: Object.freeze(limits),
+        },
+        fallbackDimensions: Object.freeze(fallbackDimensions),
+    };
+}
+/** Strict validation for state received over the persistence wire. */
+export function validateYoloopOperationalBudget(budget) {
+    if (!budget || typeof budget !== 'object')
+        return false;
+    const candidate = budget;
+    if (candidate.schemaVersion !== 'YoloopOperationalBudget/1.0'
+        || !Number.isSafeInteger(candidate.startedAtMs)
+        || Number(candidate.startedAtMs) < 0
+        || !candidate.limits)
+        return false;
+    return YOLOOP_OPERATIONAL_BUDGET_DIMENSIONS.every((dimension) => {
+        const value = candidate.limits?.[dimension];
+        return isPositiveSafeInteger(value)
+            && value <= MAX_YOLOOP_OPERATIONAL_BUDGET_LIMITS[dimension];
+    });
+}
+/**
+ * Evaluate in canonical O(11) order. Reaching a limit is exhaustion, so a
+ * boundary can never issue one more effect after consuming its full budget.
+ */
+export function evaluateYoloopOperationalBudget(input) {
+    if (!validateYoloopOperationalBudget(input.budget) || !Number.isSafeInteger(input.nowMs)) {
+        return { kind: 'invalid', reasonCode: 'YOLOOP_OPERATIONAL_BUDGET_INVALID', dimension: null };
+    }
+    const usage = {};
+    for (const dimension of YOLOOP_OPERATIONAL_BUDGET_DIMENSIONS) {
+        const rawUsed = input.usage[dimension];
+        if (!Number.isSafeInteger(rawUsed) || Number(rawUsed) < 0) {
+            return {
+                kind: 'invalid',
+                reasonCode: 'YOLOOP_OPERATIONAL_BUDGET_INVALID',
+                dimension,
+            };
+        }
+        usage[dimension] = Number(rawUsed);
+    }
+    const elapsed = input.nowMs - input.budget.startedAtMs;
+    if (!Number.isSafeInteger(elapsed) || elapsed < 0) {
+        return {
+            kind: 'invalid',
+            reasonCode: 'YOLOOP_OPERATIONAL_BUDGET_INVALID',
+            dimension: 'deadline',
+        };
+    }
+    usage.deadline = Math.max(usage.deadline, elapsed);
+    for (const dimension of YOLOOP_OPERATIONAL_BUDGET_DIMENSIONS) {
+        const used = usage[dimension];
+        const limit = input.budget.limits[dimension];
+        if (used >= limit) {
+            return {
+                kind: 'exhausted',
+                status: 'exhausted',
+                dimension,
+                limit,
+                used,
+                remaining: 0,
+                reasonCode: dimension === 'deadline'
+                    ? 'YOLOOP_SESSION_TIMEOUT'
+                    : 'YOLOOP_OPERATIONAL_BUDGET_EXHAUSTED',
+                usage: Object.freeze(usage),
+            };
+        }
+    }
+    return { kind: 'within-budget', usage: Object.freeze(usage) };
+}
+export function createZeroYoloopOperationalUsage() {
+    return Object.freeze({
+        deadline: 0,
+        wall: 0,
+        turns: 0,
+        tokens: 0,
+        cost: 0,
+        toolCalls: 0,
+        attempts: 0,
+        feedback: 0,
+        depth: 0,
+        concurrency: 0,
+        risk: 0,
+    });
+}