@nekostack/schema 1.0.0

package/dist/src/migrations/verify-provenance.js

@@ -0,0 +1,158 @@
+/**
+ * `verifyMigrationProvenance(opts)` — per-migration two-hash
+ * provenance verifier (v0.8 Step 5).
+ *
+ * For every `MigrationEntry` in the migration registry, compares
+ * the migration's recorded `(fromIrHash, toIrHash, fromSourceHash,
+ * toSourceHash)` against the current schema registry's
+ * `findSchema(...).irHash` / `.sourceHash` for the same versions.
+ * Emits one `MigrationVerdict` per migration plus a per-status
+ * summary on the success branch.
+ *
+ * **Pure.** No `fs.*`, no `import()`, no `process.*`, no
+ * `console.*`. **Never invokes `migration.transform`** — verification
+ * is a `provenance-says-what-it-says` check, not a behavior check.
+ * Transform execution is deferred to v0.9+.
+ *
+ * Verdict mapping (Decision #9 — mirrors the v0.7 two-hash
+ * freshness matrix):
+ *
+ *   | irHash match | sourceHash match | verdict           |
+ *   |--------------|-----------------|-------------------|
+ *   | both         | both            | `bound`           |
+ *   | both         | at least one ≠  | `cosmetic_drift`  |
+ *   | at least one ≠ | (any)         | `drift`           |
+ *   | endpoint absent | n/a          | `missing_endpoint`|
+ *
+ * Result-envelope rules:
+ *
+ *   - Every verdict is recorded in `verdicts[]` regardless of status.
+ *   - `summary` carries per-status counts.
+ *   - `Result.success` when every verdict is `bound` or
+ *     `cosmetic_drift` (no `drift` and no `missing_endpoint`).
+ *     `cosmetic_drift` is warning-class and does NOT fail the run.
+ *   - `Result.failure` with one `Issue` per `drift` / `missing_endpoint`
+ *     verdict otherwise. The CLI dispatcher (Step 9 handler / Step 22
+ *     verb) maps to `LOGICAL_FAILURE`.
+ *
+ * Deterministic iteration: registry entries are visited in
+ * `(schemaId, fromVersion, toVersion)` lexicographic order so the
+ * `verdicts[]` array shape is stable regardless of how the input
+ * registry was built. Downstream tooling (CLI pretty/JSON output)
+ * relies on the order being predictable across runs.
+ */
+import { findSchema } from "../registry/build-registry.js";
+// =============================================================================
+// Public entry
+// =============================================================================
+export function verifyMigrationProvenance(opts) {
+    const verdicts = [];
+    const issues = [];
+    const summary = {
+        bound: 0,
+        cosmetic_drift: 0,
+        drift: 0,
+        missing_endpoint: 0,
+    };
+    for (const entry of iterateRegistry(opts.migrationRegistry)) {
+        const verdict = classifyMigration(entry, opts.schemaRegistry);
+        verdicts.push(verdict);
+        summary[verdict.status] += 1;
+        if (verdict.status === "drift" || verdict.status === "missing_endpoint") {
+            issues.push(verdictIssue(verdict));
+        }
+    }
+    if (issues.length > 0) {
+        return { success: false, issues };
+    }
+    const result = { verdicts, summary };
+    return { success: true, data: result };
+}
+// =============================================================================
+// Deterministic iteration
+// =============================================================================
+/**
+ * Yield every `MigrationEntry` in the registry in
+ * `(schemaId, fromVersion, toVersion)` lexicographic order. The
+ * underlying `Map`s preserve insertion order, but we sort
+ * explicitly so the verifier's output is stable across different
+ * upstream-build sequences.
+ */
+function* iterateRegistry(registry) {
+    const schemaIds = [...registry.keys()].sort();
+    for (const schemaId of schemaIds) {
+        const byFrom = registry.get(schemaId);
+        const fromVersions = [...byFrom.keys()].sort();
+        for (const fromVersion of fromVersions) {
+            const byTo = byFrom.get(fromVersion);
+            const toVersions = [...byTo.keys()].sort();
+            for (const toVersion of toVersions) {
+                yield byTo.get(toVersion);
+            }
+        }
+    }
+}
+// =============================================================================
+// Classification
+// =============================================================================
+function classifyMigration(entry, schemaRegistry) {
+    const base = {
+        sourcePath: entry.sourcePath,
+        schemaId: entry.schemaId,
+        fromVersion: entry.fromVersion,
+        toVersion: entry.toVersion,
+    };
+    const fromSchema = findSchema(schemaRegistry, entry.schemaId, entry.fromVersion);
+    const toSchema = findSchema(schemaRegistry, entry.schemaId, entry.toVersion);
+    if (fromSchema === undefined || toSchema === undefined) {
+        return { status: "missing_endpoint", ...base };
+    }
+    const fromIrMatch = entry.fromIrHash === fromSchema.irHash;
+    const toIrMatch = entry.toIrHash === toSchema.irHash;
+    if (!fromIrMatch || !toIrMatch) {
+        return { status: "drift", ...base };
+    }
+    const fromSourceMatch = entry.fromSourceHash === fromSchema.sourceHash;
+    const toSourceMatch = entry.toSourceHash === toSchema.sourceHash;
+    if (!fromSourceMatch || !toSourceMatch) {
+        return { status: "cosmetic_drift", ...base };
+    }
+    return { status: "bound", ...base };
+}
+// =============================================================================
+// Issue helpers
+// =============================================================================
+function verdictIssue(verdict) {
+    if (verdict.status === "missing_endpoint") {
+        return {
+            code: "migration_missing_endpoint",
+            path: [verdict.sourcePath],
+            message: `Migration \`${verdict.schemaId}\` ` +
+                `${verdict.fromVersion} → ${verdict.toVersion} references a schema ` +
+                `version that is not in the registry.`,
+            severity: "error",
+            metadata: {
+                schemaId: verdict.schemaId,
+                fromVersion: verdict.fromVersion,
+                toVersion: verdict.toVersion,
+                sourcePath: verdict.sourcePath,
+            },
+        };
+    }
+    // drift
+    return {
+        code: "migration_drift",
+        path: [verdict.sourcePath],
+        message: `Migration \`${verdict.schemaId}\` ` +
+            `${verdict.fromVersion} → ${verdict.toVersion} was authored against a ` +
+            `schema state that has since changed (irHash mismatch).`,
+        severity: "error",
+        metadata: {
+            schemaId: verdict.schemaId,
+            fromVersion: verdict.fromVersion,
+            toVersion: verdict.toVersion,
+            sourcePath: verdict.sourcePath,
+        },
+    };
+}
+//# sourceMappingURL=verify-provenance.js.map

package/dist/src/migrations/verify-provenance.js.map

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

package/dist/src/registry/build-registry.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `buildRegistry(entries)` — pure registry construction (Master plan
+ * Step 6).
+ *
+ * Walks the CLI-supplied `RegistrySourceEntry[]` (one per loaded
+ * `*.schema.{ts,js}` file) and builds the two-level lookup map
+ * `Registry = ReadonlyMap<schemaId, ReadonlyMap<versionKey,
+ * RegistryEntry>>`. Returns `Result<Registry>` so duplicate detection
+ * surfaces as `Issue[]` rather than `throw` (Master plan Decision #4).
+ *
+ * **Pure.** No `fs.*`, no `import()`, no `path.*`. The CLI is
+ * responsible for reading the source text and dynamic-importing the
+ * schema files; this function takes the loaded data and indexes it.
+ * Master plan Decision #1 boundary.
+ *
+ * Rules:
+ * - Anonymous schemas (no `.id()`) are silently ignored. They remain
+ *   legal per v0.1; they just don't participate in registry lookup.
+ *   The CLI emits a stderr warning per anonymous schema it finds
+ *   (Master plan Decision #5), but that's an I/O concern owned by
+ *   the CLI, not by this function.
+ * - Unversioned schemas (`.id()` but no `.version()`) are indexed
+ *   under the empty-string inner key. The on-entry
+ *   `schemaVersion` field stays `undefined` per the Step 1 type.
+ * - Duplicate `(schemaId, versionKey)` pairs across the entry list
+ *   are collected into one `Issue` per dupe with code
+ *   `"duplicate_schema_id"`. The function does not throw; the CLI
+ *   formats the issue list and exits non-zero.
+ *
+ * `sourceHash` is computed once per `RegistrySourceEntry` via
+ * `sourceHashFromText(entry.sourceText)`. All `RegistryEntry`s
+ * produced from the same source file therefore share the same
+ * `sourceHash` value — correct because they share the same source
+ * text.
+ *
+ * `findSchema(registry, schemaId, version?)` is the lookup helper.
+ * When `version` is omitted, returns the highest-semver entry for
+ * the given id. If only unversioned entries exist for that id, the
+ * unversioned entry is returned. See the function comment for the
+ * full lookup rules.
+ */
+import type { Result } from "../errors/issue.js";
+import type { Registry, RegistryEntry, RegistrySourceEntry } from "./types.js";
+export declare function buildRegistry(entries: readonly RegistrySourceEntry[]): Result<Registry>;
+/**
+ * Look up a schema by `(schemaId, schemaVersion)`.
+ *
+ * Rules:
+ * - When `version` is provided: exact match against the inner key.
+ *   - `findSchema(reg, "X", "1.0.0")` returns the entry whose
+ *     `schemaVersion` is `"1.0.0"`, or `undefined`.
+ *   - `findSchema(reg, "X", "")` returns the unversioned entry if
+ *     one exists (the empty-string key); this is the intentional
+ *     way to address an unversioned schema by exact lookup.
+ * - When `version` is omitted: returns the highest-semver entry
+ *   for `schemaId`. If only unversioned entries exist, returns the
+ *   unversioned entry. If both versioned and unversioned entries
+ *   exist for the same id, **versioned wins** — `findSchema` returns
+ *   the highest semver, never the unversioned entry, when at least
+ *   one versioned entry exists.
+ * - Returns `undefined` if `schemaId` is not in the registry, or
+ *   if the explicit `version` does not match any inner key.
+ */
+export declare function findSchema(registry: Registry, schemaId: string, version?: string): RegistryEntry | undefined;
+//# sourceMappingURL=build-registry.d.ts.map

package/dist/src/registry/build-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-registry.d.ts","sourceRoot":"","sources":["../../../src/registry/build-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,KAAK,EAAS,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAMpB,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,mBAAmB,EAAE,GACtC,MAAM,CAAC,QAAQ,CAAC,CAmDlB;AA4BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,aAAa,GAAG,SAAS,CAuB3B"}

package/dist/src/registry/build-registry.js

@@ -0,0 +1,172 @@
+/**
+ * `buildRegistry(entries)` — pure registry construction (Master plan
+ * Step 6).
+ *
+ * Walks the CLI-supplied `RegistrySourceEntry[]` (one per loaded
+ * `*.schema.{ts,js}` file) and builds the two-level lookup map
+ * `Registry = ReadonlyMap<schemaId, ReadonlyMap<versionKey,
+ * RegistryEntry>>`. Returns `Result<Registry>` so duplicate detection
+ * surfaces as `Issue[]` rather than `throw` (Master plan Decision #4).
+ *
+ * **Pure.** No `fs.*`, no `import()`, no `path.*`. The CLI is
+ * responsible for reading the source text and dynamic-importing the
+ * schema files; this function takes the loaded data and indexes it.
+ * Master plan Decision #1 boundary.
+ *
+ * Rules:
+ * - Anonymous schemas (no `.id()`) are silently ignored. They remain
+ *   legal per v0.1; they just don't participate in registry lookup.
+ *   The CLI emits a stderr warning per anonymous schema it finds
+ *   (Master plan Decision #5), but that's an I/O concern owned by
+ *   the CLI, not by this function.
+ * - Unversioned schemas (`.id()` but no `.version()`) are indexed
+ *   under the empty-string inner key. The on-entry
+ *   `schemaVersion` field stays `undefined` per the Step 1 type.
+ * - Duplicate `(schemaId, versionKey)` pairs across the entry list
+ *   are collected into one `Issue` per dupe with code
+ *   `"duplicate_schema_id"`. The function does not throw; the CLI
+ *   formats the issue list and exits non-zero.
+ *
+ * `sourceHash` is computed once per `RegistrySourceEntry` via
+ * `sourceHashFromText(entry.sourceText)`. All `RegistryEntry`s
+ * produced from the same source file therefore share the same
+ * `sourceHash` value — correct because they share the same source
+ * text.
+ *
+ * `findSchema(registry, schemaId, version?)` is the lookup helper.
+ * When `version` is omitted, returns the highest-semver entry for
+ * the given id. If only unversioned entries exist for that id, the
+ * unversioned entry is returned. See the function comment for the
+ * full lookup rules.
+ */
+import { irHash } from "../ir/hash.js";
+import { sourceHashFromText } from "./source-hash.js";
+// =============================================================================
+// buildRegistry
+// =============================================================================
+export function buildRegistry(entries) {
+    const out = new Map();
+    const duplicates = [];
+    for (const entry of entries) {
+        const entrySourceHash = sourceHashFromText(entry.sourceText);
+        for (const schema of entry.schemas) {
+            const schemaId = schema.node.metadata?.id;
+            if (schemaId === undefined) {
+                // Anonymous schemas don't participate in registry lookup.
+                // The CLI warns; this layer is silent.
+                continue;
+            }
+            const schemaVersion = schema.node.metadata?.version;
+            const versionKey = schemaVersion ?? "";
+            const built = {
+                schemaId,
+                schemaVersion,
+                irHash: `sha256:${irHash(schema.node)}`,
+                sourceHash: entrySourceHash,
+                sourcePath: entry.sourcePath,
+                schema,
+            };
+            let inner = out.get(schemaId);
+            if (inner === undefined) {
+                inner = new Map();
+                out.set(schemaId, inner);
+            }
+            const existing = inner.get(versionKey);
+            if (existing !== undefined) {
+                duplicates.push(duplicateIssue(schemaId, schemaVersion, [
+                    existing.sourcePath,
+                    entry.sourcePath,
+                ]));
+                // Keep the first-seen entry. Re-indexing would let the
+                // duplicate replace the original silently, which is the
+                // exact failure mode this Result is meant to surface.
+                continue;
+            }
+            inner.set(versionKey, built);
+        }
+    }
+    if (duplicates.length > 0) {
+        return { success: false, issues: duplicates };
+    }
+    return { success: true, data: out };
+}
+function duplicateIssue(schemaId, schemaVersion, sourcePaths) {
+    const versionLabel = schemaVersion === undefined ? "(unversioned)" : `v${schemaVersion}`;
+    return {
+        code: "duplicate_schema_id",
+        path: [],
+        message: `Duplicate schema "${schemaId}" ${versionLabel} found in: ${sourcePaths.join(", ")}`,
+        severity: "error",
+        metadata: {
+            schemaId,
+            schemaVersion: schemaVersion ?? null,
+            sourcePaths: [...sourcePaths],
+        },
+    };
+}
+// =============================================================================
+// findSchema
+// =============================================================================
+/**
+ * Look up a schema by `(schemaId, schemaVersion)`.
+ *
+ * Rules:
+ * - When `version` is provided: exact match against the inner key.
+ *   - `findSchema(reg, "X", "1.0.0")` returns the entry whose
+ *     `schemaVersion` is `"1.0.0"`, or `undefined`.
+ *   - `findSchema(reg, "X", "")` returns the unversioned entry if
+ *     one exists (the empty-string key); this is the intentional
+ *     way to address an unversioned schema by exact lookup.
+ * - When `version` is omitted: returns the highest-semver entry
+ *   for `schemaId`. If only unversioned entries exist, returns the
+ *   unversioned entry. If both versioned and unversioned entries
+ *   exist for the same id, **versioned wins** — `findSchema` returns
+ *   the highest semver, never the unversioned entry, when at least
+ *   one versioned entry exists.
+ * - Returns `undefined` if `schemaId` is not in the registry, or
+ *   if the explicit `version` does not match any inner key.
+ */
+export function findSchema(registry, schemaId, version) {
+    const inner = registry.get(schemaId);
+    if (inner === undefined)
+        return undefined;
+    if (version !== undefined) {
+        return inner.get(version);
+    }
+    // No version supplied — pick the highest-semver entry.
+    const versionedKeys = [];
+    let unversioned;
+    for (const [key, entry] of inner) {
+        if (key === "") {
+            unversioned = entry;
+        }
+        else {
+            versionedKeys.push(key);
+        }
+    }
+    if (versionedKeys.length > 0) {
+        versionedKeys.sort(compareSemver);
+        return inner.get(versionedKeys[versionedKeys.length - 1]);
+    }
+    return unversioned;
+}
+/**
+ * Compare two semver-shaped strings numerically by major.minor.patch.
+ * Falls back to `localeCompare` for non-matching inputs so we never
+ * throw on a non-standard version string — that would defeat the
+ * fail-loud-not-throw discipline. Matches the shape used by
+ * `scripts/generate-status.mjs`.
+ */
+function compareSemver(a, b) {
+    const ax = a.match(/(\d+)\.(\d+)\.(\d+)/);
+    const bx = b.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!ax || !bx)
+        return a.localeCompare(b);
+    for (let i = 1; i <= 3; i++) {
+        const d = Number(ax[i]) - Number(bx[i]);
+        if (d !== 0)
+            return d;
+    }
+    return a.localeCompare(b);
+}
+//# sourceMappingURL=build-registry.js.map

package/dist/src/registry/build-registry.js.map

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

package/dist/src/registry/diff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Schema diff classifier (Master plan Step 7).
+ *
+ * `diffNodes(before, after)` walks two `SchemaNode` trees and emits a
+ * list of `DiffChange`s with severity per the locked Master plan
+ * Decision #12 table. The **input-acceptance compatibility** lens is
+ * primary: severity reflects whether the new schema accepts every
+ * input the old one did (additive) or rejects some (breaking).
+ * Output-side caveats are reflected in `kind` / `message` where they
+ * matter (`default_removed`, etc.) but do not split the severity.
+ *
+ * **Pure.** No registry lookup, no `Issue[]` surface, no filesystem.
+ * The function returns `readonly DiffChange[]`; an empty array means
+ * the schemas are equivalent. `worstSeverity` aggregation lives in
+ * `diffHandler` (Step 9).
+ *
+ * Unsupported IR kinds (`date`, `union`, `recursiveRef`, `transform`)
+ * throw `UnsupportedNodeKindError({ generator: "diff", kind })` per
+ * Master plan Decision #14 — same fail-loud discipline as the v0.3 /
+ * v0.6 generators.
+ */
+import type { SchemaNode } from "../ir/nodes.js";
+import type { DiffChange } from "./types.js";
+export declare function diffNodes(before: SchemaNode, after: SchemaNode): readonly DiffChange[];
+//# sourceMappingURL=diff.d.ts.map

package/dist/src/registry/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/registry/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAUV,UAAU,EACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAC;AAa3D,wBAAgB,SAAS,CACvB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,GAChB,SAAS,UAAU,EAAE,CAIvB"}