@eir-labs/coltrane 0.4.0

package/dist/src/skills.js

@@ -0,0 +1,258 @@
+// Skills-as-first-class — the API surface (docs/skills-as-first-class.md).
+//
+// Execution + the fixture/determinism runner are IMPLEMENTED in skill_subprocess.ts.
+// The rest of the contract — package loading + code_hash, code-first/model-residual
+// resolution, the per-resolution telemetry record, determinism_ratio computed from
+// those records, the evolution gate, and composition — is declared here as typed
+// stubs so the RED contract suite typechecks and fails honestly on assertions (not on
+// missing imports). Each stub throws NotImplemented; the build fills them in green.
+import { readFileSync, existsSync, mkdtempSync, mkdirSync, copyFileSync, readdirSync, rmSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { readSkillMeta, executeSkill, loadFixtures, runSkillFixtures, } from "./skill_subprocess.js";
+export { executeSkill, runSkillFixtures, loadFixtures, readSkillMeta, tierFlags, } from "./skill_subprocess.js";
+class NotImplemented extends Error {
+    constructor(what) {
+        super(`not implemented: ${what}`);
+        this.name = "NotImplemented";
+    }
+}
+// Typed errors at the skill layer (mirror the genome carve: hard-fail where there's no
+// recoverable order, soft-fail-with-named-error where a definition is just broken).
+export class SkillLoadError extends Error {
+}
+export class SkillCompositionCycleError extends Error {
+}
+// Declare the hash format so implementations match.
+export const CODE_HASH_ALGO = "sha256";
+export function hashSkillCode(codePath) {
+    return `${CODE_HASH_ALGO}:${createHash(CODE_HASH_ALGO).update(readFileSync(codePath)).digest("hex")}`;
+}
+/** Load a skill package: meta + code (content-hashed) + fixtures + the reasoning half.
+ *  A malformed package (unreadable/sluggless meta, bad fixture shape) raises SkillLoadError;
+ *  an ABSENT code half is allowed (codeHash null) — that degrades to pure reasoning at run. */
+export function loadSkillPackage(dir) {
+    let meta;
+    try {
+        meta = JSON.parse(readFileSync(join(dir, "meta.json"), "utf-8"));
+    }
+    catch (e) {
+        throw new SkillLoadError(`skill package ${dir}: cannot read meta.json — ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!meta || typeof meta.slug !== "string" || meta.slug.trim() === "") {
+        throw new SkillLoadError(`skill package ${dir}: meta.json is missing a slug`);
+    }
+    const codePath = join(dir, "skill.mjs");
+    const codeHash = existsSync(codePath) ? hashSkillCode(codePath) : null;
+    const mdPath = existsSync(join(dir, "skill.md")) ? join(dir, "skill.md") : null;
+    const fixtures = loadFixtures(dir);
+    for (const fx of fixtures) {
+        if (typeof fx.id !== "string" || fx.id.trim() === "" || fx.input === undefined) {
+            throw new SkillLoadError(`skill package ${meta.slug}: a fixture has an invalid shape (each needs a non-empty id and an input)`);
+        }
+    }
+    return { dir, meta, codeHash, fixtures, mdPath };
+}
+function pick(o, keys) {
+    const r = {};
+    for (const k of keys)
+        if (k in o)
+            r[k] = o[k];
+    return r;
+}
+// Warn once (not per-call) when resolutions run with no chainDir: every such call records
+// NO SkillChainEvent, so determinism_ratio never accumulates. The absence is a real gap, not
+// a no-op — surface it once so it's visible without spamming a tight resolve loop.
+let warnedNoChainDir = false;
+/** Run code first, compute the residual, let the model fill only the gap, tag origins.
+ *  When `opts.chainDir` is set, append a SkillChainEvent recording this resolution. */
+export async function resolveSkill(dir, input, invoke, opts) {
+    if (!opts?.chainDir && !warnedNoChainDir) {
+        warnedNoChainDir = true;
+        console.warn("[skills] resolveSkill running without chainDir — no SkillChainEvent recorded; determinism_ratio will not accumulate.");
+    }
+    const pkg = loadSkillPackage(dir);
+    // schema fields bound what code/model may resolve. No schema → the code's own keys are
+    // the shape (nothing is "unresolved"), so the model is never asked.
+    const props = pkg.meta.output_schema?.properties;
+    const schemaFields = props ? Object.keys(props) : null;
+    // 1. code first — unless the code can't be trusted/run (graceful degradation, never throws)
+    let resolved = {};
+    let degraded;
+    let duration_ms = 0;
+    if (pkg.codeHash === null) {
+        degraded = { reason: "no code half — resolving via pure reasoning" };
+    }
+    else if (typeof pkg.meta.code_hash === "string" && pkg.meta.code_hash !== pkg.codeHash) {
+        degraded = { reason: `code_hash mismatch — declared ${pkg.meta.code_hash}, on disk ${pkg.codeHash}; unverified code not run` };
+    }
+    else {
+        const r = executeSkill(dir, input);
+        duration_ms = r.duration_ms;
+        if (!r.ok) {
+            degraded = { reason: `code half threw / produced no output: ${r.error}` };
+        }
+        else {
+            const out = (r.output && typeof r.output === "object" ? r.output : {});
+            // typing guarantee: code can only resolve fields that exist in the output schema
+            resolved = schemaFields ? pick(out, schemaFields) : out;
+        }
+    }
+    // 2. residual = schema − what the code resolved (subset of the schema, always)
+    const resolvedKeys = Object.keys(resolved);
+    const residual = schemaFields ? schemaFields.filter((f) => !resolvedKeys.includes(f)) : [];
+    // 3. the model fills ONLY the residual; resolved fields are verified context it can't override
+    let modelFields = {};
+    if (residual.length > 0) {
+        const md = pkg.mdPath ? readFileSync(pkg.mdPath, "utf-8") : "";
+        const m = await invoke({ unresolved: residual, resolved, md });
+        modelFields = pick(m ?? {}, residual);
+    }
+    // 4. union + origins
+    const output = { ...resolved, ...modelFields };
+    const field_origins = {};
+    for (const k of Object.keys(resolved))
+        field_origins[k] = "code";
+    for (const k of Object.keys(modelFields))
+        field_origins[k] = "model";
+    if (opts?.chainDir) {
+        appendSkillChainEvent(opts.chainDir, {
+            slug: pkg.meta.slug,
+            version: pkg.meta.version,
+            code_hash: pkg.codeHash ?? "",
+            tier: pkg.meta.permission?.tier ?? 0,
+            duration_ms,
+            permission_violations: [],
+            field_origins,
+            ...(degraded ? { degraded_reason: degraded.reason } : {}),
+        });
+    }
+    return { output, resolved, residual, field_origins, ...(degraded ? { degraded } : {}) };
+}
+function appendSkillChainEvent(chainDir, ev) {
+    mkdirSync(chainDir, { recursive: true });
+    appendFileSync(join(chainDir, `${ev.slug}.jsonl`), JSON.stringify(ev) + "\n");
+}
+/** Read the recorded resolution events for a skill+version — the log determinism reads from. */
+export function skillChainEvents(slug, version, opts) {
+    const dir = opts?.chainDir;
+    if (!dir)
+        return []; // ambient store (from sealed records) is a Phase-3 open question
+    const path = join(dir, `${slug}.jsonl`);
+    if (!existsSync(path))
+        return [];
+    const events = readFileSync(path, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim() !== "")
+        .map((l) => JSON.parse(l));
+    return version === undefined ? events : events.filter((e) => e.version === version);
+}
+export function computeDeterminismRatio(slug, version, opts) {
+    const window = opts?.window ?? 100;
+    const events = skillChainEvents(slug, version, opts).slice(-window);
+    // each event's code-resolved fraction; the ratio is the rolling average across the window
+    const fractions = events.map((e) => {
+        const origins = Object.values(e.field_origins);
+        return origins.length ? origins.filter((o) => o === "code").length / origins.length : 0;
+    });
+    const ratio = fractions.length ? fractions.reduce((a, b) => a + b, 0) / fractions.length : 0;
+    return { slug, version, ratio, window, samples: events.length };
+}
+/** Run a candidate skill.mjs against the package's fixtures; accept iff none regress. The
+ *  fixtures are the evolution gate: an "improvement" that breaks any committed contract is
+ *  rejected, and the broken fixtures are named. */
+export function evolveSkill(dir, candidateCodePath) {
+    const tmp = mkdtempSync(join(tmpdir(), "coltrane-evolve-"));
+    try {
+        copyFileSync(join(dir, "meta.json"), join(tmp, "meta.json"));
+        const fxSrc = join(dir, "fixtures");
+        if (existsSync(fxSrc)) {
+            mkdirSync(join(tmp, "fixtures"), { recursive: true });
+            for (const f of readdirSync(fxSrc))
+                copyFileSync(join(fxSrc, f), join(tmp, "fixtures", f));
+        }
+        copyFileSync(candidateCodePath, join(tmp, "skill.mjs"));
+        const report = runSkillFixtures(tmp);
+        const failing_fixtures = report.results.filter((r) => !r.passed).map((r) => r.id);
+        return { accepted: failing_fixtures.length === 0, failing_fixtures };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** Compose multiple skills for one chair: validate composable_with, order by deps,
+ *  detect cycles (SkillCompositionCycleError), merge the residual. */
+export function composeSkills(dirs) {
+    const pkgs = dirs.map((d) => loadSkillPackage(d));
+    const slugs = pkgs.map((p) => p.meta.slug);
+    const fields = (p, half) => Object.keys((p.meta[half]?.properties ?? {}));
+    // 1. composable_with: every pair must be declared composable by at least one side
+    for (let i = 0; i < pkgs.length; i++) {
+        for (let j = i + 1; j < pkgs.length; j++) {
+            const a = pkgs[i], b = pkgs[j];
+            const ok = (a.meta.composable_with ?? []).includes(b.meta.slug) || (b.meta.composable_with ?? []).includes(a.meta.slug);
+            if (!ok)
+                throw new SkillLoadError(`skills "${a.meta.slug}" and "${b.meta.slug}" are not composable_with each other`);
+        }
+    }
+    // 2. shared output fields must declare identical types
+    const seen = new Map();
+    for (const p of pkgs) {
+        const props = (p.meta.output_schema?.properties ?? {});
+        for (const [f, def] of Object.entries(props)) {
+            const prev = seen.get(f);
+            if (prev && JSON.stringify(prev.type) !== JSON.stringify(def?.type)) {
+                throw new SkillLoadError(`type conflict on shared output field "${f}": "${prev.owner}" declares ${JSON.stringify(prev.type)}, "${p.meta.slug}" declares ${JSON.stringify(def?.type)}`);
+            }
+            if (!prev)
+                seen.set(f, { type: def?.type, owner: p.meta.slug });
+        }
+    }
+    // 3. dependency edges: B depends on A if B's input references a field A outputs
+    const outputs = new Map(pkgs.map((p) => [p.meta.slug, new Set(fields(p, "output_schema"))]));
+    const deps = new Map(slugs.map((s) => [s, new Set()]));
+    for (const p of pkgs) {
+        for (const other of pkgs) {
+            if (other.meta.slug === p.meta.slug)
+                continue;
+            const outs = outputs.get(other.meta.slug);
+            if (fields(p, "input_schema").some((f) => outs.has(f)))
+                deps.get(p.meta.slug).add(other.meta.slug);
+        }
+    }
+    // 4. topological order (deterministic, independent of input order); cycle → cycle error.
+    // The error names the FULL cycle path (A → B → C → A), not just the node we re-entered —
+    // a one-node message can't be regression-tested for the right cycle, and a multi-node
+    // cycle is undebuggable without its path. The in-progress (color-1) stack IS the path.
+    const order = [];
+    const state = new Map();
+    const visit = (s, path) => {
+        const st = state.get(s) ?? 0;
+        if (st === 2)
+            return;
+        if (st === 1) {
+            const from = path.indexOf(s);
+            const cycle = [...path.slice(from), s].join(" → ");
+            throw new SkillCompositionCycleError(`skill composition cycle: ${cycle}`);
+        }
+        state.set(s, 1);
+        for (const d of [...deps.get(s)].sort())
+            visit(d, [...path, s]);
+        state.set(s, 2);
+        order.push(s);
+    };
+    for (const s of [...slugs].sort())
+        visit(s, []);
+    // 5. merged residual: fields no skill's code resolves (a pure-reasoning skill resolves none)
+    const merged = new Set();
+    for (const p of pkgs)
+        if (p.codeHash === null)
+            for (const f of fields(p, "output_schema"))
+                merged.add(f);
+    return { order, merged_residual: [...merged] };
+}
+// Re-export to keep the type checker honest about unused-import in stubs.
+void readSkillMeta;
+void executeSkill;
+//# sourceMappingURL=skills.js.map

package/dist/src/skills.js.map

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

package/dist/src/subthread_recorder.d.ts

@@ -0,0 +1,68 @@
+export interface SubthreadEntry {
+    session_id: string;
+    turn_idx: number;
+    parent_session_id: string | null;
+    api_version: string;
+    genome_hash: string;
+    run_fingerprint: string;
+    tool_call_sequence: string[];
+    started_at: string;
+    finished_at: string | null;
+    error?: string;
+    observability_log?: Record<string, unknown>;
+}
+export interface RecorderOptions {
+    path: string;
+    session_id: string;
+    parent_session_id?: string | null | undefined;
+    api_version: string;
+    genome_hash: string;
+    run_fingerprint: string;
+}
+export declare class ApiVersionMismatchError extends Error {
+    readonly recorded: string;
+    readonly current: string;
+    constructor(recorded: string, current: string);
+}
+/**
+ * A file-backed recorder that captures one entry per sub-thread turn, keyed on
+ * session_id. Each turn is one server lifetime; resume across lifetimes increments
+ * turn_idx. Entries carry deterministic provenance fields (genome_hash,
+ * run_fingerprint, tool_call_sequence) plus lifecycle timestamps that callers
+ * can exclude from hash-stability checks.
+ */
+export declare class SubthreadRecorder {
+    readonly path: string;
+    readonly session_id: string;
+    readonly parent_session_id: string | null;
+    readonly api_version: string;
+    readonly genome_hash: string;
+    readonly run_fingerprint: string;
+    readonly turn_idx: number;
+    private tool_call_sequence;
+    private observability_log;
+    private started_at;
+    private finished_at;
+    private error;
+    private flushed;
+    private constructor();
+    /**
+     * Open a recorder for this server lifetime. Detects api_version mismatch
+     * against prior turns for the same session_id and throws
+     * `ApiVersionMismatchError`; the typed error is also sealed into the recorder
+     * before throwing so the failure is auditable.
+     */
+    static open(opts: RecorderOptions): SubthreadRecorder;
+    recordToolCall(name: string): void;
+    recordObservability(key: string, value: unknown): void;
+    flush(): void;
+    private current;
+    private persist;
+}
+/**
+ * Stable hash over a recorder file scoped to deterministic provenance fields —
+ * excludes session_id (varies per Claude session), timestamps, and observability
+ * payloads. Used by reproducibility checks to compare two runs against the same
+ * genome.
+ */
+export declare function hashRecorderDeterministicFields(path: string): string;

package/dist/src/subthread_recorder.js

@@ -0,0 +1,166 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+export class ApiVersionMismatchError extends Error {
+    recorded;
+    current;
+    constructor(recorded, current) {
+        super(`api_version_mismatch: recorded=${recorded} current=${current}`);
+        this.name = "ApiVersionMismatchError";
+        this.recorded = recorded;
+        this.current = current;
+    }
+}
+function readAllEntries(path) {
+    if (!existsSync(path))
+        return [];
+    const lines = readFileSync(path, "utf-8").split("\n").filter((l) => l.length > 0);
+    const out = [];
+    for (const line of lines) {
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+    return out;
+}
+function writeAllEntries(path, entries) {
+    mkdirSync(dirname(path), { recursive: true });
+    const body = entries.map((e) => JSON.stringify(e)).join("\n") + (entries.length > 0 ? "\n" : "");
+    writeFileSync(path, body);
+}
+/**
+ * A file-backed recorder that captures one entry per sub-thread turn, keyed on
+ * session_id. Each turn is one server lifetime; resume across lifetimes increments
+ * turn_idx. Entries carry deterministic provenance fields (genome_hash,
+ * run_fingerprint, tool_call_sequence) plus lifecycle timestamps that callers
+ * can exclude from hash-stability checks.
+ */
+export class SubthreadRecorder {
+    path;
+    session_id;
+    parent_session_id;
+    api_version;
+    genome_hash;
+    run_fingerprint;
+    turn_idx;
+    tool_call_sequence = [];
+    observability_log = {};
+    started_at;
+    finished_at = null;
+    error = null;
+    flushed = false;
+    constructor(opts, turn_idx) {
+        this.path = opts.path;
+        this.session_id = opts.session_id;
+        this.parent_session_id = opts.parent_session_id ?? null;
+        this.api_version = opts.api_version;
+        this.genome_hash = opts.genome_hash;
+        this.run_fingerprint = opts.run_fingerprint;
+        this.turn_idx = turn_idx;
+        this.started_at = new Date().toISOString();
+    }
+    /**
+     * Open a recorder for this server lifetime. Detects api_version mismatch
+     * against prior turns for the same session_id and throws
+     * `ApiVersionMismatchError`; the typed error is also sealed into the recorder
+     * before throwing so the failure is auditable.
+     */
+    static open(opts) {
+        const prior = readAllEntries(opts.path).filter((e) => e.session_id === opts.session_id);
+        const turn_idx = prior.length;
+        if (prior.length > 0) {
+            const firstApi = prior[0].api_version;
+            if (firstApi !== opts.api_version) {
+                const mismatchEntry = {
+                    session_id: opts.session_id,
+                    turn_idx,
+                    parent_session_id: opts.parent_session_id ?? null,
+                    api_version: opts.api_version,
+                    genome_hash: opts.genome_hash,
+                    run_fingerprint: opts.run_fingerprint,
+                    tool_call_sequence: [],
+                    started_at: new Date().toISOString(),
+                    finished_at: new Date().toISOString(),
+                    error: `api_version_mismatch: recorded=${firstApi} current=${opts.api_version}`,
+                };
+                appendFileSync(opts.path, JSON.stringify(mismatchEntry) + "\n");
+                throw new ApiVersionMismatchError(firstApi, opts.api_version);
+            }
+        }
+        const rec = new SubthreadRecorder(opts, turn_idx);
+        rec.persist();
+        return rec;
+    }
+    recordToolCall(name) {
+        if (this.flushed)
+            return;
+        this.tool_call_sequence.push(name);
+        this.persist();
+    }
+    recordObservability(key, value) {
+        if (this.flushed)
+            return;
+        this.observability_log[key] = value;
+        this.persist();
+    }
+    flush() {
+        if (this.flushed)
+            return;
+        this.finished_at = new Date().toISOString();
+        this.flushed = true;
+        this.persist();
+    }
+    current() {
+        const entry = {
+            session_id: this.session_id,
+            turn_idx: this.turn_idx,
+            parent_session_id: this.parent_session_id,
+            api_version: this.api_version,
+            genome_hash: this.genome_hash,
+            run_fingerprint: this.run_fingerprint,
+            tool_call_sequence: [...this.tool_call_sequence],
+            started_at: this.started_at,
+            finished_at: this.finished_at,
+            observability_log: { ...this.observability_log },
+        };
+        if (this.error)
+            entry.error = this.error;
+        return entry;
+    }
+    persist() {
+        const all = readAllEntries(this.path);
+        const idx = all.findIndex((e) => e.session_id === this.session_id && e.turn_idx === this.turn_idx);
+        const next = this.current();
+        if (idx >= 0)
+            all[idx] = next;
+        else
+            all.push(next);
+        writeAllEntries(this.path, all);
+    }
+}
+/**
+ * Stable hash over a recorder file scoped to deterministic provenance fields —
+ * excludes session_id (varies per Claude session), timestamps, and observability
+ * payloads. Used by reproducibility checks to compare two runs against the same
+ * genome.
+ */
+export function hashRecorderDeterministicFields(path) {
+    const entries = readAllEntries(path);
+    if (entries.length === 0)
+        return "EMPTY";
+    const scoped = entries.map((e) => ({
+        turn_idx: e.turn_idx,
+        api_version: e.api_version,
+        genome_hash: e.genome_hash,
+        run_fingerprint: e.run_fingerprint,
+        tool_call_sequence: e.tool_call_sequence,
+        parent_present: e.parent_session_id !== null,
+    }));
+    // Order by turn_idx so resume-order matters but session-id-suffix doesn't leak in.
+    scoped.sort((a, b) => a.turn_idx - b.turn_idx);
+    return createHash("sha256").update(JSON.stringify(scoped)).digest("hex");
+}
+//# sourceMappingURL=subthread_recorder.js.map

package/dist/src/subthread_recorder.js.map

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

package/dist/src/tensor_read.d.ts

@@ -0,0 +1,38 @@
+export interface ChannelReading<T = unknown> {
+    channel: string;
+    produced_by: string;
+    payload: T;
+}
+export interface TensorRead {
+    gig_id: string;
+    readings: readonly ChannelReading[];
+}
+export declare class TensorReadError extends Error {
+}
+export declare function emptyTensorRead(gig_id: string): TensorRead;
+export declare function addChannel(tensor: TensorRead, reading: ChannelReading): TensorRead;
+export declare function readChannel(tensor: TensorRead, channel: string): ChannelReading | undefined;
+export interface ChannelDiff {
+    channel: string;
+    present_in_both: boolean;
+    a_only: boolean;
+    b_only: boolean;
+    a_produced_by?: string | undefined;
+    b_produced_by?: string | undefined;
+}
+export interface TensorDiff {
+    gig_a: string;
+    gig_b: string;
+    channels: readonly ChannelDiff[];
+}
+export declare function compareTensorReads(a: TensorRead, b: TensorRead): TensorDiff;
+/**
+ * Pure cardinality helpers. Return NUMBERS so a downstream policy layer can
+ * weight them inside the tensor — never as standalone verdicts.
+ */
+export declare function channelCount(tensor: TensorRead): number;
+export declare function uniqueChannels(diff: TensorDiff): {
+    in_both: number;
+    a_only: number;
+    b_only: number;
+};

package/dist/src/tensor_read.js

@@ -0,0 +1,60 @@
+// Multi-channel tensor read. Each channel of a gig (score, output, song, etc)
+// produces its own structured reading. The TensorRead holds them side-by-side
+// WITHOUT collapsing to a scalar. Validation across channels reads pairwise
+// diffs; the tensor itself is never reduced to "pass/fail."
+export class TensorReadError extends Error {
+}
+export function emptyTensorRead(gig_id) {
+    return { gig_id, readings: [] };
+}
+export function addChannel(tensor, reading) {
+    if (tensor.readings.some((r) => r.channel === reading.channel)) {
+        throw new TensorReadError(`tensor already has a reading for channel "${reading.channel}"`);
+    }
+    return {
+        gig_id: tensor.gig_id,
+        readings: [...tensor.readings, reading],
+    };
+}
+export function readChannel(tensor, channel) {
+    return tensor.readings.find((r) => r.channel === channel);
+}
+export function compareTensorReads(a, b) {
+    const channels = new Set();
+    for (const r of a.readings)
+        channels.add(r.channel);
+    for (const r of b.readings)
+        channels.add(r.channel);
+    const diffs = [];
+    for (const ch of channels) {
+        const ra = readChannel(a, ch);
+        const rb = readChannel(b, ch);
+        const diff = {
+            channel: ch,
+            present_in_both: !!ra && !!rb,
+            a_only: !!ra && !rb,
+            b_only: !ra && !!rb,
+        };
+        if (ra?.produced_by)
+            diff.a_produced_by = ra.produced_by;
+        if (rb?.produced_by)
+            diff.b_produced_by = rb.produced_by;
+        diffs.push(diff);
+    }
+    return { gig_a: a.gig_id, gig_b: b.gig_id, channels: diffs };
+}
+/**
+ * Pure cardinality helpers. Return NUMBERS so a downstream policy layer can
+ * weight them inside the tensor — never as standalone verdicts.
+ */
+export function channelCount(tensor) {
+    return tensor.readings.length;
+}
+export function uniqueChannels(diff) {
+    return {
+        in_both: diff.channels.filter((c) => c.present_in_both).length,
+        a_only: diff.channels.filter((c) => c.a_only).length,
+        b_only: diff.channels.filter((c) => c.b_only).length,
+    };
+}
+//# sourceMappingURL=tensor_read.js.map

package/dist/src/tensor_read.js.map

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