@descryy/ir 0.1.0

package/dist/ir.d.ts

@@ -0,0 +1,360 @@
+/**
+ * The Canonical IR — the boundary every language reaches the graph through.
+ *
+ * Nothing above this boundary may name a language (architecture principle 7).
+ * `language` is carried as provenance so findings can be reported honestly; it is
+ * never branched on. The boundary lint enforces that mechanically.
+ */
+import type { EdgeType, NodeType } from "./vocabulary.ts";
+/**
+ * How well the code behind a node or edge was actually understood.
+ *
+ * R0 tree-sitter only · R1 + module resolution · R2 + LSP references/definitions
+ * · R3 + type checker (shapes) · R4 observed firing at runtime.
+ *
+ * This is the third confidence axis, alongside reliability class and environment
+ * level. It caps the reliability class of any finding resting on it, which is
+ * what stops multi-language support meaning multi-language guessing.
+ *
+ * Includes 4. See DEC-005 — R4 was defined in the architecture's prose but the
+ * IR type still read `0 | 1 | 2 | 3`, leaving the stated core moat nowhere to be
+ * stored.
+ */
+export type ResolutionLevel = 0 | 1 | 2 | 3 | 4;
+export declare const RESOLUTION_LEVELS: readonly [0, 1, 2, 3, 4];
+/** Inclusive line range within a file. */
+export interface Range {
+    readonly startLine: number;
+    readonly endLine: number;
+}
+export interface IRNode {
+    /**
+     * Stable across runs AND across file moves: `n2:` + hash(scope, language, kind,
+     * qualified symbol path). Deliberately excludes file path — see DEC-004,
+     * DEC-011 and DEC-054.
+     */
+    readonly id: string;
+    readonly type: NodeType;
+    readonly name: string;
+    /** Repo-relative. Null for fileless node types — see DEC-014. */
+    readonly file: string | null;
+    /** Null wherever `file` is null. */
+    readonly range: Range | null;
+    /**
+     * Provenance only. NEVER branched on above the IR boundary.
+     * Null on `API_ENDPOINT`, which belongs to no single language — the Normaliser
+     * sets this and rejects any adapter that claims otherwise.
+     */
+    readonly language: string | null;
+    /** `adapterId@version`. Drives graph invalidation on adapter upgrade. */
+    readonly producedBy: string;
+    readonly resolution: ResolutionLevel;
+    /**
+     * Language- and framework-specific detail, opaque above the boundary. This is
+     * the pressure valve that keeps the type list at 15: a Django model and a
+     * Prisma model are both `MODEL`, and what differs lives here.
+     *
+     * Never part of node identity.
+     */
+    readonly attrs: Readonly<Record<string, unknown>>;
+}
+export interface IREdge {
+    readonly from: string;
+    readonly to: string;
+    readonly type: EdgeType;
+    readonly resolution: ResolutionLevel;
+    /** 0–1. Feeds the impact score. Clamped down by resolution, never up. */
+    readonly confidence: number;
+    readonly producedBy: string;
+    /**
+     * The run that witnessed this edge actually firing. Required when
+     * `resolution === 4`; meaningless otherwise. Drives R4 expiry.
+     */
+    readonly observedByRun?: string;
+    readonly attrs?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A reference an adapter saw but could not resolve to a real node.
+ *
+ * These are NOT written as edges. A name-matched guess is a false claim, and one
+ * wrong edge corrupts every layer above the graph — so it is dropped. But dropped
+ * silently there is no denominator for recall and nothing to report under "not
+ * analysable", so it is recorded here instead.
+ *
+ * Measured on real prior-art graphs, this is 52–60% of everything an adapter
+ * emits. See DEC-016.
+ */
+export interface UnresolvedRef {
+    readonly fromNodeId: string;
+    readonly edgeType: EdgeType;
+    /** The raw text the adapter could not resolve, e.g. `append`. */
+    readonly rawTarget: string;
+    readonly file: string | null;
+    readonly line: number | null;
+    readonly producedBy: string;
+    readonly reason: string;
+    /**
+     * Producer-supplied detail, opaque above this boundary — the same contract
+     * as `IRNode.attrs`/`IREdge.attrs`. Two keys are named here:
+     *
+     * `blockedBy` — the literal source text of the specific expression that
+     * stopped resolution, e.g. `env.BACKEND_API_BASE_URL`,
+     * `import.meta.env.VITE_BACKEND_API_URL`. NOT the callee (`rawTarget`
+     * already carries that — `fetch`, `api.get`) and NOT a restatement of
+     * `reason` (prose for a person; `blockedBy` is the exact string a later
+     * human-confirmed answer is matched against, byte for byte, scoped to one
+     * repo — DEC-223 §3). `null` or absent means the row's cause is not "one
+     * unresolved expression" — a genuinely dynamic call has nothing singular
+     * to name.
+     *
+     * `refusalClass` — one of `UNRESOLVED_REF_CLASSES`, the producer's own
+     * answer to "can a human sentence ever resolve this row?" A `blockedBy`
+     * string alone cannot say that: naming the blocking expression does not
+     * mean a person can supply its value — see `UnresolvedRefClass`'s own doc
+     * for why this is a second, independent field rather than folded into the
+     * first. Never inferred from `reason`'s prose by a consumer (rule 3 — a
+     * text/name heuristic is not evidence); a producer sets it only when it
+     * knows structurally which bucket a row is in.
+     *
+     * **Assigned after config resolution, not before.** A producer must first
+     * check whatever local config sources it already reads (`.env` files,
+     * `wrangler.toml`'s `[vars]`, framework config) for the blocked
+     * expression's value — CLAUDE.md's own rule, "if the framework will tell
+     * you, never infer it." Only a value genuinely absent from every config
+     * source this reader can see is `"value-unknown"`; a value already sitting
+     * in a config file the repo contains must never reach this field as
+     * unresolved, and must never be classified in a way that could route it to
+     * a human. This ordering is a producer-side contract this field cannot
+     * enforce structurally — stated here because a shape that assumed
+     * classification runs first would license exactly that mistake.
+     *
+     * Both keys are optional and unenforced: most producers do not set them
+     * yet, and absence is a disclosed gap, never a rejection — see the
+     * reconciliation test in `normalise.test.ts` and DEC-223. Absent
+     * `refusalClass` means **unclassified**, and an unclassified row must never
+     * be defaulted to askable by a consumer — see the type's own doc.
+     */
+    readonly attrs?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The closed set `attrs.refusalClass` may hold on an `UnresolvedRef`.
+ *
+ * Producer-declared, never inferred from `reason`'s prose — a text/name
+ * heuristic over a free-text field is exactly the guess rule 3 bans, and
+ * `reason` is reworded by producers without the underlying question changing
+ * (`packages/core/src/query/unresolved.ts`'s own header is the measured
+ * account of that failure). Assigned only after the producer's own
+ * config-resolution pass has had a chance to answer the row from a source
+ * the repo already contains — see `UnresolvedRef.attrs`'s doc.
+ *
+ * - `"value-unknown"` — the row names something whose *value* the reader does
+ *   not statically know AND does not find in any config source it reads (an
+ *   env var with no matching `.env`/deploy-config entry). One human sentence
+ *   can resolve it, and — because matching is exact-string on
+ *   `(repo, blockedBy)` — the same sentence resolves every row in that repo
+ *   sharing the identical `attrs.blockedBy` (DEC-223 §3). This is the class
+ *   `blockedBy` was built for, and the only one a question queue may surface.
+ * - `"capability-gap"` — the reader cannot parse or resolve this shape at
+ *   all: an enum-dispatched verb, a path pattern it does not trace, a
+ *   language construct with no extractor yet. No sentence answers this —
+ *   only code does — and it must never reach a question queue. Measured: 92
+ *   of 95 censused C#/Java refusal rows are this class, not `value-unknown`.
+ * - `"out-of-scope"` — the reference resolved correctly to something outside
+ *   this workspace (a third-party host, another team's service) and was
+ *   filed as a refusal anyway. Correct information sitting in the wrong
+ *   ledger, not a gap and not askable either.
+ * - `"varies-per-call"` — the blocked value is not fixed anywhere to ask
+ *   about: a caller-supplied prop, a function parameter, a request-scoped
+ *   value that is, by design, different on every call (`FileViewerModal`'s
+ *   `url` prop; an upload helper's destination argument). Distinct from
+ *   `"value-unknown"` on purpose — that class means *a* fixed value exists
+ *   and nobody has stated it yet; this class means no single value exists to
+ *   state. Asking a human "what is `url`?" here is a category error, not an
+ *   unanswered question, and folding this into `"value-unknown"` behind a
+ *   flag would let a consumer that forgets to check the flag put an
+ *   unanswerable row in front of someone anyway — the same failure a missing
+ *   class was already found to cause once (see the measured C#/Java case
+ *   below). A dedicated class makes the omission a type error instead.
+ *
+ * **Absent means unclassified, not `"value-unknown"`.** A consumer building a
+ * question queue from this ledger must treat an unset `refusalClass` as
+ * not-askable — defaulting unset to askable is exactly how an unaudited row
+ * would reach a user as a question nobody vetted.
+ *
+ * This split is proposed from measured censuses across two cycles, not
+ * settled — whether `"out-of-scope"` belongs in this ledger at all, rather
+ * than being a class within it, is an open question for whoever reviews this
+ * contract next, not decided here.
+ */
+export declare const UNRESOLVED_REF_CLASSES: readonly ["value-unknown", "capability-gap", "out-of-scope", "varies-per-call"];
+export type UnresolvedRefClass = (typeof UNRESOLVED_REF_CLASSES)[number];
+/**
+ * DEC-223's answer half — a person's confirmed value for a `"value-unknown"`
+ * refusal-ledger row.
+ *
+ * Keyed on **exact string equality on `(repo, blockedBy)`, never fuzzy and
+ * never inferred across repositories** (rule 3 — "an answer is a declaration
+ * about the case it answers, never an inference about a second one"). `env.
+ * BACKEND_URL` and `env.BACKEND_API_BASE_URL` are different questions even
+ * when they plausibly resolve the same way; the same repository's identically
+ * spelled variable in a second application is a different case entirely.
+ * `blockedBy` here matches `UnresolvedRef.attrs.blockedBy` byte for byte —
+ * the field is named identically on both sides deliberately, so a reader (and
+ * a linter) can see the two are the same value without tracing a rename. A
+ * row with no `blockedBy` has nothing to key an answer on and cannot be
+ * answered by this mechanism at all, only by a code change.
+ *
+ * One fact legitimately answers every ledger row in `repo` sharing the
+ * identical `blockedBy` value, because they are, by construction, blocked by
+ * the same runtime binding — DEC-223's own measured case is exactly this: one
+ * `BACKEND_API_BASE_URL` value would join 18 rows in `sherpa-cf-worker`, one
+ * `VITE_BACKEND_API_URL` value already joins 50 in `sherpa-frontend`.
+ *
+ * This type says nothing about what an edge built from it may be classified
+ * as — that is `reliabilityCap`'s `humanAsserted` parameter, a second and
+ * independent guard, deliberately not encoded here so that a consumer cannot
+ * satisfy the obligation by constructing a `ConfirmedFact` correctly and then
+ * forgetting to pass the flag three functions later.
+ */
+export interface ConfirmedFact {
+    /** Scope — matches `RepoRoot.repo`. Never inferred across repositories. */
+    readonly repo: string;
+    /** Must equal some row's `attrs.blockedBy`, exact string match. */
+    readonly blockedBy: string;
+    /** The human-supplied literal. */
+    readonly value: string;
+    /**
+     * Optional, and unscoped is a legal, common answer — not a placeholder for
+     * one not yet given. A real answer arrived for `VITE_BACKEND_API_URL` in
+     * `sherpa-frontend` naming no environment at all, and forcing one would
+     * have meant guessing rather than recording what was actually said.
+     *
+     * Two facts for the same `(repo, blockedBy)` are the same answer only when
+     * their `environment` also matches (`undefined` is its own value, not a
+     * wildcard) — recording `"staging"` after recording an unscoped answer adds
+     * a second fact rather than overwriting the first, because a repository can
+     * genuinely need three different values for one expression: one per
+     * environment, or none at all when the repository does not distinguish
+     * them. `applyConfirmedFacts` surfaces every matching fact rather than
+     * picking one, so a caller sees the split rather than an arbitrarily
+     * chosen value.
+     *
+     * **Human-supplied only, never inferred.** Nothing above this type may
+     * read `"staging"` out of a hostname or a file path and assign it here —
+     * the same discipline `blockedBy` matching already applies to `expression`
+     * text, extended to this field: a guess dressed as a declaration is worse
+     * than an honest `undefined`.
+     */
+    readonly environment?: string;
+    /** Free text — who or what asserted this. Not validated; recorded as given. */
+    readonly confirmedBy: string;
+    /** ISO timestamp. */
+    readonly confirmedAt: string;
+    /**
+     * The repo's `commitSha` (see `IRBatch.commitSha`) at the moment this fact
+     * was confirmed — "against what", to `confirmedAt`'s "when". Optional: a
+     * fact confirmed before this field existed carries none, and that absence
+     * is itself meaningful (staleness cannot be checked, not "assumed fresh") —
+     * never backfilled with a guess.
+     *
+     * This is the disclosure floor, not a re-verification mechanism: nothing
+     * reads this field to re-check a fact against a live source (there is no
+     * live source yet — `descry-runtime` does not exist). It exists so a
+     * consumer minting an edge from this fact *today* can say whether today's
+     * commit matches the one the human answer was given against, and disclose
+     * the mismatch rather than presenting an old answer as current.
+     */
+    readonly confirmedAtCommit?: string;
+}
+/**
+ * A node this batch offers as a target for a **declared cross-language
+ * namespace peer** — see `CapabilityMatrix.crossLanguageNamespace`, DEC-161.
+ *
+ * `qualifiedName` is what the REFERENCING side's own source would spell to
+ * name this node — a Java `import`'s fully-qualified name, for a Kotlin
+ * declaration reached from Java. It is opaque above this point: the resolver
+ * that consumes it does string equality only, never parses it, and nothing
+ * above the IR may know what syntax produced it. This is the field
+ * `IRNode.id`'s hash cannot serve in its place — an id is stable and
+ * unreadable by design, and a cross-language match needs a string a *different
+ * adapter* could independently compute.
+ *
+ * Not identity. `nodeId` is the real, existing node id; this is an additional,
+ * adapter-declared fact about how to *reach* it from outside its own language.
+ */
+export interface CrossLanguageDeclaration {
+    readonly qualifiedName: string;
+    readonly nodeId: string;
+}
+/**
+ * Why a file this batch's adapter attempted contributed no nodes or edges.
+ *
+ * Distinct from `UnresolvedRef` — that ledger is a reference the adapter *saw*
+ * and could not resolve to a node; this is a file the adapter could not read
+ * or parse at all, so it never got the chance to see anything in it. Mirrors
+ * `ParseFailure` (`@descryhq-wq/adapter-treesitter`) rather than inventing new
+ * vocabulary, since that shape is already what most producers compute — this
+ * field just gives it somewhere to go instead of dead-ending on `session`.
+ */
+export declare const SKIP_REASONS: readonly ["too-large", "unreadable", "grammar-error", "other"];
+export type SkipReason = (typeof SKIP_REASONS)[number];
+export interface SkippedFile {
+    readonly file: string;
+    readonly reason: SkipReason;
+    /** Producer-supplied, human-readable — the underlying error message, not a restatement of `reason`. */
+    readonly detail: string;
+}
+/**
+ * The unit of ingest, and the unit of invalidation.
+ *
+ * `IREdge` carries no file, so stale edges from a changed file cannot be deleted
+ * from the edge alone — and derived edges (`PROPAGATES_TO`, `CHANGES_WITH`) have
+ * no owning file at all. Rather than patch `IREdge`, which the architecture pins,
+ * invalidation lives here: the writer deletes everything previously written by
+ * `producedBy` for `sourceFiles`, then inserts, in one transaction.
+ *
+ * See DEC-015, amended by the `skippedFiles` decision below.
+ */
+export interface IRBatch {
+    readonly repo: string;
+    /**
+     * The identity scope for workspace-scoped node types (DEC-054). Absent means
+     * "this repository alone". Carried on the batch and not only on the context so
+     * that a stored batch records the scope its ids were computed under — an id
+     * cannot be re-derived from the node alone once the config has moved on.
+     */
+    readonly workspace?: string | undefined;
+    readonly commitSha: string;
+    /** `adapterId@version` — must match every node and edge in the batch. */
+    readonly producedBy: string;
+    /**
+     * Repo-relative paths this batch's nodes and edges were actually derived
+     * from — files the adapter successfully analysed. **Not** every file it
+     * attempted; a file that failed belongs in `skippedFiles` instead, never
+     * here. This is the invalidation key: a file sitting in this list falsely
+     * (because it actually failed) makes the writer treat it as re-covered and
+     * silently evict its last-known-good rows instead of disclosing the
+     * regression via `evictedFiles` — see DEC-022.
+     */
+    readonly sourceFiles: readonly string[];
+    /**
+     * Files this batch's adapter attempted but that contributed no nodes or
+     * edges, with why. Never overlaps `sourceFiles` — a file is either analysed
+     * (named there) or skipped (named here), never both. Not yet persisted
+     * durably by the writer; surfaced as an in-request disclosure only.
+     */
+    readonly skippedFiles: readonly SkippedFile[];
+    /** The level `prepare()` actually reached, not the level hoped for. */
+    readonly reachedResolution: ResolutionLevel;
+    readonly nodes: readonly IRNode[];
+    readonly edges: readonly IREdge[];
+    readonly unresolved: readonly UnresolvedRef[];
+    /**
+     * Nodes in this batch reachable from a declared cross-language namespace
+     * peer, keyed by what that peer's own source would spell to name them.
+     * Empty or absent unless this batch's adapter declares
+     * `CapabilityMatrix.crossLanguageNamespace`. See DEC-161.
+     */
+    readonly crossLanguageDeclarations?: readonly CrossLanguageDeclaration[];
+}
+//# sourceMappingURL=ir.d.ts.map

package/dist/ir.d.ts.map

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

package/dist/ir.js

@@ -0,0 +1,76 @@
+/**
+ * The Canonical IR — the boundary every language reaches the graph through.
+ *
+ * Nothing above this boundary may name a language (architecture principle 7).
+ * `language` is carried as provenance so findings can be reported honestly; it is
+ * never branched on. The boundary lint enforces that mechanically.
+ */
+export const RESOLUTION_LEVELS = [0, 1, 2, 3, 4];
+/**
+ * The closed set `attrs.refusalClass` may hold on an `UnresolvedRef`.
+ *
+ * Producer-declared, never inferred from `reason`'s prose — a text/name
+ * heuristic over a free-text field is exactly the guess rule 3 bans, and
+ * `reason` is reworded by producers without the underlying question changing
+ * (`packages/core/src/query/unresolved.ts`'s own header is the measured
+ * account of that failure). Assigned only after the producer's own
+ * config-resolution pass has had a chance to answer the row from a source
+ * the repo already contains — see `UnresolvedRef.attrs`'s doc.
+ *
+ * - `"value-unknown"` — the row names something whose *value* the reader does
+ *   not statically know AND does not find in any config source it reads (an
+ *   env var with no matching `.env`/deploy-config entry). One human sentence
+ *   can resolve it, and — because matching is exact-string on
+ *   `(repo, blockedBy)` — the same sentence resolves every row in that repo
+ *   sharing the identical `attrs.blockedBy` (DEC-223 §3). This is the class
+ *   `blockedBy` was built for, and the only one a question queue may surface.
+ * - `"capability-gap"` — the reader cannot parse or resolve this shape at
+ *   all: an enum-dispatched verb, a path pattern it does not trace, a
+ *   language construct with no extractor yet. No sentence answers this —
+ *   only code does — and it must never reach a question queue. Measured: 92
+ *   of 95 censused C#/Java refusal rows are this class, not `value-unknown`.
+ * - `"out-of-scope"` — the reference resolved correctly to something outside
+ *   this workspace (a third-party host, another team's service) and was
+ *   filed as a refusal anyway. Correct information sitting in the wrong
+ *   ledger, not a gap and not askable either.
+ * - `"varies-per-call"` — the blocked value is not fixed anywhere to ask
+ *   about: a caller-supplied prop, a function parameter, a request-scoped
+ *   value that is, by design, different on every call (`FileViewerModal`'s
+ *   `url` prop; an upload helper's destination argument). Distinct from
+ *   `"value-unknown"` on purpose — that class means *a* fixed value exists
+ *   and nobody has stated it yet; this class means no single value exists to
+ *   state. Asking a human "what is `url`?" here is a category error, not an
+ *   unanswered question, and folding this into `"value-unknown"` behind a
+ *   flag would let a consumer that forgets to check the flag put an
+ *   unanswerable row in front of someone anyway — the same failure a missing
+ *   class was already found to cause once (see the measured C#/Java case
+ *   below). A dedicated class makes the omission a type error instead.
+ *
+ * **Absent means unclassified, not `"value-unknown"`.** A consumer building a
+ * question queue from this ledger must treat an unset `refusalClass` as
+ * not-askable — defaulting unset to askable is exactly how an unaudited row
+ * would reach a user as a question nobody vetted.
+ *
+ * This split is proposed from measured censuses across two cycles, not
+ * settled — whether `"out-of-scope"` belongs in this ledger at all, rather
+ * than being a class within it, is an open question for whoever reviews this
+ * contract next, not decided here.
+ */
+export const UNRESOLVED_REF_CLASSES = [
+    "value-unknown",
+    "capability-gap",
+    "out-of-scope",
+    "varies-per-call",
+];
+/**
+ * Why a file this batch's adapter attempted contributed no nodes or edges.
+ *
+ * Distinct from `UnresolvedRef` — that ledger is a reference the adapter *saw*
+ * and could not resolve to a node; this is a file the adapter could not read
+ * or parse at all, so it never got the chance to see anything in it. Mirrors
+ * `ParseFailure` (`@descryhq-wq/adapter-treesitter`) rather than inventing new
+ * vocabulary, since that shape is already what most producers compute — this
+ * field just gives it somewhere to go instead of dead-ending on `session`.
+ */
+export const SKIP_REASONS = ["too-large", "unreadable", "grammar-error", "other"];
+//# sourceMappingURL=ir.js.map

package/dist/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.js","sourceRoot":"","sources":["../src/ir.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoBH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAU,CAAC;AA2H1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,eAAe;IACf,gBAAgB;IAChB,cAAc;IACd,iBAAiB;CACT,CAAC;AAuGX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,OAAO,CAAU,CAAC"}

package/dist/model-tables.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `DATABASE_TABLE`/`DATABASE_COLUMN` from a `MODEL`'s own mapped shape —
+ * DEC-240's Option 2.
+ *
+ * `adapter-sql` is the only producer of these two types until now, reading
+ * `*.sql` DDL. A Python (or, later, Java/C#) stack that maps its tables
+ * through an ORM and never checks in a migration file has no producer at
+ * all — 17 real tables on the stack this was measured against, zero
+ * `DATABASE_TABLE` nodes. DEC-240 ruled that the fix is not "teach
+ * `adapter-python`'s `orm.ts` to mint these too": a language adapter that did
+ * would also have to decide Django's/JPA's/EF Core's own implicit
+ * table-naming convention (app label + lowercased model name, a class name,
+ * a pluralisation rule) to cover the common case where no explicit table
+ * name is written — three adapters each independently inventing, or
+ * independently refusing, the same class of naming inference is three
+ * chances to disagree on the one byte that has to be identical for a join to
+ * happen at all. So the naming judgement — explicit name or refuse, never
+ * infer — lives here instead, once, and every adapter calls this function
+ * at its own emit time rather than re-deriving the rule.
+ *
+ * ## The part DEC-240's own ruling did not check, and the fix could not
+ * ship correctly without
+ *
+ * `nodeId` hashes `[scope, language, kind, qualifiedSymbolPath]` for every
+ * node type **except** the three in `FILELESS_NODE_TYPES` — and
+ * `DATABASE_TABLE`/`DATABASE_COLUMN` are not in that list. `adapter-sql`
+ * already hashes its own nodes with `language: "sql"`. A second producer
+ * hashing with its own language — `"python"`, later `"java"`, `"csharp"` —
+ * would mint a *different* id for the same real table than every other
+ * producer, and DEC-054's whole point (a Python `DATABASE_COLUMN` and a
+ * TypeScript `COMPONENT` meeting through one `API_ENDPOINT`) fails silently
+ * the identical way DEC-055 already found once: everything resolves,
+ * nothing errors, and the join returns nothing. So this function — and, to
+ * match it, `adapter-sql`'s own two call sites — hash with `language: null`
+ * unconditionally.
+ *
+ * **The emitted node's own `language` field is `null` too, not the real
+ * per-producer language.** The first cut of this function kept the real
+ * language there ("only the identity hash has to be language-blind, not the
+ * metadata") and that was wrong: the graph builder's collision detector
+ * (`identityFingerprint`, `packages/core/src/graph/merge.ts`) compares
+ * `[type, language]` for any two nodes that land on one id, precisely to
+ * catch two *different* things sharing an id by accident (DEC-024). A real
+ * per-producer language on this field means two genuine producers of the
+ * *same* table — a Python ORM and the `*.sql` DDL for it, this function's own
+ * motivating case — always disagree on `language` and always trip that
+ * detector, discarding one side's `DATABASE_COLUMN`s outright. `origin.language`
+ * is kept on {@link ModelTableOrigin} only as caller-supplied provenance for
+ * future use (e.g. `attrs`); it is not echoed onto the node. Per-producer
+ * provenance is still recoverable after a real merge through the node's
+ * `attrs.corroboratedBy`, the same mechanism every other cross-producer merge
+ * in this project already uses instead of a scalar field.
+ *
+ * `schema` defaults to `"public"` when a shape names none, matching
+ * `adapter-sql`'s own `DEFAULT_SCHEMA` — duplicated as a literal because
+ * `@descry/ir` cannot depend on an adapter package to import the constant.
+ * A model that maps to a non-default schema and never says so joins nothing
+ * either, the same silent-refusal shape `tableOf()` already accepts for an
+ * implicit table name.
+ */
+import { type IdentityScope } from "./identity.ts";
+import type { IRNode, ResolutionLevel } from "./ir.ts";
+/** Matches `adapter-sql`'s own `DEFAULT_SCHEMA` (`packages/adapter-sql` in `descry-adapters`). */
+export declare const DEFAULT_MODEL_SCHEMA = "public";
+export interface ModelFieldShape {
+    readonly name: string;
+    readonly nullable: boolean;
+    /**
+     * The database column's own name, where the mapping states one explicitly
+     * and it differs from `name` — TypeORM's `@Column({ name: "..." })` is the
+     * first producer of this, mapping a camelCase property to a snake_case
+     * column the way real TypeScript ORM code commonly does. Defaults to
+     * `name` when absent, the same "explicit or refuse, never guess" rule
+     * this file's header already holds table names to: read, never derived by
+     * a naming-convention rule this function does not own.
+     */
+    readonly columnName?: string | undefined;
+}
+/**
+ * The mapped shape a `MODEL`'s own extractor already produced — `orm.ts`'s
+ * `OrmShape` and its future JPA/EF Core siblings all carry exactly this:
+ * a table name where the source wrote one explicitly, `null` where it did
+ * not, and the fields that shape maps.
+ */
+export interface ModelTableShape {
+    /** `null` when the source names no explicit table. Refused below, never guessed. */
+    readonly table: string | null;
+    readonly fields: readonly ModelFieldShape[];
+    /** Explicit schema, where the source states one. Defaults to `DEFAULT_MODEL_SCHEMA`. */
+    readonly schema?: string | undefined;
+}
+export interface ModelTableOrigin {
+    readonly file: string;
+    readonly line: number;
+    readonly producedBy: string;
+    readonly resolution: ResolutionLevel;
+    /**
+     * The emitting adapter's own language. Carried on neither the node nor the
+     * id — see this file's header for why the node's `language` field is `null`
+     * too, not just the hash. Kept on this type as caller-supplied provenance
+     * for possible future use.
+     */
+    readonly language: string;
+}
+/**
+ * `DATABASE_TABLE` plus one `DATABASE_COLUMN` per mapped field, or `[]` when
+ * `shape.table` is `null` — the disclosed refusal `tableOf()` already makes
+ * for an implicit table name, carried through rather than re-decided here.
+ */
+export declare function databaseTableNodesFromModel(scope: IdentityScope, shape: ModelTableShape, origin: ModelTableOrigin): readonly IRNode[];
+//# sourceMappingURL=model-tables.d.ts.map

package/dist/model-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-tables.d.ts","sourceRoot":"","sources":["../src/model-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEvD,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,gBAAgB,GACvB,SAAS,MAAM,EAAE,CAmCnB"}