@aiwg/cli 2026.8.18 → 2026.8.20

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

@@ -0,0 +1,265 @@
+import { MISSION_API_VERSION, } 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))
+        throw new Error(`${label} must be an object.`);
+    return value;
+}
+function string(value) {
+    return typeof value === 'string' && value.length ? value : undefined;
+}
+function requiredId(record) {
+    const metadata = record.metadata && typeof record.metadata === 'object' ? record.metadata : {};
+    const id = string(record.missionId) ?? string(record.mission_id) ?? string(record.id)
+        ?? string(record.taskId) ?? string(record.task_id) ?? string(record.responseId) ?? string(metadata.id);
+    if (!id)
+        throw new Error('Mission source is missing a stable identifier.');
+    return id;
+}
+export function normalizeMissionState(nativeState) {
+    const state = String(nativeState ?? 'unknown').toLowerCase().replace(/_/g, '-');
+    if (['done', 'completed', 'succeeded', 'success'].includes(state))
+        return 'completed';
+    if (['aborted', 'cancelled', 'canceled'].includes(state))
+        return 'cancelled';
+    if (['failed', 'error', 'rejected', 'timed-out'].includes(state))
+        return 'failed';
+    if (['incomplete', 'budget-exhausted', 'max-iterations', 'max-tokens'].includes(state))
+        return 'incomplete';
+    if (['running', 'in-progress', 'working', 'started', 'assigned', 'admitted', 'starting'].includes(state))
+        return 'running';
+    if (['pending', 'submitted', 'queued', 'runnable', 'scheduled'].includes(state))
+        return 'pending';
+    if (['blocked', 'blocked-hitl', 'input-required', 'auth-required', 'paused', 'suspended'].includes(state))
+        return 'blocked';
+    if (['operator-review', 'operator-review-required', 'manual-review'].includes(state))
+        return 'operator-review';
+    if (['unknown', 'disconnected', 'detached', 'unreachable'].includes(state))
+        return 'unknown';
+    return 'unknown';
+}
+function knownKeysFor(source) {
+    const common = ['id', 'missionId', 'mission_id', 'taskId', 'task_id', 'responseId', 'title', 'goal', 'objective', 'prompt', 'completion', 'completionCriterion', 'completion_criterion', 'status', 'state', 'nativeState', 'createdAt', 'created_at', 'updatedAt', 'updated_at', 'metadata', 'spec', 'provenance', 'extensions', 'artifacts', 'output', 'partialOutput', 'error', 'checkpoint', 'cycles', 'activityLog', 'totalCost', 'runtimesUsed', 'apiVersion', 'api_version', 'schemaVersion', 'schema_version', 'kind', 'session_id', 'previous_response_id'];
+    if (source === 'uhp-2026-08-11')
+        common.push('object', 'model', 'incomplete_details', 'store', 'usage');
+    return new Set(common);
+}
+function extensions(record, source) {
+    const explicit = record.extensions && typeof record.extensions === 'object' ? structuredClone(record.extensions) : {};
+    if (record.metadata && typeof record.metadata === 'object')
+        explicit.metadata = structuredClone(record.metadata);
+    if (record.status && typeof record.status === 'object')
+        explicit.nativeStatus = structuredClone(record.status);
+    for (const [key, value] of Object.entries(record))
+        if (!knownKeysFor(source).has(key))
+            explicit[key] = structuredClone(value);
+    return explicit;
+}
+function artifacts(record) {
+    const values = Array.isArray(record.artifacts) ? record.artifacts : [];
+    return values.flatMap((item, index) => {
+        if (!item || typeof item !== 'object')
+            return [];
+        const artifact = item;
+        const id = string(artifact.id) ?? string(artifact.fileId) ?? string(artifact.file_id) ?? string(artifact.uri) ?? `artifact-${index}`;
+        return [{
+                id,
+                kind: string(artifact.kind) ?? 'other',
+                ...(string(artifact.uri) ? { uri: string(artifact.uri) } : {}),
+                ...(string(artifact.sha256) ? { sha256: string(artifact.sha256) } : {}),
+                ...(string(artifact.mediaType) ?? string(artifact.media_type) ? { mediaType: string(artifact.mediaType) ?? string(artifact.media_type) } : {}),
+                extensions: structuredClone(artifact),
+            }];
+    });
+}
+function uhpOutputArtifacts(record) {
+    const found = new Map();
+    function visit(value) {
+        if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const item = value;
+        const id = string(item.file_id);
+        if (id)
+            found.set(id, { id, kind: 'uhp-file', ...(string(item.media_type) ? { mediaType: string(item.media_type) } : {}), extensions: { 'uhp.file': structuredClone(item) } });
+        Object.values(item).forEach(visit);
+    }
+    visit(record.output);
+    return [...found.values()];
+}
+function nativeStateFor(source, record, statusRecord) {
+    const explicit = string(statusRecord.state) ?? string(record.nativeState) ?? string(record.status)
+        ?? string(record.state) ?? string(record.observed_state) ?? string(record.observedState) ?? string(record.nodeState);
+    if (explicit)
+        return explicit;
+    if (source === 'mission-ledger' && record.checkpoint && typeof record.checkpoint === 'object') {
+        const checkpoint = record.checkpoint;
+        if (Array.isArray(checkpoint.pending) && checkpoint.pending.length)
+            return 'running';
+        if (Array.isArray(checkpoint.failed) && checkpoint.failed.length)
+            return 'failed';
+        if (Array.isArray(checkpoint.completed) && checkpoint.completed.length)
+            return 'completed';
+    }
+    return 'unknown';
+}
+function sourceVersion(source, record) {
+    if (source === 'canonical')
+        return string(record.apiVersion) ?? 'unknown';
+    if (source === 'uhp-2026-08-11')
+        return '2026-08-11';
+    if (source === 'executor-v1')
+        return 'executor.aiwg.io/v1';
+    if (source === 'fleet-workload-v1')
+        return 'fleet-workload/v1';
+    if (source === 'graph-flow-v1')
+        return 'graph.flow.aiwg.io/v1';
+    if (source === 'activity-v1')
+        return 'activity.aiwg.io/v1';
+    return string(record.apiVersion) ?? string(record.api_version) ?? string(record.schemaVersion) ?? string(record.schema_version) ?? 'unversioned';
+}
+function assertSupported(version) {
+    const supported = new Set(['unversioned', MISSION_API_VERSION, '2026-08-11', 'executor.aiwg.io/v1', 'fleet-workload/v1', 'graph.flow.aiwg.io/v1', 'activity.aiwg.io/v1']);
+    if (supported.has(version))
+        return;
+    const major = version.match(/(?:^|\/)v(\d+)(?:$|[.-])/)?.[1];
+    if (major && major !== '1')
+        throw new Error(`Unsupported Mission source major version '${version}'; supported major is v1.`);
+    throw new Error(`Unsupported Mission source version '${version}'.`);
+}
+export function validateCanonicalMission(value) {
+    const record = object(value, 'Canonical Mission');
+    if (record.apiVersion !== MISSION_API_VERSION)
+        throw new Error(`Unsupported canonical Mission version '${String(record.apiVersion)}'.`);
+    if (record.kind !== 'Mission')
+        throw new Error("Canonical Mission kind must be 'Mission'.");
+    const metadata = object(record.metadata, 'Mission metadata');
+    const spec = object(record.spec, 'Mission spec');
+    const status = object(record.status, 'Mission status');
+    const provenance = object(record.provenance, 'Mission provenance');
+    if (!string(metadata.id) || !string(spec.objective) || !string(provenance.sourceContract) || !string(provenance.sourceVersion))
+        throw new Error('Canonical Mission is missing required identity, objective, or provenance.');
+    const state = normalizeMissionState(status.state);
+    if (status.state !== state)
+        throw new Error(`Canonical Mission state '${String(status.state)}' is not normalized.`);
+    if (status.terminal !== TERMINAL.has(state))
+        throw new Error(`Canonical Mission terminal flag contradicts state '${state}'.`);
+    if (!Array.isArray(status.artifacts))
+        throw new Error('Canonical Mission artifacts must be an array.');
+    return structuredClone(value);
+}
+export function decodeMission(input, source) {
+    const record = object(input);
+    if (source === 'canonical') {
+        const value = validateCanonicalMission(record);
+        return { value, sourceVersion: MISSION_API_VERSION, warnings: [], preservedExtensions: structuredClone(value.extensions ?? {}), lossReport: [] };
+    }
+    const version = sourceVersion(source, record);
+    assertSupported(version);
+    const statusRecord = record.status && typeof record.status === 'object' ? record.status : {};
+    const nativeState = nativeStateFor(source, record, statusRecord);
+    const state = normalizeMissionState(nativeState);
+    const objective = string(record.goal) ?? string(record.objective) ?? string(record.title) ?? string(record.prompt) ?? '(legacy mission objective unavailable)';
+    const completionCriterion = string(record.completionCriterion) ?? string(record.completion_criterion) ?? string(record.completion);
+    const preserved = extensions(record, source);
+    const warnings = [];
+    const lossReport = [];
+    if (objective.startsWith('(legacy'))
+        warnings.push('Source did not contain a mission objective; placeholder retained.');
+    if (state === 'unknown' && nativeState !== 'unknown')
+        warnings.push(`Unknown native state '${nativeState}' preserved beside normalized unknown state.`);
+    const sourceArtifacts = artifacts(record);
+    if (source === 'uhp-2026-08-11') {
+        const ids = new Set(sourceArtifacts.map(artifact => artifact.id));
+        for (const artifact of uhpOutputArtifacts(record))
+            if (!ids.has(artifact.id))
+                sourceArtifacts.push(artifact);
+    }
+    const budgets = record.budgets && typeof record.budgets === 'object' ? record.budgets : undefined;
+    const lineage = Array.isArray(record.lineage) ? record.lineage.flatMap(item => {
+        if (!item || typeof item !== 'object')
+            return [];
+        const entry = item;
+        return string(entry.relation) && string(entry.id) ? [{ relation: string(entry.relation), id: string(entry.id) }] : [];
+    }) : undefined;
+    const value = {
+        apiVersion: MISSION_API_VERSION,
+        kind: 'Mission',
+        metadata: {
+            id: requiredId(record),
+            ...(string(record.createdAt) ?? string(record.created_at) ? { createdAt: string(record.createdAt) ?? string(record.created_at) } : {}),
+            ...(string(record.updatedAt) ?? string(record.updated_at) ? { updatedAt: string(record.updatedAt) ?? string(record.updated_at) } : {}),
+            ...(string(record.previous_response_id) ? { previousId: string(record.previous_response_id) } : {}),
+            ...(lineage?.length ? { lineage } : {}),
+        },
+        spec: { objective, ...(completionCriterion ? { completionCriterion } : {}), ...(budgets ? { budgets: structuredClone(budgets) } : {}) },
+        status: {
+            state,
+            terminal: TERMINAL.has(state),
+            nativeState,
+            artifacts: sourceArtifacts,
+            ...(record.output !== undefined || record.partialOutput !== undefined || record.partial_output !== undefined ? { partialOutput: structuredClone(record.partialOutput ?? record.partial_output ?? record.output) } : {}),
+        },
+        provenance: { sourceContract: source, sourceVersion: version, ...(source === 'a2a' || source.startsWith('uhp') ? { transport: source.split('-')[0] } : {}), sourceId: requiredId(record) },
+        ...(Object.keys(preserved).length ? { extensions: { [`aiwg.source.${source}`]: preserved } } : {}),
+    };
+    return { value, sourceVersion: version, warnings, preservedExtensions: preserved, lossReport };
+}
+function projectionLosses(value, target) {
+    const losses = [];
+    if (value.status.verification?.length)
+        losses.push({ path: '/status/verification', reason: `${target} has no native verification ledger`, severity: 'warning' });
+    if (value.metadata.lineage?.length && !['mission-ledger', 'fleet-workload-v1', 'canonical'].includes(target))
+        losses.push({ path: '/metadata/lineage', reason: `${target} cannot represent full lineage`, severity: 'required' });
+    if (value.spec.budgets && !['fleet-workload-v1', 'canonical'].includes(target))
+        losses.push({ path: '/spec/budgets', reason: `${target} cannot represent every canonical budget`, severity: 'warning' });
+    return losses;
+}
+export function encodeMission(value, target, options = {}) {
+    const mission = validateCanonicalMission(value);
+    if (target === 'canonical')
+        return { value: mission, targetVersion: MISSION_API_VERSION, warnings: [], lossReport: [] };
+    const lossReport = projectionLosses(mission, target);
+    const required = lossReport.filter(loss => loss.severity === 'required');
+    if (required.length && !options.allowLoss)
+        throw new Error(`Projection to ${target} would silently lose required semantics: ${required.map(loss => loss.path).join(', ')}.`);
+    const base = {
+        missionId: mission.metadata.id,
+        goal: mission.spec.objective,
+        completionCriterion: mission.spec.completionCriterion,
+        status: mission.status.nativeState ?? mission.status.state,
+        artifacts: structuredClone(mission.status.artifacts),
+        partialOutput: structuredClone(mission.status.partialOutput),
+        lineage: structuredClone(mission.metadata.lineage ?? []),
+        extensions: {
+            'aiwg.mission.canonical': { apiVersion: mission.apiVersion, state: mission.status.state, lossReport },
+            ...(mission.extensions ?? {}),
+        },
+    };
+    let projected = base;
+    if (target === 'mission-plan')
+        projected = { missionId: base.missionId, goal: base.goal, completionCriterion: base.completionCriterion ?? '', cycles: [], extensions: base.extensions };
+    else if (target === 'mission-ledger')
+        projected = { ...base, activityLog: [], cycles: [], totalCost: 0, checkpoint: { completed: [], pending: [], failed: [] }, runtimesUsed: [] };
+    else if (target === 'uhp-2026-08-11')
+        projected = { id: mission.provenance.sourceId ?? mission.metadata.id, object: 'response', created_at: 0, status: base.status, model: '', output: mission.status.partialOutput ?? [], metadata: base.extensions };
+    else if (target === 'a2a')
+        projected = { id: mission.provenance.sourceId ?? mission.metadata.id, status: { state: base.status }, artifacts: base.artifacts, partialOutput: base.partialOutput, metadata: base.extensions };
+    else if (target === 'graph-flow-v1')
+        projected = { schemaVersion: 'graph.flow.aiwg.io/v1', runId: mission.metadata.id, nodeState: mission.status.state, metadata: base.extensions };
+    else if (target === 'cockpit')
+        projected = { id: mission.metadata.id, session_id: mission.metadata.id, source: mission.provenance.transport ?? mission.provenance.sourceContract, title: mission.spec.objective, completion: mission.spec.completionCriterion, status: mission.status.state, artifacts: base.artifacts, partialOutput: base.partialOutput, extensions: base.extensions };
+    else if (target === 'activity-v1')
+        projected = { event: 'mission.projected', missionId: mission.metadata.id, objective: mission.spec.objective, state: mission.status.state, metadata: base.extensions };
+    else if (target === 'executor-v1')
+        projected = { mission_id: mission.metadata.id, objective: mission.spec.objective, completion_criterion: mission.spec.completionCriterion, state: base.status, artifacts: base.artifacts, partial_output: base.partialOutput, metadata: base.extensions };
+    else if (target === 'fleet-workload-v1')
+        projected = { mission_id: mission.metadata.id, objective: mission.spec.objective, completion_criterion: mission.spec.completionCriterion, observed_state: base.status, budgets: mission.spec.budgets, artifacts: base.artifacts, partial_output: base.partialOutput, lineage: base.lineage, metadata: base.extensions };
+    else if (target === 'mission-control-session')
+        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 };
+}
+//# sourceMappingURL=codecs.js.map

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

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './codecs.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,2 @@
+export const MISSION_API_VERSION = 'mission.aiwg.io/v1';
+//# sourceMappingURL=types.js.map

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -22,6 +22,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, } from './workspace-context.js';
+import { dominantLineEnding, withLineEnding } from './line-endings.js';
 export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
 export const CLAUDE_HOOK_END = '<!-- AIWG:claude-md-hook:end -->';
 function buildClaudeArtifactOutputPolicy(policy = {}) {
@@ -77,7 +78,7 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
     catch {
         // Missing/legacy/temporarily malformed config receives the safe default.
     }
-    const block = buildClaudeHookBlock(policy);
+    let block = buildClaudeHookBlock(policy);
     // Case 1: CLAUDE.md does not exist — create a minimal one with just the block.
     let existing;
     try {
@@ -92,6 +93,8 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
         }
         throw err;
     }
+    const lineEnding = dominantLineEnding(existing);
+    block = withLineEnding(block, lineEnding);
     const startIdx = existing.indexOf(CLAUDE_HOOK_START);
     const endIdx = existing.indexOf(CLAUDE_HOOK_END);
     // Case 2: marker block does not exist — append the block to end of file.
@@ -117,8 +120,8 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
             return result;
         }
         // Ensure the file ends with a single newline before appending.
-        const trimmed = existing.replace(/\n+$/, '\n');
-        const updated = `${trimmed}\n${block}\n`;
+        const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
+        const updated = `${trimmed}${lineEnding}${block}${lineEnding}`;
         await fs.writeFile(claudeMdPath, updated, 'utf8');
         result.action = 'inserted';
         return result;
@@ -135,8 +138,8 @@ export async function ensureClaudeMdHook(projectPath, opts = {}) {
             await fs.writeFile(backupPath, existing, 'utf8');
             result.backupPath = backupPath;
         }
-        const trimmed = existing.replace(/\n+$/, '\n');
-        const updated = `${trimmed}\n${block}\n`;
+        const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
+        const updated = `${trimmed}${lineEnding}${block}${lineEnding}`;
         await fs.writeFile(claudeMdPath, updated, 'utf8');
         result.action = 'inserted';
         return result;

package/dist/src/smiths/context-pipeline/line-endings.js

@@ -0,0 +1,12 @@
+/** Select the majority line ending, preferring LF for ties and new files. */
+export function dominantLineEnding(content) {
+    const crlfCount = content.match(/\r\n/g)?.length ?? 0;
+    const newlineCount = content.match(/\n/g)?.length ?? 0;
+    const bareLfCount = newlineCount - crlfCount;
+    return crlfCount > bareLfCount ? '\r\n' : '\n';
+}
+/** Render generated text using the line-ending convention of existing content. */
+export function withLineEnding(content, lineEnding) {
+    return content.replace(/\r?\n/g, lineEnding);
+}
+//# sourceMappingURL=line-endings.js.map

package/dist/src/smiths/context-pipeline/managed-hook.js

@@ -14,6 +14,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { buildProviderBootstrapBlock } from './workspace-context.js';
+import { dominantLineEnding, withLineEnding } from './line-endings.js';
 export const CONTEXT_HOOK_START = '<!-- AIWG:context-hook:start -->';
 export const CONTEXT_HOOK_END = '<!-- AIWG:context-hook:end -->';
 /** The managed block — loads canonical workspace context before framework context. */
@@ -42,7 +43,7 @@ export function hasContextHook(content) {
  */
 export async function ensureManagedHook(filePath, opts = {}) {
     const base = path.basename(filePath);
-    const block = buildContextHookBlock(opts.provider);
+    let block = buildContextHookBlock(opts.provider);
     const result = { path: filePath, action: 'skipped', warnings: [] };
     let existing;
     try {
@@ -56,6 +57,8 @@ export async function ensureManagedHook(filePath, opts = {}) {
         }
         throw err;
     }
+    const lineEnding = dominantLineEnding(existing);
+    block = withLineEnding(block, lineEnding);
     // Already has both bare includes (operator wired them by hand) — nothing to do.
     if (!existing.includes(CONTEXT_HOOK_START) && /^[ \t]*@WORKSPACE\.md[ \t]*$/m.test(existing) && /^[ \t]*@AIWG\.md[ \t]*$/m.test(existing)) {
         result.action = 'unchanged';
@@ -65,16 +68,16 @@ export async function ensureManagedHook(filePath, opts = {}) {
     const e = existing.indexOf(CONTEXT_HOOK_END);
     // No managed block — append it to the end, preserving everything above.
     if (s === -1 && e === -1) {
-        const trimmed = existing.replace(/\n+$/, '\n');
-        await fs.writeFile(filePath, `${trimmed}\n${block}\n`, 'utf8');
+        const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
+        await fs.writeFile(filePath, `${trimmed}${lineEnding}${block}${lineEnding}`, 'utf8');
         result.action = 'inserted';
         return result;
     }
     // Malformed (one marker only) — repair only with --force to avoid clobbering.
     if (s === -1 || e === -1) {
         if (opts.force) {
-            const trimmed = existing.replace(/\n+$/, '\n');
-            await fs.writeFile(filePath, `${trimmed}\n${block}\n`, 'utf8');
+            const trimmed = existing.replace(/(?:\r?\n)+$/, lineEnding);
+            await fs.writeFile(filePath, `${trimmed}${lineEnding}${block}${lineEnding}`, 'utf8');
             result.action = 'inserted';
             return result;
         }

package/dist/src/smiths/context-pipeline/workspace-context.js

@@ -14,6 +14,7 @@ import { buildNormalizedAiwgMd } from './finalization.js';
 import { getProviderDefinition, listProviderDefinitions, } from '../../providers/provider-definitions.js';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
 import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../../config/project-artifacts.js';
+import { dominantLineEnding, withLineEnding } from './line-endings.js';
 export const WORKSPACE_MANAGED_START = '<!-- AIWG:workspace-context:start -->';
 export const WORKSPACE_MANAGED_END = '<!-- AIWG:workspace-context:end -->';
 export const WORKSPACE_OPERATOR_START = '<!-- AIWG:workspace-operator:start -->';
@@ -90,7 +91,8 @@ function replaceBlock(content, start, end, block) {
         return null;
     if (startIndex < 0 || endIndex < startIndex)
         throw new Error(`Malformed managed block: ${start} / ${end}`);
-    return content.slice(0, startIndex) + block + content.slice(endIndex + end.length);
+    const renderedBlock = withLineEnding(block, dominantLineEnding(content));
+    return content.slice(0, startIndex) + renderedBlock + content.slice(endIndex + end.length);
 }
 function stripGeneratedBlocks(content) {
     let stripped = content;

package/dist/src/storage/backend-contract.js

@@ -0,0 +1,64 @@
+/**
+ * Versioned capability contract for scalable storage and index backends.
+ *
+ * This contract describes semantics; it does not make optional capabilities
+ * available. Consumers must negotiate before using anything beyond the
+ * required baseline.
+ *
+ * @issue #2193
+ */
+export const STORAGE_BACKEND_CONTRACT = 'aiwg.storage-backend/v1';
+export class StorageCapabilityError extends Error {
+    code = 'AIWG_STORAGE_CAPABILITY_NEGOTIATION_FAILED';
+    constructor(message) {
+        super(message);
+        this.name = 'StorageCapabilityError';
+    }
+}
+/** Fail-closed negotiation. Unknown major contracts and missing capabilities never degrade silently. */
+export function negotiateStorageCapabilities(descriptor, request) {
+    if (request.contract !== STORAGE_BACKEND_CONTRACT) {
+        throw new StorageCapabilityError(`unsupported storage contract "${request.contract}"; backend provides ${STORAGE_BACKEND_CONTRACT}`);
+    }
+    if (request.acceptedSchemaVersions?.length &&
+        !request.acceptedSchemaVersions.includes(descriptor.schemaVersion)) {
+        throw new StorageCapabilityError(`backend schema ${descriptor.schemaVersion} is not in the accepted schema set`);
+    }
+    const available = new Set(descriptor.capabilities);
+    const missing = [...new Set(request.required)].filter(capability => !available.has(capability));
+    if (missing.length) {
+        throw new StorageCapabilityError(`backend ${descriptor.backend} lacks required capabilities: ${missing.sort().join(', ')}`);
+    }
+    return {
+        contract: STORAGE_BACKEND_CONTRACT,
+        backend: descriptor.backend,
+        schemaVersion: descriptor.schemaVersion,
+        capabilities: [...descriptor.capabilities].sort(),
+    };
+}
+const BASELINE = ['read', 'subsystem-isolation'];
+export const STORAGE_BACKEND_MATRIX = {
+    'json-filesystem': descriptor('json-filesystem', 'supported', BASELINE, 'filesystem', 'single-host', 'none', 'regenerable-index'),
+    graphology: descriptor('graphology', 'supported', BASELINE, 'process', 'local-process', 'none', 'regenerable-index'),
+    sqlite: descriptor('sqlite', 'supported', [...BASELINE, 'atomic-batch', 'consistent-snapshot', 'tombstones', 'idempotency-keys', 'filtered-query', 'cursor-pagination', 'backup', 'restore'], 'wal', 'single-host', 'serializable', 'regenerable-index'),
+    'fortemi-core-static': descriptor('fortemi-core-static', 'supported', ['read', 'filtered-query', 'recursive-traversal', 'set-operations'], 'filesystem', 'single-host', 'snapshot', 'static-cache'),
+    'fortemi-server': descriptor('fortemi-server', 'alpha', [...BASELINE, 'filtered-query', 'health', 'tls', 'tenant-isolation'], 'replicated', 'remote-service', 'none', 'remote-persistence'),
+    'postgres-direct': descriptor('postgres-direct', 'advanced', [], 'replicated', 'remote-service', 'none', 'canonical'),
+    'postgres-postgrest': descriptor('postgres-postgrest', 'advanced', [], 'replicated', 'remote-service', 'none', 'canonical'),
+    mysql: descriptor('mysql', 'deferred', [], 'replicated', 'remote-service', 'none', 'canonical'),
+};
+function descriptor(backend, maturity, capabilities, durability, availability, isolation, dataClass) {
+    return {
+        contract: STORAGE_BACKEND_CONTRACT,
+        backend,
+        implementationVersion: '1.0.0',
+        schemaVersion: '1',
+        maturity,
+        capabilities,
+        durability,
+        availability,
+        isolation,
+        dataClass,
+    };
+}
+//# sourceMappingURL=backend-contract.js.map

package/dist/src/storage/index.js

@@ -21,6 +21,8 @@ export { FilesystemAdapter } from './backends/fs.js';
 export { ObsidianAdapter } from './backends/obsidian.js';
 export { LogseqAdapter } from './backends/logseq.js';
 export { FortemiAdapter } from './backends/fortemi.js';
+export { STORAGE_BACKEND_CONTRACT, STORAGE_BACKEND_MATRIX, StorageCapabilityError, negotiateStorageCapabilities, } from './backend-contract.js';
+export { STORAGE_MIGRATION_PROTOCOL, MigrationProtocolError, StorageMigrationCoordinator, approvalDigest, digestRecords, validateManifest, } from './migration-protocol.js';
 let state = null;
 /**
  * Initialize or reset the registry for a given project root. Most