@cleocode/contracts 2026.5.111 → 2026.5.113

package/dist/config/__tests__/manifest.test.js

@@ -0,0 +1,143 @@
+/**
+ * Tests for the ConfigManifest contract (T9876 / Saga T9855 / ADR-076).
+ *
+ * Covers:
+ * - Schema round-trip for each of the 4 built-in entries.
+ * - Merge-precedence invariant (project > global > defaults).
+ * - Metadata-scope isolation (NOT in the merge chain).
+ * - {@link DriftDetection} exhaustiveness via a `never` fallback switch.
+ *
+ * @task T9876
+ */
+import { describe, expect, it } from 'vitest';
+import { CLEO_CONFIG_MANIFEST, CONFIG_MANIFEST_ENTRIES, configManifestEntrySchema, GLOBAL_CLEO_CONFIG_MANIFEST, PROJECT_CONTEXT_MANIFEST, PROJECT_INFO_MANIFEST, } from '../manifest.js';
+describe('ConfigManifest built-in entries', () => {
+    const builtins = [
+        ['PROJECT_INFO_MANIFEST', PROJECT_INFO_MANIFEST],
+        ['PROJECT_CONTEXT_MANIFEST', PROJECT_CONTEXT_MANIFEST],
+        ['CLEO_CONFIG_MANIFEST', CLEO_CONFIG_MANIFEST],
+        ['GLOBAL_CLEO_CONFIG_MANIFEST', GLOBAL_CLEO_CONFIG_MANIFEST],
+    ];
+    for (const [name, entry] of builtins) {
+        it(`${name} validates against configManifestEntrySchema`, () => {
+            const parsed = configManifestEntrySchema.parse(entry);
+            expect(parsed.id).toBe(entry.id);
+            expect(parsed.scope).toBe(entry.scope);
+            expect(parsed.path).toBe(entry.path);
+            expect(parsed.mergePrecedence).toBe(entry.mergePrecedence);
+            expect(parsed.driftDetection).toBe(entry.driftDetection);
+        });
+    }
+    it('CONFIG_MANIFEST_ENTRIES contains all 4 built-in entries', () => {
+        const ids = CONFIG_MANIFEST_ENTRIES.map((e) => e.id).sort();
+        expect(ids).toEqual([
+            'cleo-config-global',
+            'cleo-config-project',
+            'project-context',
+            'project-info',
+        ]);
+    });
+    it('CONFIG_MANIFEST_ENTRIES is frozen', () => {
+        expect(Object.isFrozen(CONFIG_MANIFEST_ENTRIES)).toBe(true);
+    });
+});
+describe('Merge-precedence invariant (project > global > defaults)', () => {
+    it('project precedence > global precedence (higher wins)', () => {
+        expect(CLEO_CONFIG_MANIFEST.mergePrecedence).toBeGreaterThan(GLOBAL_CLEO_CONFIG_MANIFEST.mergePrecedence);
+    });
+    it('canonical precedence values: project=20, global=10, metadata=0', () => {
+        expect(CLEO_CONFIG_MANIFEST.mergePrecedence).toBe(20);
+        expect(GLOBAL_CLEO_CONFIG_MANIFEST.mergePrecedence).toBe(10);
+        expect(PROJECT_INFO_MANIFEST.mergePrecedence).toBe(0);
+        expect(PROJECT_CONTEXT_MANIFEST.mergePrecedence).toBe(0);
+    });
+    it('cascade-resolver sort order yields global then project (project wins)', () => {
+        const cascadeEntries = CONFIG_MANIFEST_ENTRIES.filter((e) => e.scope === 'global' || e.scope === 'project')
+            .slice() // copy before sort — array is frozen
+            .sort((a, b) => a.mergePrecedence - b.mergePrecedence);
+        expect(cascadeEntries.map((e) => e.scope)).toEqual(['global', 'project']);
+    });
+});
+describe('Metadata-scope isolation', () => {
+    it('metadata entries are NOT in the cascade merge chain', () => {
+        const cascadeScopes = CONFIG_MANIFEST_ENTRIES.filter((e) => e.scope !== 'metadata').map((e) => e.scope);
+        expect(cascadeScopes).toEqual(expect.arrayContaining(['global', 'project']));
+        expect(cascadeScopes).not.toContain('metadata');
+    });
+    it('all metadata entries have mergePrecedence 0 (separate channel)', () => {
+        const metadataEntries = CONFIG_MANIFEST_ENTRIES.filter((e) => e.scope === 'metadata');
+        expect(metadataEntries.length).toBeGreaterThan(0);
+        for (const e of metadataEntries) {
+            expect(e.mergePrecedence).toBe(0);
+        }
+    });
+});
+describe('DriftDetection exhaustiveness (type-level)', () => {
+    it('switch over DriftDetection covers all variants with never fallback', () => {
+        const describe_ = (d) => {
+            switch (d) {
+                case 'schema-validate':
+                    return 'schema-validate';
+                case 'staleness-gate':
+                    return 'staleness-gate';
+                case 'value-diff':
+                    return 'value-diff';
+                case 'none':
+                    return 'none';
+                default: {
+                    // If a new variant is added without updating this switch, TS will
+                    // refuse to assign it to `never` at compile time.
+                    const _exhaustive = d;
+                    return _exhaustive;
+                }
+            }
+        };
+        expect(describe_('schema-validate')).toBe('schema-validate');
+        expect(describe_('staleness-gate')).toBe('staleness-gate');
+        expect(describe_('value-diff')).toBe('value-diff');
+        expect(describe_('none')).toBe('none');
+    });
+});
+describe('configManifestEntrySchema rejects invalid input', () => {
+    it('rejects empty id', () => {
+        const result = configManifestEntrySchema.safeParse({
+            id: '',
+            scope: 'project',
+            path: '.cleo/config.json',
+            mergePrecedence: 20,
+            driftDetection: 'schema-validate',
+        });
+        expect(result.success).toBe(false);
+    });
+    it('rejects unknown scope', () => {
+        const result = configManifestEntrySchema.safeParse({
+            id: 'x',
+            scope: 'workspace',
+            path: '.cleo/x.json',
+            mergePrecedence: 0,
+            driftDetection: 'none',
+        });
+        expect(result.success).toBe(false);
+    });
+    it('rejects negative mergePrecedence', () => {
+        const result = configManifestEntrySchema.safeParse({
+            id: 'x',
+            scope: 'project',
+            path: '.cleo/x.json',
+            mergePrecedence: -1,
+            driftDetection: 'none',
+        });
+        expect(result.success).toBe(false);
+    });
+    it('rejects unknown driftDetection variant', () => {
+        const result = configManifestEntrySchema.safeParse({
+            id: 'x',
+            scope: 'project',
+            path: '.cleo/x.json',
+            mergePrecedence: 0,
+            driftDetection: 'sha-compare',
+        });
+        expect(result.success).toBe(false);
+    });
+});
+//# sourceMappingURL=manifest.test.js.map

package/dist/config/__tests__/manifest.test.js.map

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

package/dist/config/manifest.d.ts

@@ -0,0 +1,158 @@
+/**
+ * ConfigManifest contract — declarative registry of every config-like file CLEO
+ * reads, writes, or merges, with its scope, schema, merge precedence, and the
+ * drift-detection strategy applied to it.
+ *
+ * Foundation for the CORE SSoT config registry (T9878) and the `resolveCleoConfig`
+ * cascade resolver. Built-in entries cover the four canonical CLEO files:
+ *
+ * - `~/.cleo/config.json`          (`global`,   precedence 10)
+ * - `<project>/.cleo/config.json`  (`project`,  precedence 20)
+ * - `<project>/.cleo/project-info.json`    (`metadata`, separate channel)
+ * - `<project>/.cleo/project-context.json` (`metadata`, separate channel)
+ *
+ * Merge semantics: higher `mergePrecedence` wins. The `metadata` scope is
+ * intentionally OUTSIDE the project ↔ global merge chain — those files are
+ * read-only consumer state and must NEVER be merged into resolved CleoConfig.
+ *
+ * @task T9876
+ * @saga T9855
+ * @adr 076
+ */
+import { type ZodTypeAny, z } from 'zod';
+/**
+ * Cascade-participating scopes for the project ↔ global merge chain.
+ *
+ * - `'global'`  — `~/.cleo/config.json`        (precedence 10)
+ * - `'project'` — `<project>/.cleo/config.json` (precedence 20, higher wins)
+ *
+ * Note: `'metadata'` is NOT part of this union — metadata-scoped files are
+ * read-only consumer state and live on a separate channel. See
+ * {@link ConfigManifestScope} for the full union including metadata.
+ *
+ * @task T9876
+ */
+export type ConfigScope = 'global' | 'project';
+/**
+ * Full scope union covering cascade scopes AND the read-only `metadata`
+ * channel used by `project-info.json` and `project-context.json`.
+ *
+ * Metadata-scoped entries are NEVER merged into the resolved CleoConfig —
+ * they are surfaced separately as consumer state and validated only for
+ * schema conformance / staleness.
+ *
+ * @task T9876
+ */
+export type ConfigManifestScope = ConfigScope | 'metadata';
+/**
+ * Drift-detection strategy applied to a manifest entry.
+ *
+ * - `'schema-validate'` — Re-parse the file's contents against {@link ConfigManifestEntry.schema}
+ *   on read. Any parse error is reported as drift.
+ * - `'staleness-gate'`  — Compare the file's `detectedAt` (or equivalent freshness key)
+ *   against a freshness threshold. Stale files are flagged but not rejected.
+ * - `'value-diff'`      — Diff the file's resolved values against the manifest's
+ *   `defaults` baseline and report changed keys. Useful for invariant tracking.
+ * - `'none'`            — No drift detection. Entry is informational-only.
+ *
+ * @task T9876
+ */
+export type DriftDetection = 'schema-validate' | 'staleness-gate' | 'value-diff' | 'none';
+/**
+ * A single registry entry describing one config-like file CLEO is aware of.
+ *
+ * `mergePrecedence` orders entries within the SAME scope channel. Across
+ * channels, the cascade-resolver consumes entries with `scope` in
+ * {@link ConfigScope} (global/project) and merges by ascending precedence
+ * (higher wins). Metadata entries are surfaced separately.
+ *
+ * @task T9876
+ */
+export interface ConfigManifestEntry {
+    /** Stable identifier for the entry (e.g. `'cleo-config-project'`). */
+    id: string;
+    /** Where the file lives in the precedence hierarchy. */
+    scope: ConfigManifestScope;
+    /** Absolute or `~`-rooted path to the file on disk. */
+    path: string;
+    /**
+     * Optional Zod schema used by the `'schema-validate'` drift detector to
+     * re-parse the file's contents. `null` disables schema validation even when
+     * `driftDetection === 'schema-validate'` (advisory-only mode).
+     */
+    schema?: ZodTypeAny | null;
+    /**
+     * Numeric merge precedence within the cascade. Higher wins.
+     *
+     * Canonical values:
+     * - `0`  — defaults / metadata (NOT part of the merge chain)
+     * - `10` — global
+     * - `20` — project
+     */
+    mergePrecedence: number;
+    /** Drift-detection strategy to apply to this entry. */
+    driftDetection: DriftDetection;
+    /** Optional default values used as the baseline for `'value-diff'` drift detection. */
+    defaults?: Record<string, unknown>;
+}
+/**
+ * Manifest entry for `<project>/.cleo/project-info.json`.
+ *
+ * Metadata channel (NOT part of the merge cascade). Schema-validated on
+ * read because the file is consumer state with a stable shape.
+ *
+ * @task T9876
+ */
+export declare const PROJECT_INFO_MANIFEST: ConfigManifestEntry;
+/**
+ * Manifest entry for `<project>/.cleo/project-context.json`.
+ *
+ * Metadata channel. Staleness-gated because the file is regenerated by
+ * project-detection scans and consumers care about freshness, not exact shape.
+ *
+ * @task T9876
+ */
+export declare const PROJECT_CONTEXT_MANIFEST: ConfigManifestEntry;
+/**
+ * Manifest entry for `<project>/.cleo/config.json` (project-scoped CleoConfig).
+ *
+ * Project scope; precedence 20 — wins over global. Schema-validated.
+ *
+ * @task T9876
+ */
+export declare const CLEO_CONFIG_MANIFEST: ConfigManifestEntry;
+/**
+ * Manifest entry for `~/.cleo/config.json` (global CleoConfig).
+ *
+ * Global scope; precedence 10 — loses to project. Schema-validated.
+ *
+ * @task T9876
+ */
+export declare const GLOBAL_CLEO_CONFIG_MANIFEST: ConfigManifestEntry;
+/**
+ * Frozen registry of all built-in manifest entries shipped with the contracts
+ * package. Order is informational only — consumers MUST sort by
+ * `mergePrecedence` when applying the cascade.
+ *
+ * @task T9876
+ */
+export declare const CONFIG_MANIFEST_ENTRIES: readonly ConfigManifestEntry[];
+/**
+ * Zod schema for {@link ConfigManifestEntry}.
+ *
+ * Treats `schema` as `unknown` because `ZodTypeAny` instances cannot be
+ * validated through Zod itself without infinite recursion — schema-shape
+ * checking is the responsibility of the consumer that constructs the entry.
+ *
+ * @task T9876
+ */
+export declare const configManifestEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    scope: z.ZodUnion<readonly [z.ZodLiteral<"global">, z.ZodLiteral<"project">, z.ZodLiteral<"metadata">]>;
+    path: z.ZodString;
+    schema: z.ZodOptional<z.ZodUnknown>;
+    mergePrecedence: z.ZodNumber;
+    driftDetection: z.ZodUnion<readonly [z.ZodLiteral<"schema-validate">, z.ZodLiteral<"staleness-gate">, z.ZodLiteral<"value-diff">, z.ZodLiteral<"none">]>;
+    defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/config/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/config/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMzC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,UAAU,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,YAAY,GAAG,MAAM,CAAC;AAM1F;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,KAAK,EAAE,mBAAmB,CAAC;IAC3B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B;;;;;;;OAOG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,cAAc,EAAE,cAAc,CAAC;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAMnC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,EAAE,mBAMtC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,mBAMlC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,mBAMzC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,mBAAmB,EAKhE,CAAC;AAMH;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;iBAapC,CAAC"}

package/dist/config/manifest.js

@@ -0,0 +1,123 @@
+/**
+ * ConfigManifest contract — declarative registry of every config-like file CLEO
+ * reads, writes, or merges, with its scope, schema, merge precedence, and the
+ * drift-detection strategy applied to it.
+ *
+ * Foundation for the CORE SSoT config registry (T9878) and the `resolveCleoConfig`
+ * cascade resolver. Built-in entries cover the four canonical CLEO files:
+ *
+ * - `~/.cleo/config.json`          (`global`,   precedence 10)
+ * - `<project>/.cleo/config.json`  (`project`,  precedence 20)
+ * - `<project>/.cleo/project-info.json`    (`metadata`, separate channel)
+ * - `<project>/.cleo/project-context.json` (`metadata`, separate channel)
+ *
+ * Merge semantics: higher `mergePrecedence` wins. The `metadata` scope is
+ * intentionally OUTSIDE the project ↔ global merge chain — those files are
+ * read-only consumer state and must NEVER be merged into resolved CleoConfig.
+ *
+ * @task T9876
+ * @saga T9855
+ * @adr 076
+ */
+import { z } from 'zod';
+// ───────────────────────────────────────────────────────────────────────────
+// Built-in manifest entries (4 canonical CLEO files)
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Manifest entry for `<project>/.cleo/project-info.json`.
+ *
+ * Metadata channel (NOT part of the merge cascade). Schema-validated on
+ * read because the file is consumer state with a stable shape.
+ *
+ * @task T9876
+ */
+export const PROJECT_INFO_MANIFEST = {
+    id: 'project-info',
+    scope: 'metadata',
+    path: '.cleo/project-info.json',
+    mergePrecedence: 0,
+    driftDetection: 'schema-validate',
+};
+/**
+ * Manifest entry for `<project>/.cleo/project-context.json`.
+ *
+ * Metadata channel. Staleness-gated because the file is regenerated by
+ * project-detection scans and consumers care about freshness, not exact shape.
+ *
+ * @task T9876
+ */
+export const PROJECT_CONTEXT_MANIFEST = {
+    id: 'project-context',
+    scope: 'metadata',
+    path: '.cleo/project-context.json',
+    mergePrecedence: 0,
+    driftDetection: 'staleness-gate',
+};
+/**
+ * Manifest entry for `<project>/.cleo/config.json` (project-scoped CleoConfig).
+ *
+ * Project scope; precedence 20 — wins over global. Schema-validated.
+ *
+ * @task T9876
+ */
+export const CLEO_CONFIG_MANIFEST = {
+    id: 'cleo-config-project',
+    scope: 'project',
+    path: '.cleo/config.json',
+    mergePrecedence: 20,
+    driftDetection: 'schema-validate',
+};
+/**
+ * Manifest entry for `~/.cleo/config.json` (global CleoConfig).
+ *
+ * Global scope; precedence 10 — loses to project. Schema-validated.
+ *
+ * @task T9876
+ */
+export const GLOBAL_CLEO_CONFIG_MANIFEST = {
+    id: 'cleo-config-global',
+    scope: 'global',
+    path: '~/.cleo/config.json',
+    mergePrecedence: 10,
+    driftDetection: 'schema-validate',
+};
+/**
+ * Frozen registry of all built-in manifest entries shipped with the contracts
+ * package. Order is informational only — consumers MUST sort by
+ * `mergePrecedence` when applying the cascade.
+ *
+ * @task T9876
+ */
+export const CONFIG_MANIFEST_ENTRIES = Object.freeze([
+    PROJECT_INFO_MANIFEST,
+    PROJECT_CONTEXT_MANIFEST,
+    GLOBAL_CLEO_CONFIG_MANIFEST,
+    CLEO_CONFIG_MANIFEST,
+]);
+// ───────────────────────────────────────────────────────────────────────────
+// Runtime validation schema
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Zod schema for {@link ConfigManifestEntry}.
+ *
+ * Treats `schema` as `unknown` because `ZodTypeAny` instances cannot be
+ * validated through Zod itself without infinite recursion — schema-shape
+ * checking is the responsibility of the consumer that constructs the entry.
+ *
+ * @task T9876
+ */
+export const configManifestEntrySchema = z.object({
+    id: z.string().min(1),
+    scope: z.union([z.literal('global'), z.literal('project'), z.literal('metadata')]),
+    path: z.string().min(1),
+    schema: z.unknown().optional(),
+    mergePrecedence: z.number().int().nonnegative(),
+    driftDetection: z.union([
+        z.literal('schema-validate'),
+        z.literal('staleness-gate'),
+        z.literal('value-diff'),
+        z.literal('none'),
+    ]),
+    defaults: z.record(z.string(), z.unknown()).optional(),
+});
+//# sourceMappingURL=manifest.js.map

package/dist/config/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/config/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAmB,CAAC,EAAE,MAAM,KAAK,CAAC;AAyFzC,8EAA8E;AAC9E,qDAAqD;AACrD,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB;IACxD,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,yBAAyB;IAC/B,eAAe,EAAE,CAAC;IAClB,cAAc,EAAE,iBAAiB;CAClC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAwB;IAC3D,EAAE,EAAE,iBAAiB;IACrB,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,4BAA4B;IAClC,eAAe,EAAE,CAAC;IAClB,cAAc,EAAE,gBAAgB;CACjC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAwB;IACvD,EAAE,EAAE,qBAAqB;IACzB,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,mBAAmB;IACzB,eAAe,EAAE,EAAE;IACnB,cAAc,EAAE,iBAAiB;CAClC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAwB;IAC9D,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,QAAQ;IACf,IAAI,EAAE,qBAAqB;IAC3B,eAAe,EAAE,EAAE;IACnB,cAAc,EAAE,iBAAiB;CAClC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAmC,MAAM,CAAC,MAAM,CAAC;IACnF,qBAAqB;IACrB,wBAAwB;IACxB,2BAA2B;IAC3B,oBAAoB;CACrB,CAAC,CAAC;AAEH,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAClF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC9B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC/C,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC;QACtB,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC;QAC5B,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC;QAC3B,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;QACvB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC"}

package/dist/docs/__tests__/provenance.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Unit + snapshot tests for the Docs Provenance Graph contract (T10166).
+ *
+ * Coverage:
+ *   - Round-trip Zod parse for each node variant + edge variant + envelope.
+ *   - Discriminator rejection for unknown `kind` / `relation` / lifecycle values.
+ *   - Type-guard narrowing for all five node variants.
+ *   - Snapshot test for a typical-sized graph (5 docs, 8 tasks, 4 decisions,
+ *     2 sessions) — locks the wire shape consumed by the renderer.
+ *
+ * @task T10166
+ */
+export {};
+//# sourceMappingURL=provenance.test.d.ts.map

package/dist/docs/__tests__/provenance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.test.d.ts","sourceRoot":"","sources":["../../../src/docs/__tests__/provenance.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}