@aiwg/cli 2026.8.28 → 2026.9.1

package/dist/src/output-modes/registry.js

@@ -1,23 +1,57 @@
 import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
+import { tmpdir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { dirname, extname, join, resolve } from 'node:path';
 import { parse, stringify } from 'yaml';
+import { z } from 'zod';
+import { resolveUserConfigDir } from '../config/user-config-dir.mjs';
+const MODE_ID_PATTERN = /^[a-z0-9][a-z0-9.-]*$/;
 const PROTECTED = ['code', 'commands', 'citations', 'quoted-text', 'identifiers', 'machine-readable-blocks'];
 const STAGE_ORDER = ['semantic', 'voice', 'controlled-language', 'structure', 'presentation'];
+const modeIdSchema = z.string().regex(MODE_ID_PATTERN, 'must start with a lowercase letter or number and contain only lowercase letters, numbers, dots, or hyphens');
+const uniqueModeIds = z.array(modeIdSchema).refine(values => new Set(values).size === values.length, 'must not contain duplicates');
+const outputModeProfileSchema = z.object({
+    id: modeIdSchema,
+    version: z.string().min(1),
+    description: z.string().min(1),
+    kind: z.enum(['voice', 'controlled-language', 'structure', 'presentation']),
+    stage: z.enum(STAGE_ORDER),
+    order: z.number().int().optional(),
+    instructions: z.string(),
+    provenance: z.object({ source: z.string().min(1), license: z.string().min(1) }).strict(),
+    validation: z.object({
+        level: z.enum(['advisory', 'validated', 'conformance']),
+        hook: z.string().min(1).optional(),
+        standardVersion: z.string().min(1).optional(),
+    }).strict(),
+    compatible: uniqueModeIds.optional(),
+    conflicts: uniqueModeIds.optional(),
+    requires: uniqueModeIds.optional(),
+    supersedes: uniqueModeIds.optional(),
+    protectedContent: z.array(z.enum(PROTECTED)).refine(values => new Set(values).size === values.length, 'must not contain duplicates').optional(),
+    contextCost: z.number().int().nonnegative().optional(),
+    mergeStrategy: z.literal('weighted-voice').optional(),
+}).strict().superRefine((profile, ctx) => {
+    if (profile.validation.level !== 'advisory' && !profile.validation.hook) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['validation', 'hook'], message: `${profile.validation.level} modes require a validator hook` });
+    }
+    if (profile.validation.level === 'conformance' && !profile.validation.standardVersion) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['validation', 'standardVersion'], message: 'conformance modes require a standard version' });
+    }
+});
 const BUILTINS = [
     {
         id: 'unaltered', version: '1.0.0', description: 'No-op mode; preserves the provider output path unchanged.',
         kind: 'presentation', stage: 'presentation', order: -1000, instructions: '',
         provenance: { source: 'AIWG', license: 'MIT' }, validation: { level: 'advisory' }, contextCost: 0,
-        protectedContent: PROTECTED,
+        protectedContent: [...PROTECTED],
     },
     {
         id: 'wittgenstein-inspired', version: '1.0.0', description: 'Concise, proposition-oriented stylistic profile; not impersonation or attribution.',
         kind: 'voice', stage: 'voice', order: 100, instructions: 'Prefer concise propositions, clarify terms in use, and expose category errors. Do not imitate or attribute text to Ludwig Wittgenstein.',
         provenance: { source: 'AIWG original style guidance', license: 'MIT' }, validation: { level: 'advisory' }, contextCost: 48,
-        protectedContent: PROTECTED,
+        protectedContent: [...PROTECTED],
     },
     {
         id: 'asd-ste', version: '1.0.0', description: 'Operator-configured ASD Simplified Technical English adapter.',
@@ -25,13 +59,13 @@ const BUILTINS = [
         instructions: 'Apply only operator-supplied ASD-STE rules and approved terminology. Without licensed rules and a configured validator, describe output as advisory and never claim conformance.',
         provenance: { source: 'AIWG adapter; standard content supplied by operator', license: 'MIT adapter only' },
         validation: { level: 'advisory', standardVersion: 'operator-configured' }, contextCost: 64,
-        protectedContent: PROTECTED,
+        protectedContent: [...PROTECTED],
     },
 ];
 function profileDirs(cwd) {
     return [
         { dir: join(cwd, '.aiwg', 'output-modes'), source: 'project' },
-        { dir: join(homedir(), '.config', 'aiwg', 'output-modes'), source: 'user' },
+        { dir: join(resolveUserConfigDir(), 'output-modes'), source: 'user' },
     ];
 }
 async function readable(path) {
@@ -43,31 +77,33 @@ async function readable(path) {
         return false;
     }
 }
-function validateProfile(value, path) {
-    if (!value || typeof value !== 'object')
-        throw new Error(`Invalid output mode profile at ${path}: expected an object`);
-    const p = value;
-    for (const field of ['id', 'version', 'description', 'kind', 'stage', 'instructions', 'provenance', 'validation']) {
-        if (p[field] === undefined)
-            throw new Error(`Invalid output mode profile at ${path}: missing ${field}`);
+export function validateOutputModeProfile(value, path = '<profile>') {
+    const result = outputModeProfileSchema.safeParse(value);
+    if (!result.success) {
+        const details = result.error.issues
+            .map(issue => `${issue.path.length ? issue.path.join('.') : 'profile'}: ${issue.message}`)
+            .join('; ');
+        throw new Error(`Invalid output mode profile at ${path}: ${details}`);
     }
-    if (!['voice', 'controlled-language', 'structure', 'presentation'].includes(String(p.kind)))
-        throw new Error(`Invalid output mode kind in ${path}: ${p.kind}`);
-    if (!STAGE_ORDER.includes(String(p.stage)))
-        throw new Error(`Invalid output mode stage in ${path}: ${p.stage}`);
-    return p;
+    return result.data;
 }
 async function loadDirectory(dir, source) {
     if (!(await readable(dir)))
         return [];
     const result = [];
+    const seen = new Map();
     for (const name of (await readdir(dir)).sort()) {
         if (!['.yaml', '.yml', '.json'].includes(extname(name)))
             continue;
         const sourcePath = join(dir, name);
         const raw = await readFile(sourcePath, 'utf8');
         const value = extname(name) === '.json' ? JSON.parse(raw) : parse(raw);
-        result.push({ ...validateProfile(value, sourcePath), source, sourcePath });
+        const profile = validateOutputModeProfile(value, sourcePath);
+        const previous = seen.get(profile.id);
+        if (previous)
+            throw new Error(`Duplicate output mode '${profile.id}' in ${previous} and ${sourcePath}. Keep one definition per scope.`);
+        seen.set(profile.id, sourcePath);
+        result.push({ ...profile, source, sourcePath });
     }
     return result;
 }
@@ -84,7 +120,7 @@ async function loadVoiceAdapters(frameworkRoot) {
             id, version: String(voice.version ?? '1.0.0'), description: String(voice.description ?? `Adapted voice profile: ${id}`),
             kind: 'voice', stage: 'voice', order: 100, instructions: `Apply the existing voice profile '${id}' through voice-apply.`,
             provenance: { source: sourcePath, license: String(voice.license ?? 'project license') },
-            validation: { level: 'advisory' }, protectedContent: PROTECTED, contextCost: 32,
+            validation: { level: 'advisory' }, protectedContent: [...PROTECTED], contextCost: 32,
             mergeStrategy: 'weighted-voice', source: 'voice-adapter', sourcePath,
         });
     }
@@ -115,7 +151,10 @@ export async function readOutputModeState(cwd, scope) {
     if (!(await readable(path)))
         return { version: 1, modes: [] };
     const value = parse(await readFile(path, 'utf8'));
-    return { version: 1, modes: Array.isArray(value.modes) ? value.modes.map(String) : [] };
+    if (!value || value.version !== 1 || !Array.isArray(value.modes) || value.modes.some(mode => typeof mode !== 'string' || !MODE_ID_PATTERN.test(mode))) {
+        throw new Error(`Invalid output mode state at ${path}: expected version 1 and an array of valid mode IDs.`);
+    }
+    return { version: 1, modes: [...new Set(value.modes)] };
 }
 export async function writeOutputModeState(cwd, scope, modes) {
     const path = statePath(cwd, scope);
@@ -123,11 +162,16 @@ export async function writeOutputModeState(cwd, scope, modes) {
     await writeFile(path, stringify({ version: 1, modes }), 'utf8');
     return path;
 }
-export async function resolveOutputModes(cwd, frameworkRoot, invocation = []) {
+export async function resolveOutputModes(cwd, frameworkRoot, invocation = [], overrides = {}) {
     const registry = await loadOutputModeRegistry(cwd, frameworkRoot);
-    const project = await readOutputModeState(cwd, 'project');
-    const session = await readOutputModeState(cwd, 'session');
-    const selected = [...project.modes.map(id => ({ id, scope: 'project' })), ...session.modes.map(id => ({ id, scope: 'session' })), ...invocation.map(id => ({ id, scope: 'invocation' }))];
+    const project = overrides.project ?? (await readOutputModeState(cwd, 'project')).modes;
+    const session = overrides.session ?? (await readOutputModeState(cwd, 'session')).modes;
+    for (const [scope, modes] of [['project', project], ['session', session], ['invocation', invocation]]) {
+        if (!Array.isArray(modes) || modes.some(id => typeof id !== 'string' || !MODE_ID_PATTERN.test(id))) {
+            throw new Error(`Invalid ${scope} output mode selection: expected valid mode IDs.`);
+        }
+    }
+    const selected = [...project.map(id => ({ id, scope: 'project' })), ...session.map(id => ({ id, scope: 'session' })), ...invocation.map(id => ({ id, scope: 'invocation' }))];
     const effective = new Map();
     const diagnostics = [];
     for (const item of selected) {

package/dist/src/output-modes/runtime.js

@@ -16,8 +16,11 @@ function protectedPattern(classes) {
 function protect(content, classes) {
     const literals = [];
     const pattern = protectedPattern(classes);
+    let tokenPrefix = '\uE000AIWG_OUTPUT_MODE_';
+    while (content.includes(tokenPrefix))
+        tokenPrefix += '_';
     const protectedContent = pattern ? content.replace(pattern, value => {
-        const token = `\uE000${literals.length}\uE001`;
+        const token = `${tokenPrefix}${literals.length}\uE001`;
         literals.push({ token, value });
         return token;
     }) : content;
@@ -26,9 +29,10 @@ function protect(content, classes) {
 function restore(content, literals, mode) {
     let restored = content;
     for (const literal of literals) {
-        if (!restored.includes(literal.token))
-            throw new Error(`Output mode '${mode}' modified or removed a protected literal.`);
-        restored = restored.replaceAll(literal.token, literal.value);
+        const occurrences = restored.split(literal.token).length - 1;
+        if (occurrences !== 1)
+            throw new Error(`Output mode '${mode}' modified, removed, or duplicated a protected literal.`);
+        restored = restored.replace(literal.token, literal.value);
     }
     return restored;
 }
@@ -39,9 +43,10 @@ export async function applyOutputModes(input, modes, options) {
     const diagnostics = [];
     const applied = [];
     for (const mode of modes) {
-        const snapshot = content;
         const masked = protect(content, mode.protectedContent ?? []);
         const transformed = await options.transform(masked.content, mode);
+        if (typeof transformed !== 'string')
+            throw new Error(`Output mode '${mode.id}' transform returned a non-string result.`);
         content = restore(transformed, masked.literals, mode.id);
         if (mode.validation.level !== 'advisory') {
             if (!options.validate)
@@ -54,9 +59,6 @@ export async function applyOutputModes(input, modes, options) {
                 return { content: input, diagnostics, applied, fallback: 'unaltered' };
             }
         }
-        // A transform may only change semantic presentation, never return an absent result.
-        if (typeof content !== 'string')
-            content = snapshot;
         applied.push(mode.id);
     }
     return { content, diagnostics, applied, fallback: 'none' };

package/dist/src/plugin/skill-command-translator.js

@@ -38,6 +38,7 @@ const SKILLS_ONLY_PROVIDERS = new Set([
     'cursor',
     'hermes',
     'openhuman',
+    'pi',
 ]);
 /**
  * Check if a provider needs command files generated from skills.

package/dist/src/providers/capability-matrix.yaml

@@ -470,6 +470,47 @@ providers:
     deploy_target: mixed
     aggregated_output: true
 
+  pi:
+    display_name: Pi Coding Agent
+    aliases:
+      - pi-coding-agent
+    status: experimental
+    daemon_tier: unsupported
+    daemon_pty_adapter: false
+    artifact_paths:
+      agents: .agents/skills/
+      commands: .pi/prompts/
+      skills: .pi/skills/
+      skills_cross_agent: .agents/skills/
+      rules: AGENTS.md
+      behaviors: .pi/extensions/
+    native_features:
+      cron: false
+      agent_teams: false
+      tasks: false
+      mcp: false
+      behaviors: false
+      mission_control: false
+      daemon: false
+    emulation:
+      cron: external-trigger
+      agent_teams: aiwg-mc
+      tasks: aiwg-mc
+      mcp: null
+      behaviors: null
+      mission_control: aiwg-mc
+      daemon: null
+    hook_wiring:
+      at_link_support: false
+      fallback: full-inject
+      context_file: AGENTS.md
+    interaction:
+      structured_questions: none
+      fallback: markdown
+      notes: Pi does not expose a built-in structured question tool.
+    deploy_target: project
+    aggregated_output: false
+
 # Feature definitions — documents what each feature key means and
 # what emulation strategies are available when native support is absent.
 features:

package/dist/src/providers/provider-definitions.js

@@ -21,6 +21,7 @@ const ProviderDefinitionSchema = z.object({
         'opencode',
         'openclaw',
         'openhuman',
+        'pi',
         'warp',
         'windsurf',
         'generic',
@@ -131,6 +132,7 @@ export const PROVIDER_IDS = [
     'opencode',
     'openclaw',
     'openhuman',
+    'pi',
     'warp',
     'windsurf',
     'generic',
@@ -191,6 +193,17 @@ const CONTEXT_CONTRACTS = {
         bootstrapTargets: ['AGENTS.md'], maxContextBytes: null, recommendedMaxLines: null, nestedContext: false, support: 'degraded',
         verification: { method: 'AIWG mixed-scope adapter contract; host loading remains capability-dependent', source: 'agentic/code/providers/capability-matrix.yaml', lastVerified: VERIFIED_ON },
     },
+    pi: {
+        startupFiles: ['AGENTS.override.md', 'AGENTS.md', 'CLAUDE.md'],
+        precedence: ['provider/system', 'root-to-cwd context chain', 'AGENTS.override.md supersedes same-directory AGENTS.md and CLAUDE.md'],
+        loadMode: 'prose-directive', includeSyntax: null, configRegistration: null,
+        bootstrapTargets: ['AGENTS.md'], maxContextBytes: null, recommendedMaxLines: null, nestedContext: true, support: 'supported',
+        verification: {
+            method: 'Pi coding-agent resource loader and official README context-file documentation',
+            source: 'https://github.com/earendil-works/pi/blob/79680533c6b898894f2d2421c7f640b212d3dfdd/packages/coding-agent/README.md#context-files',
+            lastVerified: '2026-09-03',
+        },
+    },
     warp: {
         startupFiles: ['WARP.md', 'AGENTS.md'], precedence: ['provider/system', 'subdirectory rule', 'root rule', 'global rule'],
         loadMode: 'prose-directive', includeSyntax: null, configRegistration: null,
@@ -656,6 +669,65 @@ const BUILT_IN_SEEDS = [
         },
         matrixRef: 'openhuman',
     },
+    {
+        id: 'pi',
+        aliases: ['pi-coding-agent'],
+        builtIn: true,
+        surfaces: {
+            primary: 'pi',
+            compatibility: ['pi-coding-agent'],
+            precedence: ['AGENTS.override.md', 'AGENTS.md', '.agents/skills/', '.pi/skills/', '.pi/prompts/'],
+            related: [],
+        },
+        detection: {
+            // PI_CODING_AGENT_DIR only relocates configuration; it is deliberately
+            // not an active-runtime marker. Availability is proven by process or executable.
+            env: [],
+            process: ['pi'],
+            capabilityId: 'pi',
+        },
+        paths: {
+            artifacts: {
+                agents: '.agents/skills',
+                commands: '.pi/prompts',
+                skills: '.pi/.aiwg/skills',
+                rules: null,
+                behaviors: '.pi/extensions',
+            },
+            kernelSkills: '.agents/skills',
+            contextDiscovery: {
+                agents: '.agents/skills',
+                skills: '.agents/skills',
+                rules: null,
+                behaviors: '.pi/extensions',
+            },
+            configFile: 'AGENTS.md',
+            contextFiles: { aiwgMd: true, agentsMd: true, claudeMdHook: false, hookFile: null, contextFile: 'AGENTS.md' },
+        },
+        smithPaths: {
+            agents: '.agents/skills',
+            commands: '.pi/prompts',
+            skills: '.pi/skills',
+            rules: null,
+            fileExtension: '.md',
+            configFile: 'AGENTS.md',
+            aggregated: false,
+        },
+        skillNamespace: {
+            deploymentGroup: 'deep-recursion',
+            pathType: 'project',
+            skillsBaseDir: '.pi/skills',
+            subdirLayout: true,
+        },
+        adapters: {
+            agentFormat: 'agents-md',
+            hookBridge: null,
+            mcpInjection: null,
+            contextAggregation: 'agents-md',
+            ruleFormat: 'agents-md-section',
+        },
+        matrixRef: 'pi',
+    },
     {
         id: 'warp',
         aliases: [],

package/dist/src/providers/provider-inventory.js

@@ -14,6 +14,7 @@ const PROVIDER_EXECUTABLES = {
     opencode: ['opencode'],
     openclaw: ['openclaw'],
     openhuman: ['openhuman'],
+    pi: ['pi'],
     warp: ['warp'],
     windsurf: ['windsurf'],
 };

package/dist/src/schema/catalog.js

@@ -0,0 +1,234 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { createDiagnostic, hasSchemaErrors, SCHEMA_DIAGNOSTIC_CODES } from './diagnostics.js';
+import { diagnosePolicy, resolveEffectivePolicy } from './policy.js';
+function parseJson(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isDomainManifest(value) {
+    return (isRecord(value) &&
+        value.schemaVersion === '1' &&
+        typeof value.domain === 'string' &&
+        isRecord(value.owner) &&
+        typeof value.owner.id === 'string' &&
+        Array.isArray(value.artifacts));
+}
+function isCatalogSource(value) {
+    return isRecord(value) && value.schemaVersion === '1' && Array.isArray(value.domains);
+}
+function safePath(rootDir, path) {
+    const absolute = resolve(rootDir, path);
+    const rel = relative(resolve(rootDir), absolute);
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel)) ? absolute : undefined;
+}
+function sha256(path) {
+    return `sha256:${createHash('sha256').update(readFileSync(path)).digest('hex')}`;
+}
+function validateArtifactShape(artifact, domain) {
+    const diagnostics = [];
+    const required = [
+        'logicalName',
+        'id',
+        'version',
+        'format',
+        'lifecycle',
+        'owner',
+        'authority',
+    ];
+    for (const field of required) {
+        if (artifact[field] === undefined || artifact[field] === '') {
+            diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidManifest, `Artifact in domain ${domain} is missing required field ${field}`, { artifactId: artifact.id }));
+        }
+    }
+    if (artifact.format === 'json-schema' && !artifact.dialect) {
+        diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidManifest, 'JSON Schema artifacts require a dialect', {
+            artifactId: artifact.id,
+        }));
+    }
+    if (artifact.lifecycle === 'deprecated' && artifact.deprecation === undefined) {
+        diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidManifest, 'Deprecated artifacts require deprecation data', {
+            artifactId: artifact.id,
+        }));
+    }
+    return diagnostics;
+}
+function walkSchemaFiles(root) {
+    if (!existsSync(root))
+        return [];
+    const result = [];
+    for (const entry of readdirSync(root).sort()) {
+        const path = resolve(root, entry);
+        const stat = statSync(path);
+        if (stat.isDirectory())
+            result.push(...walkSchemaFiles(path));
+        else if (/\.schema\.json$/u.test(entry))
+            result.push(path);
+    }
+    return result;
+}
+function readSchemaId(path) {
+    try {
+        const value = parseJson(path);
+        return isRecord(value) && typeof value.$id === 'string' ? value.$id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function compileSchemaCatalog(source, manifests, options) {
+    const rootDir = resolve(options.rootDir);
+    const diagnostics = [];
+    const entries = [];
+    const ids = new Map();
+    const names = new Map();
+    const authorities = new Map();
+    const declaredPaths = new Map();
+    for (const manifest of [...manifests].sort((a, b) => a.domain.localeCompare(b.domain))) {
+        for (const artifact of [...manifest.artifacts].sort((a, b) => `${a.logicalName}\0${a.version}\0${a.id}`.localeCompare(`${b.logicalName}\0${b.version}\0${b.id}`))) {
+            diagnostics.push(...validateArtifactShape(artifact, manifest.domain));
+            const nameVersion = `${artifact.logicalName}@${artifact.version}`;
+            if (ids.has(artifact.id)) {
+                diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.duplicateId, `Duplicate schema id ${artifact.id}`, { artifactId: artifact.id, details: { firstDomain: ids.get(artifact.id), secondDomain: manifest.domain } }));
+            }
+            else
+                ids.set(artifact.id, manifest.domain);
+            if (names.has(nameVersion)) {
+                diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.duplicateNameVersion, `Duplicate schema name and version ${nameVersion}`, { artifactId: artifact.id }));
+            }
+            else
+                names.set(nameVersion, artifact.id);
+            let digest = artifact.digest;
+            if (artifact.authority.kind === 'canonical') {
+                const canonicalPath = artifact.authority.path;
+                if (!canonicalPath) {
+                    diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidManifest, 'Canonical authority requires a path', { artifactId: artifact.id }));
+                }
+                else {
+                    const absolute = safePath(rootDir, canonicalPath);
+                    if (!absolute)
+                        diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.pathOutsideRoot, `Authority path escapes repository root: ${canonicalPath}`, { artifactId: artifact.id, path: canonicalPath }));
+                    else if (!existsSync(absolute))
+                        diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.missingPath, `Authority path does not exist: ${canonicalPath}`, { artifactId: artifact.id, path: canonicalPath }));
+                    else {
+                        const normalized = relative(rootDir, absolute).split(sep).join('/');
+                        const previous = authorities.get(normalized);
+                        if (previous)
+                            diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.duplicateAuthority, `Canonical path ${normalized} is claimed by ${previous} and ${artifact.id}`, { artifactId: artifact.id, path: normalized }));
+                        else
+                            authorities.set(normalized, artifact.id);
+                        declaredPaths.set(normalized, { id: artifact.id, projection: false });
+                        const actual = sha256(absolute);
+                        if (digest && digest !== actual)
+                            diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.digestMismatch, `Digest mismatch for ${normalized}`, { artifactId: artifact.id, path: normalized, details: { declared: digest, actual } }));
+                        digest = actual;
+                    }
+                }
+            }
+            for (const projection of artifact.projections ?? []) {
+                const absolute = safePath(rootDir, projection.path);
+                if (!absolute)
+                    diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.pathOutsideRoot, `Projection path escapes repository root: ${projection.path}`, { artifactId: artifact.id, path: projection.path }));
+                else if (!existsSync(absolute))
+                    diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.missingPath, `Projection path does not exist: ${projection.path}`, { artifactId: artifact.id, path: projection.path }));
+                else {
+                    const normalized = relative(rootDir, absolute).split(sep).join('/');
+                    declaredPaths.set(normalized, { id: artifact.id, projection: true });
+                    if (projection.digest && projection.digest !== sha256(absolute))
+                        diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.digestMismatch, `Projection digest mismatch for ${normalized}`, { artifactId: artifact.id, path: normalized }));
+                }
+            }
+            const effectivePolicy = resolveEffectivePolicy(source.policy, manifest, artifact);
+            diagnostics.push(...diagnosePolicy(effectivePolicy, artifact.id, options.now));
+            if (effectivePolicy.requireDigest && artifact.digest === undefined) {
+                diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidManifest, 'Effective policy requires a declared digest', { artifactId: artifact.id }));
+            }
+            entries.push({ artifact, domain: manifest.domain, ...(digest === undefined ? {} : { digest }), effectivePolicy });
+        }
+    }
+    for (const entry of entries) {
+        for (const dependency of entry.artifact.dependencies ?? []) {
+            if (!ids.has(dependency.id))
+                diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.unresolvedDependency, `Unresolved dependency ${dependency.id}`, { artifactId: entry.artifact.id, details: { dependency: dependency.id } }));
+        }
+    }
+    for (const inventoryRoot of options.inventoryRoots ?? []) {
+        const absoluteRoot = safePath(rootDir, inventoryRoot);
+        if (!absoluteRoot) {
+            diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.pathOutsideRoot, `Inventory root escapes repository root: ${inventoryRoot}`, { path: inventoryRoot }));
+            continue;
+        }
+        for (const file of walkSchemaFiles(absoluteRoot)) {
+            const normalized = relative(rootDir, file).split(sep).join('/');
+            if (!declaredPaths.has(normalized)) {
+                const schemaId = readSchemaId(file);
+                const canonical = schemaId === undefined ? undefined : entries.find((entry) => entry.artifact.id === schemaId);
+                diagnostics.push(createDiagnostic(canonical ? SCHEMA_DIAGNOSTIC_CODES.undeclaredMirror : SCHEMA_DIAGNOSTIC_CODES.undeclaredCanonical, canonical
+                    ? `Schema file shares ${schemaId} but is not declared as a mirror: ${normalized}`
+                    : `Schema file is not registered: ${normalized}`, { path: normalized, ...(schemaId === undefined ? {} : { details: { schemaId } }) }));
+            }
+        }
+    }
+    entries.sort((a, b) => `${a.artifact.id}\0${a.artifact.version}`.localeCompare(`${b.artifact.id}\0${b.artifact.version}`));
+    const catalog = { schemaVersion: '1', entries, domains: [...new Set(manifests.map((manifest) => manifest.domain))].sort() };
+    return { catalog, diagnostics, valid: !hasSchemaErrors(diagnostics) };
+}
+export function loadSchemaCatalog(options) {
+    const rootDir = resolve(options.rootDir);
+    const catalogPath = resolve(rootDir, options.catalogPath ?? 'schemas/catalog/catalog.json');
+    const diagnostics = [];
+    if (!existsSync(catalogPath)) {
+        diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.missingPath, `Catalog does not exist: ${relative(rootDir, catalogPath)}`, { path: relative(rootDir, catalogPath) }));
+        return { diagnostics, valid: false };
+    }
+    let source;
+    try {
+        source = parseJson(catalogPath);
+    }
+    catch (error) {
+        diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidCatalog, `Cannot parse catalog: ${error instanceof Error ? error.message : String(error)}`, { path: relative(rootDir, catalogPath) }));
+        return { diagnostics, valid: false };
+    }
+    if (!isCatalogSource(source)) {
+        diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidCatalog, 'Catalog must use schemaVersion 1 and contain a domains array', { path: relative(rootDir, catalogPath) }));
+        return { diagnostics, valid: false };
+    }
+    const manifests = [];
+    for (const item of source.domains) {
+        let candidate = item;
+        let path;
+        if (typeof item === 'string') {
+            path = resolve(dirname(catalogPath), item);
+            if (!safePath(rootDir, relative(rootDir, path))) {
+                diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.pathOutsideRoot, `Domain manifest escapes repository root: ${item}`, { path: item }));
+                continue;
+            }
+            if (!existsSync(path)) {
+                diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.missingPath, `Domain manifest does not exist: ${item}`, { path: item }));
+                continue;
+            }
+            try {
+                candidate = parseJson(path);
+            }
+            catch (error) {
+                diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidManifest, `Cannot parse domain manifest ${item}: ${error instanceof Error ? error.message : String(error)}`, { path: item }));
+                continue;
+            }
+        }
+        if (!isDomainManifest(candidate)) {
+            diagnostics.push(createDiagnostic(SCHEMA_DIAGNOSTIC_CODES.invalidManifest, 'Domain manifest must use schemaVersion 1 and contain domain, owner, and artifacts', path ? { path: relative(rootDir, path) } : {}));
+            continue;
+        }
+        manifests.push(candidate);
+    }
+    const result = compileSchemaCatalog(source, manifests, options);
+    return { catalog: result.catalog, diagnostics: [...diagnostics, ...result.diagnostics], valid: diagnostics.length === 0 && result.valid };
+}
+/** Serialize compiler output without timestamps or filesystem-specific data. */
+export function serializeCompiledSchemaCatalog(catalog) {
+    return `${JSON.stringify(catalog, null, 2)}\n`;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/src/schema/compatibility.js

@@ -0,0 +1,42 @@
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function strings(value) {
+    return new Set(Array.isArray(value) ? value.filter((item) => typeof item === 'string') : []);
+}
+/** Conservative backward-compatibility analysis: unknown means human review, never an optimistic pass. */
+export function analyzeBackwardCompatibility(before, after) {
+    const left = record(before);
+    const right = record(after);
+    if (!left || !right)
+        return { status: 'unknown', direction: 'backward', reasons: ['schemas are not JSON objects'] };
+    if (JSON.stringify(left) === JSON.stringify(right))
+        return { status: 'compatible', direction: 'backward', reasons: ['schemas are identical'] };
+    const reasons = [];
+    if (left.type !== undefined && right.type !== undefined && JSON.stringify(left.type) !== JSON.stringify(right.type))
+        reasons.push('accepted root type changed');
+    const oldRequired = strings(left.required);
+    for (const field of strings(right.required))
+        if (!oldRequired.has(field))
+            reasons.push(`required property added: ${field}`);
+    const oldProperties = record(left.properties) ?? {};
+    const newProperties = record(right.properties) ?? {};
+    for (const field of Object.keys(oldProperties))
+        if (!(field in newProperties))
+            reasons.push(`property removed: ${field}`);
+    if (left.additionalProperties !== false && right.additionalProperties === false)
+        reasons.push('additional properties changed from allowed to forbidden');
+    const oldEnum = strings(left.enum);
+    const newEnum = strings(right.enum);
+    if (oldEnum.size && newEnum.size)
+        for (const member of oldEnum)
+            if (!newEnum.has(member))
+                reasons.push(`enum member removed: ${member}`);
+    return reasons.length
+        ? { status: 'breaking', direction: 'backward', reasons }
+        : { status: 'unknown', direction: 'backward', reasons: ['no conservative breaking rule matched; review is required'] };
+}
+export function analyzeCompatibilityChain(schemas) {
+    return schemas.slice(1).map((schema, index) => analyzeBackwardCompatibility(schemas[index], schema));
+}
+//# sourceMappingURL=compatibility.js.map