Skip to content
seampact

6. Origins and derivedFrom

interface Origin { api?: string; layer: 'api' | 'shared' | 'base' | 'core' | 'workspace' | `pack:${string}`; pointer: string }   // api: set on a copy from another api
interface DerivedFrom { derivation: DerivationId; from: Origin[] }
  • pointer is a JSON Pointer into the merged authoring tree of its layer: /surfaces/app/routes/channels/member/routes/tasks/member/routes/assign, /rights/tasks.update, /conventions/idempotency/header. It names a logical position, never a file, so moving content between files leaves it unchanged (ADR 0002 byte-identity rule).
  • Every declared element has an origin. Every inherited setting on an operation carries the origin of the node that set it (FR-2, SCN-003).
  • layer is closed, the one exception to the open enums of ADR 0005 section 3: the compiler derives a layer kind from it, and an unknown layer has no meaning for any reader. workspace locates a diagnostic on workspace.yaml only; no IR element carries it. pack:<name> takes no #, so the side-table key <layer>#<pointer> (section 11) stays unambiguous.
  • core marks a declaration the compiler supplies itself, read from no file (amendment 2026-10-13, irRevision 2): the default codes of ADR 0006 section 6, the params schemas of those codes, ApiSchemaInvalidIssue and ApiEmptyBody (section 13), and the default format bare when no layer declares it. Its pointer is the pointer the declaration would have if the YAML the ADRs give for it were a layer file: /formats/bare (ADR 0002 section 13), /errors/api.rate_limited for a default code and /errors/api.rate_limited/params for its params schema, /errors/api.schema_invalid/params/issues/items for ApiSchemaInvalidIssue (ADR 0006 section 6, written as params are), /schemas/ApiEmptyBody (section 13), and a position below one as an authored member is named. Invariant ir.origin.core checks the entry it starts with only: /formats/<id>, /errors/<code> or /schemas/<id>, present in the document unless api is set. A core origin has no side-table entry (section 11): a diagnostic about a core element is located at the binding or the use that pulled it in. Neither workspace nor core is the layer of a raw tree.
  • An element a relay route copies from another api (ADR 0002 section 7) keeps its origin in that api, with api naming it; the location is found through that api’s side table, or the pinned bundle’s sources.
  • Every derived element carries derivedFrom: the derivation id from the derivation table (ADR 0006) and the origins of the declarations that caused it, for example { derivation: 'csrf.cookieWrite', from: [/identities/user, /schemes/sessionCookie] }. A test walks the IR and fails on a derived element without it (SCN-011, CHK-045).