@eir-labs/coltrane 0.10.0 → 0.12.0

package/dist/src/repo_index.d.ts

@@ -0,0 +1,58 @@
+/** One import edge: `from` imports `symbol`, which is a real export of `to`. */
+export interface ImporterEdge {
+    from: string;
+    to: string;
+    symbol: string;
+}
+/** One module-to-test link: `test` references `module`. */
+export interface ModuleTest {
+    module: string;
+    test: string;
+}
+/** One entry point: `symbol` is an export of `module` that no other module imports. */
+export interface EntryPoint {
+    module: string;
+    symbol: string;
+}
+/**
+ * The compiled index -- MECHANICAL structure only. There is deliberately no `claims` / `unknowns`
+ * / `frame` field: judgment is not the compiler's to produce (I12). The absence is a compile-time
+ * property of this type, not a runtime filter -- nothing can put a judgment field here.
+ */
+export interface RepositoryIndex {
+    source_revision: string;
+    files_to_exports: Record<string, string[]>;
+    file_importers: ImporterEdge[];
+    module_tests: ModuleTest[];
+    entry_points: EntryPoint[];
+    conventions_observed: string[];
+    boundary: string[];
+}
+/** A file in the input set: its repo-relative path and its raw source text. */
+export type RepoFile = {
+    path: string;
+    content: string;
+};
+/**
+ * The compiler refuses rather than emitting a partial index. Thrown when a relative import
+ * specifier resolves to no file in the input set -- a dangling edge is not representable, so the
+ * whole index is withheld (I18, fail-closed).
+ */
+export declare class RepoIndexError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Compile a repository index from source. Deterministic: the returned index is byte-identical
+ * under any permutation of `files`. Fails closed: a relative import that resolves to no file in
+ * the set throws RepoIndexError rather than yielding a partial, dangling index.
+ */
+export declare function compileRepositoryIndex(files: RepoFile[], opts: {
+    source_revision: string;
+}): RepositoryIndex;
+/**
+ * Reconcile a compiled index against a model's claimed reading of the SAME mechanical fields. The
+ * compiler is authoritative: on any divergence the compiled value wins, so a model-hallucinated
+ * edge is dropped (I15). The model reading is offered for comparison only -- it never adds to the
+ * mechanical structure.
+ */
+export declare function reconcileMechanical(compiled: RepositoryIndex, _modelReading: Pick<RepositoryIndex, "file_importers">): RepositoryIndex;

package/dist/src/repo_index.js

@@ -0,0 +1,232 @@
+// The deterministic producer for a change-context's MECHANICAL fields.
+//
+// The reading seat (agent john, software-change-pr-v1) spends most of a 24 tool-call cap
+// RE-DERIVING repository structure every run -- the import graph, the module-to-tests index, the
+// exported symbols and their entry points. This module COMPILES those facts from source, so the
+// mechanical half of a reading is a build artifact rather than a thing a model re-establishes by
+// hand (and mis-establishes: three hand-rolled structural sweeps this week each needed correction,
+// and a guessed invocation surface once survived into sealed tests).
+//
+// The prohibition that gives it its shape (#424 I12/I13): this compiler emits STRUCTURE ONLY. It
+// never populates `claims`, `unknowns` or `frame` -- noticing is the reader's office, not the
+// index's. The absence is enforced structurally: `RepositoryIndex` has no field for any of the
+// three, so a compiled index carrying one would not type-check. A fast index that notices nothing
+// is the POINT: it buys the reader's turns back for the judgment half a model is actually needed
+// for.
+//
+// Everything here is pure and deterministic: the same file set in any order compiles to a
+// byte-identical index (every field is canonicalised -- keys and arrays sorted -- before return).
+// The compiler fails CLOSED: an import that resolves to no file in the input set refuses with a
+// RepoIndexError rather than emitting a partial, dangling index.
+/**
+ * The compiler refuses rather than emitting a partial index. Thrown when a relative import
+ * specifier resolves to no file in the input set -- a dangling edge is not representable, so the
+ * whole index is withheld (I18, fail-closed).
+ */
+export class RepoIndexError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RepoIndexError";
+        // Restore the prototype chain under ES5-target transpilation so `instanceof` holds.
+        Object.setPrototypeOf(this, RepoIndexError.prototype);
+    }
+}
+// -- source classification -----------------------------------------------------------------------
+const TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
+const isTestFile = (path) => TEST_FILE.test(path);
+// -- a small POSIX path resolver (the tree is described in POSIX paths, no fs access) ------------
+/** Resolve a relative specifier against the importing file's directory, POSIX-style. */
+function resolveRelative(fromPath, spec) {
+    const slash = fromPath.lastIndexOf("/");
+    const fromDir = slash >= 0 ? fromPath.slice(0, slash) : "";
+    const parts = (fromDir ? fromDir.split("/") : []).concat(spec.split("/"));
+    const stack = [];
+    for (const p of parts) {
+        if (p === "" || p === ".")
+            continue;
+        if (p === "..") {
+            stack.pop();
+            continue;
+        }
+        stack.push(p);
+    }
+    return stack.join("/");
+}
+/**
+ * Map a resolved `.js`-style specifier target to the real source file in the set (the ESM/bundler
+ * convention: source is `.ts`, the specifier names the emitted `.js`). Returns the matched path,
+ * or undefined when nothing in the set answers it.
+ */
+function resolveModule(resolvedTarget, fileSet) {
+    const base = resolvedTarget.replace(/\.[cm]?jsx?$/, "");
+    const candidates = [
+        base + ".ts",
+        base + ".tsx",
+        base + ".mts",
+        base + ".cts",
+        resolvedTarget,
+        base + "/index.ts",
+        base + "/index.tsx",
+    ];
+    for (const c of candidates) {
+        if (fileSet.has(c))
+            return c;
+    }
+    return undefined;
+}
+/**
+ * Extract the named-import bindings and their module specifier from a source text. Only named
+ * imports carry the symbols an importer edge names; `import Default from` and `import * as ns`
+ * bring in no named export and are recorded with an empty symbol list (so resolution/fail-closed
+ * still runs on their specifier). Bare (non-relative) specifiers are left to the caller to skip.
+ */
+function parseImports(content) {
+    const out = [];
+    // `import [type] [ ... ] from "spec"` -- the binding clause is optional (side-effect imports).
+    const re = /import\s+(?:type\s+)?([^;'"]*?\s+from\s+)?["']([^"']+)["']/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        const clause = m[1] ?? "";
+        const spec = m[2];
+        const braces = /\{([^}]*)\}/.exec(clause);
+        const symbols = [];
+        if (braces) {
+            for (const raw of braces[1].split(",")) {
+                const name = raw.trim().split(/\s+as\s+/)[0]?.trim();
+                // The edge names the target's EXPORTED symbol -- the left side of `orig as local`.
+                if (name && /^[A-Za-z_$][\w$]*$/.test(name))
+                    symbols.push(name);
+            }
+        }
+        out.push({ spec, symbols });
+    }
+    return out;
+}
+/** Extract the exported symbol names declared in a source text. */
+function parseExports(content) {
+    const names = new Set();
+    const push = (re) => {
+        let m;
+        const g = new RegExp(re.source, "g");
+        while ((m = g.exec(content)) !== null)
+            if (m[1])
+                names.add(m[1]);
+    };
+    // export [async] function NAME / export [abstract] class NAME / export const|let|var NAME /
+    // export type|interface|enum NAME
+    push(/export\s+(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/);
+    push(/export\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/);
+    push(/export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/);
+    push(/export\s+(?:type|interface|enum)\s+([A-Za-z_$][\w$]*)/);
+    // export { a, b as c } -- the exported name is the right side of `as`, else the bare name.
+    let mm;
+    const named = /export\s*(?:type\s*)?\{([^}]*)\}(?!\s*from)/g;
+    while ((mm = named.exec(content)) !== null) {
+        for (const raw of mm[1].split(",")) {
+            const parts = raw.trim().split(/\s+as\s+/);
+            const name = (parts[1] ?? parts[0])?.trim();
+            if (name && /^[A-Za-z_$][\w$]*$/.test(name))
+                names.add(name);
+        }
+    }
+    return [...names];
+}
+const isRelative = (spec) => spec.startsWith("./") || spec.startsWith("../");
+const edgeKey = (e) => `${e.from} ${e.to} ${e.symbol}`;
+const mtKey = (m) => `${m.module} ${m.test}`;
+const epKey = (e) => `${e.module} ${e.symbol}`;
+/**
+ * Compile a repository index from source. Deterministic: the returned index is byte-identical
+ * under any permutation of `files`. Fails closed: a relative import that resolves to no file in
+ * the set throws RepoIndexError rather than yielding a partial, dangling index.
+ */
+export function compileRepositoryIndex(files, opts) {
+    const fileSet = new Set(files.map((f) => f.path));
+    // Resolve a relative specifier or FAIL CLOSED -- every endpoint of every edge must be a real file.
+    const resolveOrThrow = (fromPath, spec) => {
+        const target = resolveModule(resolveRelative(fromPath, spec), fileSet);
+        if (target === undefined) {
+            throw new RepoIndexError(`unresolvable import in ${fromPath}: "${spec}" resolves to no file in the input set -- refusing a partial, dangling index`);
+        }
+        return target;
+    };
+    const filesToExports = {};
+    const edges = new Map();
+    const moduleTests = new Map();
+    const jsExtImport = { seen: false };
+    const colocatedTests = { seen: false };
+    for (const f of files) {
+        const imports = parseImports(f.content);
+        for (const imp of imports) {
+            if (!isRelative(imp.spec))
+                continue; // external/bare specifier -- not an in-tree edge
+            if (/\.[cm]?jsx?$/.test(imp.spec))
+                jsExtImport.seen = true;
+            const target = resolveOrThrow(f.path, imp.spec);
+            if (isTestFile(f.path)) {
+                // A test file's imports feed the module-to-tests index, never the importer graph.
+                if (!isTestFile(target)) {
+                    const mt = { module: target, test: f.path };
+                    moduleTests.set(mtKey(mt), mt);
+                    colocatedTests.seen = true;
+                }
+            }
+            else {
+                // A source file's named imports are importer edges -- one per named symbol.
+                for (const symbol of imp.symbols) {
+                    const e = { from: f.path, to: target, symbol };
+                    edges.set(edgeKey(e), e);
+                }
+            }
+        }
+        if (!isTestFile(f.path)) {
+            filesToExports[f.path] = parseExports(f.content);
+        }
+    }
+    // entry_points = exported symbols no OTHER module imports (roots of symbol consumption). A
+    // symbol reached only from a test file still counts as an entry point -- tests are not consumers
+    // in the import graph.
+    const importedSymbols = new Set();
+    for (const e of edges.values())
+        importedSymbols.add(`${e.to} ${e.symbol}`);
+    const entryPoints = [];
+    for (const [module, exports] of Object.entries(filesToExports)) {
+        for (const symbol of exports) {
+            if (!importedSymbols.has(`${module} ${symbol}`))
+                entryPoints.push({ module, symbol });
+        }
+    }
+    const conventions = [];
+    if (jsExtImport.seen)
+        conventions.push("esm-js-extension-import-specifiers");
+    if (colocatedTests.seen)
+        conventions.push("tests-reference-source-by-relative-import");
+    // -- canonicalise every field: sorted keys, sorted arrays -- so JSON.stringify is order-stable --
+    const canonExports = {};
+    for (const path of Object.keys(filesToExports).sort()) {
+        canonExports[path] = [...filesToExports[path]].sort();
+    }
+    return {
+        source_revision: opts.source_revision,
+        files_to_exports: canonExports,
+        file_importers: [...edges.values()].sort((a, b) => edgeKey(a).localeCompare(edgeKey(b))),
+        module_tests: [...moduleTests.values()].sort((a, b) => mtKey(a).localeCompare(mtKey(b))),
+        entry_points: entryPoints.sort((a, b) => epKey(a).localeCompare(epKey(b))),
+        conventions_observed: conventions.sort(),
+        boundary: [...fileSet].sort(),
+    };
+}
+/**
+ * Reconcile a compiled index against a model's claimed reading of the SAME mechanical fields. The
+ * compiler is authoritative: on any divergence the compiled value wins, so a model-hallucinated
+ * edge is dropped (I15). The model reading is offered for comparison only -- it never adds to the
+ * mechanical structure.
+ */
+export function reconcileMechanical(compiled, _modelReading) {
+    void _modelReading; // authoritative-compiler contract: the model's mechanical claims do not win
+    return {
+        ...compiled,
+        file_importers: [...compiled.file_importers],
+    };
+}
+//# sourceMappingURL=repo_index.js.map

package/dist/src/repo_index.js.map

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

package/dist/src/residency.d.ts

@@ -0,0 +1,149 @@
+export { workOnce as residencyGigPath } from "./worker.js";
+export type ResidencyState = "seated" | "listening" | "playing" | "hibernated" | "drained" | "unseated";
+export declare const RESIDENCY_STATES: readonly ResidencyState[];
+export declare const LIVE_STATES: ReadonlySet<ResidencyState>;
+export type ResidencyOpKind = "claim" | "listen" | "play" | "wake_seal" | "ack" | "heartbeat" | "hibernate" | "thaw" | "drain" | "unseat" | "reap";
+export declare const RESIDENCY_OPS: readonly ResidencyOpKind[];
+export type ResidencyActor = "holder" | "reaper" | "operator";
+export interface LegalTransition {
+    from: ResidencyState;
+    op: ResidencyOpKind;
+    to: ResidencyState;
+}
+export declare const LEGAL_TRANSITIONS: readonly LegalTransition[];
+export declare const RESIDENCY_ROW_FIELDS: readonly string[];
+export declare const REFLEX_BUDGET_TICKS = 8;
+export interface ResidencyRecord {
+    agent_slug: string;
+    org: string;
+    venue_slug: string;
+    channel_id: string;
+    soul_output_id: string | null;
+    status: ResidencyState;
+    session_id: string | null;
+    cursor: number;
+    host: string | null;
+    lease_until: number;
+    heartbeat_at: number;
+    fence: number;
+    last_sealed_sha: string | null;
+    private_memory?: unknown;
+}
+export interface ResidencyOp {
+    kind: ResidencyOpKind;
+    by?: ResidencyActor;
+    fence?: number;
+    now?: number;
+    host?: string;
+    session_id?: string;
+    message_index?: number;
+    sealed_output_sha?: string | null;
+    cortex_alive?: boolean;
+    agent_slug?: string;
+    org?: string;
+    channel_id?: string;
+}
+export type ResidencyRefusal = "illegal_transition" | "wrong_party" | "stale_fence" | "dead_cortex" | "immutable_identity" | "cursor_without_seal" | "double_activation";
+export type ResidencyTransition = {
+    ok: true;
+    next: ResidencyRecord;
+} | {
+    ok: false;
+    reason: ResidencyRefusal;
+};
+export interface InboundMessage {
+    id: string;
+    text: string;
+    at: number;
+}
+export interface SimClock {
+    now(): number;
+    tick(n?: number): void;
+}
+export interface ReflexDeps {
+    invoke: (...a: unknown[]) => unknown;
+    clock: SimClock;
+}
+export interface ReflexResult {
+    acked: true;
+    elapsed_ticks: number;
+}
+export interface ResidencySpec {
+    agent_slug: string;
+    org: string;
+    venue_slug: string;
+    channel_id: string;
+}
+export interface BootDeps {
+    resolveAgent: (slug: string) => unknown | null;
+    resolveVenue: (slug: string) => unknown | null;
+    cortexPresent: () => boolean;
+    seatRow: (rec: ResidencyRecord) => void;
+}
+export type BootRefusal = "no_such_agent" | "no_such_venue" | "no_cortex";
+export type BootResult = {
+    ok: true;
+    rec: ResidencyRecord;
+} | {
+    ok: false;
+    refusal: BootRefusal;
+};
+export interface VenueLike {
+    credential_surface: readonly string[];
+}
+export type CredentialAdmission = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "credential_breach";
+};
+/**
+ * Apply one residency op under its party constraint. TOTAL: for any (state, op) pair in the closed
+ * domain it never throws — a refusal is a decision, always a discriminated {ok:false,reason}. Every
+ * pair outside LEGAL_TRANSITIONS is refused AND leaves state unchanged (the caller keeps `rec`).
+ */
+export declare function applyResidencyOp(rec: ResidencyRecord, op: ResidencyOp): ResidencyTransition;
+/**
+ * Ack an inbound message in reflex: dumb by design. Invokes the model-invoker EXACTLY zero times
+ * (even when one is present) and completes within REFLEX_BUDGET_TICKS SIMULATED ticks on the
+ * injected clock — never a wall-clock read, so the budget holds identically on any machine.
+ */
+export declare function reflexAck(_msg: InboundMessage, deps: ReflexDeps): ReflexResult;
+/**
+ * The named reader for a dead-hibernated residency: a hibernated seat whose lease has lapsed is
+ * forced to `unseated`. It reaps the DEAD and not the living — a hibernated seat still inside its
+ * lease, or any non-hibernated record, is left untouched (a refusal, so "nothing reaped" is
+ * unambiguous). `hibernated` is a valid state, so without this reader a dead hibernated residency
+ * would read as healthy because nothing queries it.
+ */
+export declare function reapResidency(rec: ResidencyRecord, now: number): ResidencyTransition;
+/**
+ * A presence cannot read its OWN impressions as content: sealing an impression as evidence would let
+ * it witness itself. The self-read is scoped out — no impression content is ever returned.
+ */
+export declare function readOwnImpressions(_rec: ResidencyRecord): {
+    content: null;
+    scoped_out: true;
+} | {
+    content: unknown;
+};
+/**
+ * Admit a credential class only if the venue explicitly declares it in its credential_surface. The
+ * venue is the SOLE hands contract; a class it does not declare — including a channel token, which
+ * belongs to the distinct voice axis — is a breach.
+ */
+export declare function admitVenueCredential(venue: VenueLike, credentialClass: string): CredentialAdmission;
+/**
+ * Seat a residency, fail-closed. Three preflight checks run IN ORDER before seatRow ever runs, so a
+ * refused boot writes no row: an unresolvable agent → no_such_agent, an unresolvable venue →
+ * no_such_venue, an absent cortex → no_cortex. Cortex liveness is not a one-shot boot assertion — it
+ * also surfaces on every subsequent heartbeat (applyResidencyOp's dead_cortex path).
+ */
+export declare function bootResidency(spec: ResidencySpec, deps: BootDeps): BootResult;
+/**
+ * The `reside` verb REUSES work's gig path — it does not fork the drain's five-variable env contract.
+ * Missing COLTRANE_STORE_URL / COLTRANE_STORE_ANON is a usage refusal (exit 2), the same door work
+ * uses (src/cli.ts:241-248). The gig itself is workOnce, re-exported above as residencyGigPath; the
+ * store/channel wiring is a deployment seam the laws inject rather than assert here.
+ */
+export declare function runReside(_argv: readonly string[], io: unknown): Promise<number>;