@skmtc/core 0.0.983 → 0.16.1

package/esm/anchors/buildSidecar.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Assemble a {@link Sidecar} from resolved spans +
+ * attributions + landmark/path pairs.
+ *
+ * Pure function: no I/O, no parser, no global state. The AST landmark
+ * resolution step (plan §4.2) is *not* done here — the caller passes
+ * pre-resolved `(landmark, path)` pairs alongside each span. This
+ * separation is deliberate:
+ *
+ * - The sidecar shape + interning logic can be tested without a
+ *   parser (`FakeParser` is enough).
+ * - When tsc / oxc adapters land (plan §8), they're swap-ins behind
+ *   the `ParserAdapter` interface — no churn here.
+ *
+ * `writeSidecar` (Phase D) is the thin I/O wrapper. It stays separate
+ * so the pure builder can be exercised independently with a temp dir.
+ */
+import type { Span, Attribution } from './types.js';
+import { type Sidecar, type RegistryEntry } from './sidecar.js';
+/**
+ * One (span, attribution, landmark) triple — the input unit for
+ * `buildSidecar`. `landmark` is the top-level export name the span
+ * lives under (empty string when the span sits outside any landmark,
+ * which the builder treats as a skip). `path` is the AST child-index
+ * trail inside the landmark; empty path means "the landmark itself".
+ */
+export type ResolvedAnchor = {
+    span: Span;
+    attribution: Attribution;
+    landmark: string;
+    path: number[];
+    /**
+     * Generator metadata for the producer that owns this span. The
+     * `attribute()` step gives us only the generator id; the version +
+     * registry come from the CLI's view of `deno.json`/lockfile (Phase
+     * D plumbs this). For now callers pass it in; the builder takes
+     * whatever they hand over and pools it.
+     */
+    generatorVersion: string;
+    registry: RegistryEntry;
+};
+export type BuildSidecarArgs = {
+    filePath: string;
+    schemaSrc: string;
+    parser: string;
+    anchors: ResolvedAnchor[];
+};
+/**
+ * Assemble a Sidecar v2 from resolved anchors. Anchors with an empty
+ * `landmark` string are skipped — they sit outside any top-level
+ * export and have no useful re-resolution path (plan #25).
+ */
+export declare const buildSidecar: ({ filePath, schemaSrc, parser, anchors }: BuildSidecarArgs) => Sidecar;
+//# sourceMappingURL=buildSidecar.d.ts.map

package/esm/anchors/buildSidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildSidecar.d.ts","sourceRoot":"","sources":["../../src/anchors/buildSidecar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAA;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,IAAI,CAAA;IACV,WAAW,EAAE,WAAW,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,aAAa,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,cAAc,EAAE,CAAA;CAC1B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,0CAK1B,gBAAgB,KAAG,OAgFrB,CAAA"}

package/esm/anchors/buildSidecar.js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Assemble a {@link Sidecar} from resolved spans +
+ * attributions + landmark/path pairs.
+ *
+ * Pure function: no I/O, no parser, no global state. The AST landmark
+ * resolution step (plan §4.2) is *not* done here — the caller passes
+ * pre-resolved `(landmark, path)` pairs alongside each span. This
+ * separation is deliberate:
+ *
+ * - The sidecar shape + interning logic can be tested without a
+ *   parser (`FakeParser` is enough).
+ * - When tsc / oxc adapters land (plan §8), they're swap-ins behind
+ *   the `ParserAdapter` interface — no churn here.
+ *
+ * `writeSidecar` (Phase D) is the thin I/O wrapper. It stays separate
+ * so the pure builder can be exercised independently with a temp dir.
+ */
+import { emptySidecar } from './sidecar.js';
+/**
+ * Assemble a Sidecar v2 from resolved anchors. Anchors with an empty
+ * `landmark` string are skipped — they sit outside any top-level
+ * export and have no useful re-resolution path (plan #25).
+ */
+export const buildSidecar = ({ filePath, schemaSrc, parser, anchors }) => {
+    const sidecar = emptySidecar(filePath, schemaSrc, parser);
+    // String-pool interning. Repeated values get the same index.
+    const stringPool = (pool) => {
+        const cache = new Map();
+        return (value) => {
+            const hit = cache.get(value);
+            if (hit !== undefined)
+                return hit;
+            const idx = pool.length;
+            pool.push(value);
+            cache.set(value, idx);
+            return idx;
+        };
+    };
+    // Object pools key on a canonical string form so we don't double-
+    // intern entries that happen to be structurally equal but
+    // referentially distinct.
+    const internRegistry = (() => {
+        const cache = new Map();
+        return (entry) => {
+            const key = `${entry.kind}|${entry.host}`;
+            const hit = cache.get(key);
+            if (hit !== undefined)
+                return hit;
+            const idx = sidecar.R.length;
+            sidecar.R.push(entry);
+            cache.set(key, idx);
+            return idx;
+        };
+    })();
+    const internGenerator = (() => {
+        const cache = new Map();
+        return (entry) => {
+            const key = `${entry.name}|${entry.version}|${entry.r}`;
+            const hit = cache.get(key);
+            if (hit !== undefined)
+                return hit;
+            const idx = sidecar.G.length;
+            sidecar.G.push(entry);
+            cache.set(key, idx);
+            return idx;
+        };
+    })();
+    const internS = stringPool(sidecar.S);
+    const internV = stringPool(sidecar.V);
+    const internL = stringPool(sidecar.L);
+    const internP = stringPool(sidecar.P);
+    // Producer-name pool (`N`) + a parallel `An` array (one entry per
+    // emitted `A` row). Kept local then assigned, so the additive fields
+    // don't need non-null coercion on the optional sidecar shape.
+    const N = [];
+    const An = [];
+    const internN = stringPool(N);
+    for (const anchor of anchors) {
+        if (anchor.landmark === '') {
+            // Span outside any landmark. Skip — re-anchoring after
+            // reformatting wouldn't have anything stable to descend from.
+            continue;
+        }
+        const ri = internRegistry(anchor.registry);
+        const gi = internGenerator({
+            name: anchor.attribution.generatorId,
+            version: anchor.generatorVersion,
+            r: ri
+        });
+        // `schemaPointer` is `''` for spans with no schema location
+        // (generator-only producers); consumers treat the empty pool entry
+        // as "no schema pointer".
+        const si = internS(anchor.attribution.schemaPointer);
+        const vi = internV(anchor.attribution.variant);
+        const Li = internL(anchor.landmark);
+        const Pi = internP(anchor.path.join('.'));
+        sidecar.A.push([Li, Pi, gi, si, vi, anchor.span.from, anchor.span.to]);
+        // Parallel to the A row just pushed.
+        An.push(internN(anchor.attribution.producerName));
+    }
+    sidecar.N = N;
+    sidecar.An = An;
+    return sidecar;
+};

package/esm/anchors/generationMap.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Generation map — per-Definition summary used for
+ * reverse queries: "which files came from refName User?", "which
+ * files did gen-zod produce?". Per plan §4.3.
+ *
+ * Lives at `.skmtc/<project>/.maps/_map.ndjson`, **wholly rewritten**
+ * per generation (no accumulation across runs; stale entries would
+ * mislead the viewer). The CLI handles disk I/O — this module emits
+ * the entries + an NDJSON helper.
+ *
+ * One entry per Definition (landmark), not per anchor. The landmark
+ * appears in the generation map; the per-Snippet anchors stay inside
+ * the sidecar itself.
+ *
+ * "Generation map" by analogy with source maps: each row pairs a
+ * generated artifact with the schema location + generator + variant
+ * it came from. Same pattern as a sourcemap, at Definition rather
+ * than byte granularity.
+ */
+import * as v from 'valibot';
+import type { Sidecar } from './sidecar.js';
+/**
+ * Single row in the generation map. Mirrors the documented shape in
+ * `plan.md` §4.3:
+ *
+ *  - `f` — file path (relative to basePath)
+ *  - `name` — Definition / landmark name
+ *  - `g` — generator id (e.g. `@skmtc/gen-typescript`)
+ *  - `s` — schema pointer or empty string
+ *  - `v` — variant name (default `'main'`)
+ */
+export declare const generationMapEntry: v.ObjectSchema<{
+    readonly f: v.StringSchema<undefined>;
+    readonly name: v.StringSchema<undefined>;
+    readonly g: v.StringSchema<undefined>;
+    readonly s: v.StringSchema<undefined>;
+    readonly v: v.StringSchema<undefined>;
+}, undefined>;
+export type GenerationMapEntry = v.InferOutput<typeof generationMapEntry>;
+/**
+ * Extract one generation-map entry per unique landmark in `sidecar`.
+ *
+ * For each landmark, picks the **outermost** anchor — the one whose
+ * AST path is empty (meaning the span is the landmark node itself).
+ * If no path-empty anchor exists for a landmark (rare; happens when
+ * the Definition's full text was reshaped between render and
+ * post-pass), falls back to the first anchor for that landmark in
+ * document order. This keeps the map populated rather than silently
+ * dropping a Definition that the user can see in the file.
+ */
+export declare const entriesForSidecar: (sidecar: Sidecar) => GenerationMapEntry[];
+/**
+ * Convert generation-map entries to NDJSON (newline-delimited JSON).
+ * One row per line; trailing newline so concatenation between
+ * generations is boundary-safe.
+ *
+ * Pure: takes entries, returns a string. No I/O.
+ */
+export declare const toNdjson: (entries: readonly GenerationMapEntry[]) => string;
+/**
+ * Parse a generation-map NDJSON file (typically read off disk by the
+ * viewer or by a `doctor` check). Invalid rows fail the valibot parse
+ * — the map is wholly rewritten per generation so a row being
+ * unparseable means the file is corrupt, not just stale.
+ */
+export declare const parseNdjson: (text: string) => GenerationMapEntry[];
+//# sourceMappingURL=generationMap.d.ts.map

package/esm/anchors/generationMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generationMap.d.ts","sourceRoot":"","sources":["../../src/anchors/generationMap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;;;;;;aAM7B,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,OAAO,KAAG,kBAAkB,EAgCtE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,SAAS,kBAAkB,EAAE,KAAG,MACiB,CAAA;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,kBAAkB,EAI5D,CAAA"}

package/esm/anchors/generationMap.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Generation map — per-Definition summary used for
+ * reverse queries: "which files came from refName User?", "which
+ * files did gen-zod produce?". Per plan §4.3.
+ *
+ * Lives at `.skmtc/<project>/.maps/_map.ndjson`, **wholly rewritten**
+ * per generation (no accumulation across runs; stale entries would
+ * mislead the viewer). The CLI handles disk I/O — this module emits
+ * the entries + an NDJSON helper.
+ *
+ * One entry per Definition (landmark), not per anchor. The landmark
+ * appears in the generation map; the per-Snippet anchors stay inside
+ * the sidecar itself.
+ *
+ * "Generation map" by analogy with source maps: each row pairs a
+ * generated artifact with the schema location + generator + variant
+ * it came from. Same pattern as a sourcemap, at Definition rather
+ * than byte granularity.
+ */
+import * as v from 'valibot';
+/**
+ * Single row in the generation map. Mirrors the documented shape in
+ * `plan.md` §4.3:
+ *
+ *  - `f` — file path (relative to basePath)
+ *  - `name` — Definition / landmark name
+ *  - `g` — generator id (e.g. `@skmtc/gen-typescript`)
+ *  - `s` — schema pointer or empty string
+ *  - `v` — variant name (default `'main'`)
+ */
+export const generationMapEntry = v.object({
+    f: v.string(),
+    name: v.string(),
+    g: v.string(),
+    s: v.string(),
+    v: v.string()
+});
+/**
+ * Extract one generation-map entry per unique landmark in `sidecar`.
+ *
+ * For each landmark, picks the **outermost** anchor — the one whose
+ * AST path is empty (meaning the span is the landmark node itself).
+ * If no path-empty anchor exists for a landmark (rare; happens when
+ * the Definition's full text was reshaped between render and
+ * post-pass), falls back to the first anchor for that landmark in
+ * document order. This keeps the map populated rather than silently
+ * dropping a Definition that the user can see in the file.
+ */
+export const entriesForSidecar = (sidecar) => {
+    const seen = new Set();
+    const out = [];
+    for (const row of sidecar.A) {
+        const [Li, Pi, gi, si, vi] = row;
+        if (seen.has(Li))
+            continue;
+        // Prefer the path-empty row for this landmark if we find one in
+        // the remaining sequence; otherwise the first row for this Li
+        // already in front of us wins on the next iteration.
+        const pathStr = sidecar.P[Pi];
+        if (pathStr !== '') {
+            // Defer — keep scanning in case a path-empty row for the same
+            // landmark exists later.
+            const hasOuter = sidecar.A.some(([Lj, Pj]) => Lj === Li && sidecar.P[Pj] === '');
+            if (hasOuter)
+                continue;
+        }
+        seen.add(Li);
+        out.push({
+            f: sidecar.f,
+            name: sidecar.L[Li],
+            g: sidecar.G[gi]?.name ?? '',
+            s: sidecar.S[si] ?? '',
+            v: sidecar.V[vi] ?? 'main'
+        });
+    }
+    return out;
+};
+/**
+ * Convert generation-map entries to NDJSON (newline-delimited JSON).
+ * One row per line; trailing newline so concatenation between
+ * generations is boundary-safe.
+ *
+ * Pure: takes entries, returns a string. No I/O.
+ */
+export const toNdjson = (entries) => entries.length === 0 ? '' : entries.map(e => JSON.stringify(e)).join('\n') + '\n';
+/**
+ * Parse a generation-map NDJSON file (typically read off disk by the
+ * viewer or by a `doctor` check). Invalid rows fail the valibot parse
+ * — the map is wholly rewritten per generation so a row being
+ * unparseable means the file is corrupt, not just stale.
+ */
+export const parseNdjson = (text) => {
+    if (text.length === 0)
+        return [];
+    const lines = text.split('\n').filter(line => line.length > 0);
+    return lines.map(line => v.parse(generationMapEntry, JSON.parse(line)));
+};

package/esm/anchors/postPass.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Tie the Phase B + C pieces together: take a rendered
+ * file's text + the spans the render-phase {@link CaptureSink} resolved,
+ * AST-resolve each span's landmark + path, and build the sidecar.
+ *
+ * Pure function over its inputs — no I/O, no global state, no `toString`,
+ * no pipeline hooks. The caller is `RenderContext` (folded in after the
+ * single capture render), running this once per File when the run supplies
+ * `attribution.postPass`. The CLI handles disk writes via a separate
+ * `writeSidecar` wrapper.
+ */
+import type { ParserAdapter } from './ParserAdapter.js';
+import type { RegistryEntry } from './sidecar.js';
+import type { Sidecar } from './sidecar.js';
+import type { Span } from './types.js';
+/**
+ * Lookup contract for per-generator metadata. Phase D's CLI builds
+ * this once from the project's lockfile + `deno.json` import map and
+ * passes it in. Generators not in the map fall back to `version: ''`
+ * + `registry: { host: 'jsr.io', kind: 'jsr' }` — the sidecar still
+ * builds, just with degraded provenance.
+ */
+export type GeneratorMetaLookup = (generatorId: string) => {
+    version: string;
+    registry: RegistryEntry;
+};
+export type PostPassArgs = {
+    /**
+     * The rendered file's path (the `File`'s own path, not the resolved
+     * artifact path). Used as the parser's source name and stamped on the
+     * sidecar.
+     */
+    filePath: string;
+    /** The rendered file text (the single capture render's output). */
+    source: string;
+    /**
+     * Byte spans for every contributing Definition / Snippet, resolved by
+     * the render-phase {@link CaptureSink} from the occurrence tree. In
+     * document order (Definitions first, then inner Snippets depth-first).
+     */
+    spans: Span[];
+    /**
+     * The schema source name (e.g. `'openapi.json'`). Carried on the
+     * sidecar's `src` field so re-anchor consumers know which schema
+     * the producer ran against.
+     */
+    schemaSrc: string;
+    /**
+     * Parser adapter to resolve landmarks + paths. Optional — when
+     * omitted, the sidecar still emits byte ranges + attribution +
+     * generator/schema-pointer/variant pools, but the `L` (landmark)
+     * and `P` (AST path) pools stay empty and every `A` row's
+     * landmark/path indices point at the empty sentinels. The SPA
+     * handles this gracefully (skips re-anchor on formatter drift).
+     *
+     * Worker-side post-pass uses this mode because native parsers
+     * (oxc-parser's napi bindings, tsc's `source-map-support` chain)
+     * don't bundle cleanly into a Web Worker. Host-side post-pass
+     * with a real parser is a future addition.
+     */
+    parser?: ParserAdapter;
+    /**
+     * Per-generator metadata lookup. Defaults to a stub that fills
+     * generator entries with empty version + `jsr.io` registry. The
+     * Phase D CLI wires in a real lookup.
+     */
+    generatorMeta?: GeneratorMetaLookup;
+};
+/**
+ * Run the post-render attribution pass for one file and return the
+ * Sidecar. Workflow:
+ *
+ *  1. `spans` arrive pre-resolved from the render-phase `CaptureSink`
+ *     (§3.3): byte ranges for each producer, in document order.
+ *  2. `attribute(span.producer)` — Phase B (§3.2): derives
+ *     `{ generatorId, schemaPointer, variant, definitionName, producerName }`.
+ *  3. Parser ascends each span to its enclosing landmark; the
+ *     `forEachChild`-indexed path is what makes the sidecar
+ *     re-anchorable after a formatter pass.
+ *  4. `buildSidecar(...)` — Phase C (§4.1): pool + intern, emit the
+ *     Sidecar v2 object.
+ *
+ * Returns the Sidecar; caller decides what to do with it (write to
+ * disk, attach to manifest, send over the wire).
+ */
+export declare const postPass: ({ filePath, source, spans, schemaSrc, parser, generatorMeta }: PostPassArgs) => Sidecar;
+//# sourceMappingURL=postPass.d.ts.map

package/esm/anchors/postPass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postPass.d.ts","sourceRoot":"","sources":["../../src/anchors/postPass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,KAAK,EAAe,IAAI,EAAE,MAAM,YAAY,CAAA;AAInD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK;IACzD,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,aAAa,CAAA;CACxB,CAAA;AAOD,MAAM,MAAM,YAAY,GAAG;IACzB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,KAAK,EAAE,IAAI,EAAE,CAAA;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAA;CACpC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ,GAAI,+DAOtB,YAAY,KAAG,OA6CjB,CAAA"}

package/esm/anchors/postPass.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Tie the Phase B + C pieces together: take a rendered
+ * file's text + the spans the render-phase {@link CaptureSink} resolved,
+ * AST-resolve each span's landmark + path, and build the sidecar.
+ *
+ * Pure function over its inputs — no I/O, no global state, no `toString`,
+ * no pipeline hooks. The caller is `RenderContext` (folded in after the
+ * single capture render), running this once per File when the run supplies
+ * `attribution.postPass`. The CLI handles disk writes via a separate
+ * `writeSidecar` wrapper.
+ */
+import { attribute } from './attribute.js';
+import { buildSidecar } from './buildSidecar.js';
+const defaultLookup = () => ({
+    version: '',
+    registry: { host: 'jsr.io', kind: 'jsr' }
+});
+/**
+ * Run the post-render attribution pass for one file and return the
+ * Sidecar. Workflow:
+ *
+ *  1. `spans` arrive pre-resolved from the render-phase `CaptureSink`
+ *     (§3.3): byte ranges for each producer, in document order.
+ *  2. `attribute(span.producer)` — Phase B (§3.2): derives
+ *     `{ generatorId, schemaPointer, variant, definitionName, producerName }`.
+ *  3. Parser ascends each span to its enclosing landmark; the
+ *     `forEachChild`-indexed path is what makes the sidecar
+ *     re-anchorable after a formatter pass.
+ *  4. `buildSidecar(...)` — Phase C (§4.1): pool + intern, emit the
+ *     Sidecar v2 object.
+ *
+ * Returns the Sidecar; caller decides what to do with it (write to
+ * disk, attach to manifest, send over the wire).
+ */
+export const postPass = ({ filePath, source, spans, schemaSrc, parser, generatorMeta = defaultLookup }) => {
+    const parsedFile = parser?.parse(filePath, source);
+    const landmarks = parser && parsedFile ? parser.collectLandmarks(parsedFile) : undefined;
+    // No-parser fallback: track the most recent Definition we've
+    // crossed in document order. The spans emit each Definition's outer
+    // span before its inner Snippets, so this gives every inner span a
+    // stable landmark name even without AST analysis. Re-anchoring on
+    // formatter drift isn't possible without paths, but the SPA's
+    // hover/pin/related-artifact flows all work fine.
+    let currentDefinitionName = '';
+    const anchors = [];
+    for (const span of spans) {
+        const attr = attribute(span.producer);
+        if (attr.definitionName !== undefined)
+            currentDefinitionName = attr.definitionName;
+        const { landmark, path } = parser && parsedFile && landmarks
+            ? (() => {
+                const node = parser.smallestEnclosing(parsedFile, span.from, span.to);
+                return parser.ascendToLandmark(node, landmarks);
+            })()
+            : { landmark: currentDefinitionName, path: [] };
+        const meta = generatorMeta(attr.generatorId);
+        anchors.push({
+            span,
+            attribution: attr,
+            landmark,
+            path,
+            generatorVersion: meta.version,
+            registry: meta.registry
+        });
+    }
+    // Wholly-skipped sidecars (no spans) shouldn't claim a parser id.
+    // Otherwise tag with the parser used, or `'none'` when AST step
+    // was skipped — re-anchor consumers warn on mismatch and can
+    // detect "this sidecar has no landmark data" without inspecting
+    // the L/P pools.
+    return buildSidecar({
+        filePath,
+        schemaSrc,
+        parser: parser?.id ?? 'none',
+        anchors
+    });
+};

package/esm/anchors/sidecar.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Sidecar v2 — pooled, position-indexed attribution
+ * format. One sidecar per generated file. Lives at
+ * `<root>/.skmtc/<project>/.maps/<rel-to-basePath>.skm.json` (Phase D
+ * wires the path).
+ *
+ * Stable enough for round-trip via Valibot (see {@link sidecarSchema}).
+ * Format details: docs/notes/gen-maps/plan.md §4.1.
+ */
+import * as v from 'valibot';
+/**
+ * Registry pool entry. References the JSR-protocol registry that
+ * hosts a generator's source — `jsr.io` for public, `jsr.skmtc.dev`
+ * for the SKMTC private registry, plus any future SKMTC-compatible
+ * hosts.
+ */
+export declare const registryEntry: v.ObjectSchema<{
+    readonly host: v.StringSchema<undefined>;
+    readonly kind: v.UnionSchema<[v.LiteralSchema<"jsr", undefined>, v.LiteralSchema<"jsr-private", undefined>], undefined>;
+}, undefined>;
+/**
+ * Generator pool entry. `r` indexes into the registry pool so the
+ * viewer can build a URL without baking the registry host into every
+ * generator entry.
+ */
+export declare const generatorEntry: v.ObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly version: v.StringSchema<undefined>;
+    readonly r: v.NumberSchema<undefined>;
+}, undefined>;
+/**
+ * One row in the anchor table. Tuple of pool indices + byte range:
+ *
+ *   `[Li, Pi, gi, si, vi, fromByte, toByte]`
+ *
+ * Where `Li` = landmark, `Pi` = AST path, `gi` = generator,
+ * `si` = schema pointer, `vi` = variant. Each index is a non-negative
+ * integer; pools are flat string arrays (or objects for `R` / `G`).
+ */
+export declare const anchorRow: v.TupleSchema<[v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>], undefined>;
+/**
+ * Sidecar v2. JSON document carried alongside each generated file.
+ *
+ * - `v` is the format version. Phase 0 froze v2; format evolution
+ *   bumps this number and ships an adapter in the viewer.
+ * - `f` is the file path (relative to `basePath`), `src` is the
+ *   schema source the producer ran against.
+ * - `parser` is `"<id>@<version>"` (e.g. `"tsc@5.6.3"`); consumers
+ *   that re-anchor a reformatted file warn on mismatch.
+ * - `R`, `G`, `S`, `V`, `L`, `P` are pools. `A` is the anchor table
+ *   keyed into them.
+ * - `N` is the producer-name pool (each producer's own class name);
+ *   `An` is parallel to `A` — `An[i]` indexes into `N` for `A[i]`'s
+ *   producer. Both are optional + additive (the `A` tuple stays at 7),
+ *   so v2 consumers that don't know about them are unaffected.
+ */
+export declare const sidecarSchema: v.ObjectSchema<{
+    readonly v: v.LiteralSchema<2, undefined>;
+    readonly f: v.StringSchema<undefined>;
+    readonly src: v.StringSchema<undefined>;
+    readonly parser: v.StringSchema<undefined>;
+    readonly R: v.ArraySchema<v.ObjectSchema<{
+        readonly host: v.StringSchema<undefined>;
+        readonly kind: v.UnionSchema<[v.LiteralSchema<"jsr", undefined>, v.LiteralSchema<"jsr-private", undefined>], undefined>;
+    }, undefined>, undefined>;
+    readonly G: v.ArraySchema<v.ObjectSchema<{
+        readonly name: v.StringSchema<undefined>;
+        readonly version: v.StringSchema<undefined>;
+        readonly r: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly S: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly V: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly L: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly P: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly A: v.ArraySchema<v.TupleSchema<[v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>, v.NumberSchema<undefined>], undefined>, undefined>;
+    readonly N: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly An: v.OptionalSchema<v.ArraySchema<v.NumberSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export type Sidecar = v.InferOutput<typeof sidecarSchema>;
+export type RegistryEntry = v.InferOutput<typeof registryEntry>;
+export type GeneratorEntry = v.InferOutput<typeof generatorEntry>;
+export type AnchorRow = v.InferOutput<typeof anchorRow>;
+/**
+ * Empty sidecar with the given file/source/parser metadata. Anchor
+ * pools start empty and grow via `intern`-style appends during
+ * `buildSidecar`.
+ */
+export declare const emptySidecar: (filePath: string, schemaSrc: string, parser: string) => Sidecar;
+//# sourceMappingURL=sidecar.d.ts.map

package/esm/anchors/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/anchors/sidecar.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;aAGxB,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;aAIzB,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,yNAQpB,CAAA;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;aAcxB,CAAA;AAEF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,aAAa,CAAC,CAAA;AACzD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,aAAa,CAAC,CAAA;AAC/D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,cAAc,CAAC,CAAA;AACjE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,SAAS,CAAC,CAAA;AAEvD;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,WAAW,MAAM,EAAE,QAAQ,MAAM,KAAG,OAcjF,CAAA"}