@untangle-code/context-artifacts 0.0.0-stage → 0.1.1

package/src/coverage.ts

@@ -0,0 +1,336 @@
+/**
+ * Skip ledger (docs/BUILD_PLAN.md §12 E4: "KEIN stilles Ueberspringen von
+ * Inhalt — Skip-Ledger mit Grund").
+ *
+ * `ArtifactChunk`/`ArtifactAdapter` (architecture.md §20, frozen in
+ * `@untangle-code/domain`) carry no ledger field of their own — chunk
+ * ranges are the only signal a caller has about what was turned into a
+ * searchable chunk. `buildArtifactSkipLedger()` is this package's answer to
+ * E4 within that contract: given a document and the chunks an adapter
+ * produced for it, it finds every byte range NOT covered by any chunk and
+ * returns it as a labeled entry, so a caller (indexer/CLI) can log or
+ * surface "artifact X, bytes N..M were not turned into a chunk, because
+ * Y" — visibly, with a reason, never silently.
+ *
+ * A gap is not automatically a defect: whitespace between two SQL
+ * statements, or a comment line between two Terraform blocks, is expected
+ * and labeled `"whitespace_or_comment"`. A gap that still contains
+ * non-trivial content is labeled `"unclassified_content"` — a signal that
+ * an adapter's section boundaries missed something real.
+ *
+ * Byte coverage alone is BLIND to one real defect class (found in review of
+ * WP-81): an adapter can produce chunks whose union of byte ranges looks
+ * complete while a real section's identity was still lost — e.g. two SQL
+ * statements sharing one physical line, where a broken span computation
+ * attributed BOTH statements' bytes to the first statement's chunk and then
+ * emitted a second, byte-EMPTY chunk for the one that lost its own range.
+ * That second chunk carries no gap (there are no uncovered bytes left to
+ * report) yet is definitive proof that the adapter detected a section
+ * boundary and then failed to capture anything for it — a section was
+ * found, not classified.
+ *
+ * This module cannot re-parse an arbitrary format to notice that kind of
+ * loss (coverage.ts is intentionally format-agnostic — it only ever sees
+ * `ArtifactChunk[]`, never an adapter's own grammar). What it CAN check,
+ * generically and with zero false positives, is the structural invariant
+ * every legitimate chunk must satisfy: a non-empty, non-inverted byte range
+ * (`range.endByte > range.startByte`), and — when two chunks claim the
+ * EXACT same byte range — agreement on what that range even is (same
+ * `kind`+`title`; protobuf's intentionally nested service/RPC overlap never
+ * trips this, since an RPC's range is a strict sub-range of its service's,
+ * never byte-identical to it). Either violation is reported as
+ * `"semantic_loss"`: content IS covered by some chunk, but a section the
+ * adapter itself tried to carve out was not actually captured or was
+ * captured twice with conflicting identities.
+ *
+ * WP-118 fand die dritte Blindstelle derselben Familie: nichts fehlt,
+ * nichts ist leer, nichts überlappt — aber ein Fragment ist MITTEN DURCH
+ * ein Konstrukt geschnitten (die SQL-Zerlegung zerriss ein Statement an
+ * einem Semikolon INNERHALB einer Zeichenkette). Das kann dieses Modul
+ * nicht selbst erkennen, weil ihm dafür die Konventionen des Formats
+ * fehlen. Es nimmt sie deshalb als Rückruf entgegen:
+ * `buildArtifactSkipLedger(document, chunks, { checkPlausibility })`
+ * meldet jedes so beanstandete Fragment als `"implausible_fragment"`.
+ * Die Adapter reichen ihre eigene Prüfung über
+ * `adapters/shared.ts::buildChunksReportingSkips` herein, damit auch das
+ * keine Bringschuld des Aufrufers wird (E4).
+ */
+import type { ArtifactChunk, ArtifactDocument, SourceRange } from "@untangle-code/domain";
+
+import { buildLineIndex, lineNumberForByte, type LineIndex } from "./text/line-index.js";
+
+export type ArtifactSkipReason =
+  "whitespace_or_comment" | "unclassified_content" | "semantic_loss" | "implausible_fragment";
+
+export interface ArtifactSkipLedgerEntry {
+  artifactName: string;
+  /** "/"-normalized document path. */
+  path: string;
+  range: SourceRange;
+  reason: ArtifactSkipReason;
+  /** First 200 chars of the skipped content, for a human reviewing the ledger. */
+  contentPreview: string;
+}
+
+/**
+ * Callback invoked with the actionable (non-`"whitespace_or_comment"`)
+ * entries of a document's skip ledger, from the NORMAL `chunk()` path (see
+ * `adapters/shared.ts`'s `buildChunksReportingSkips` — every built-in
+ * adapter's `chunk()` goes through it, so this fires without a caller ever
+ * having to call `buildArtifactSkipLedger` separately, BUILD_PLAN §12 E4).
+ */
+export type SkipLedgerReporter = (
+  entries: readonly ArtifactSkipLedgerEntry[],
+  document: ArtifactDocument,
+) => void;
+
+/**
+ * Default `SkipLedgerReporter`: one JSON-lines-shaped warning per entry on
+ * `stderr`. Deliberately dependency-free (no `@untangle-code/observability`
+ * `Logger` — that requires an injected `Clock` and isn't available to a
+ * bare `create*Adapter()` factory call) so a loss is visible out of the box;
+ * a caller with a real structured logger passes its own `onSkipLedgerGap`
+ * to any `create*Adapter()`/`createArtifactAdapterRegistry()` instead.
+ */
+export const defaultSkipLedgerReporter: SkipLedgerReporter = (entries, document) => {
+  for (const entry of entries) {
+    process.stderr.write(
+      `${JSON.stringify({
+        level: "warn",
+        event: "context_artifact_skip_ledger_gap",
+        artifactName: document.artifactName,
+        path: entry.path,
+        range: entry.range,
+        reason: entry.reason,
+        contentPreview: entry.contentPreview,
+      })}\n`,
+    );
+  }
+};
+
+const PREVIEW_LENGTH = 200;
+
+/**
+ * Strips full-line `#`/`--`/`//` comments and any `/* *\/` block comment
+ * (which may itself span several lines — stripped whole, before the
+ * per-line check, precisely so a gap that is JUST a multi-line block
+ * comment — e.g. between two Terraform resources — is recognized as
+ * benign) so a comment-only gap is classified `"whitespace_or_comment"`,
+ * never `"unclassified_content"`.
+ */
+function isWhitespaceOrCommentOnly(text: string): boolean {
+  const withoutBlockComments = text.replace(/\/\*[\s\S]*?\*\//g, "");
+  return withoutBlockComments.split("\n").every((line) => /^\s*(#.*|--.*|\/\/.*)?\s*$/.test(line));
+}
+
+function classify(content: string): ArtifactSkipReason {
+  return isWhitespaceOrCommentOnly(content) ? "whitespace_or_comment" : "unclassified_content";
+}
+
+/**
+ * Prüft EIN fertiges Fragment auf Sinnhaftigkeit und liefert bei einem
+ * Befund den Begründungstext, sonst `undefined` (WP-118).
+ *
+ * Byte-Abdeckung beantwortet nur „fehlt etwas?"; sie ist blind dafür, ob
+ * ein Fragment an einer sinnvollen Stelle endet. Genau diese zweite Frage
+ * kann `coverage.ts` nicht selbst beantworten — sie braucht die
+ * Konventionen des jeweiligen Formats. Der zuständige Adapter reicht sie
+ * deshalb als Funktion herein (`adapters/sql.ts`, `adapters/protobuf.ts`,
+ * `adapters/terraform.ts` nutzen dafür `text/delimiter-balance.ts`),
+ * während dieses Modul format-agnostisch bleibt.
+ */
+export type ChunkPlausibilityCheck = (chunk: ArtifactChunk) => string | undefined;
+
+export interface ArtifactSkipLedgerOptions {
+  /** Siehe {@link ChunkPlausibilityCheck}. Ohne diese Option verhält sich der Ledger wie vor WP-118. */
+  readonly checkPlausibility?: ChunkPlausibilityCheck;
+}
+
+/**
+ * Finds every byte range of `document.content` not covered by any of
+ * `chunks`' ranges and returns one labeled ledger entry per gap.
+ *
+ * Overlapping/out-of-order chunk ranges (e.g. Protobuf's intentionally
+ * overlapping service/RPC chunks, see the protobuf adapter's
+ * "Entscheidungen" entry) are handled correctly: ranges are merged before
+ * gaps are computed, so an RPC chunk nested inside its service chunk never
+ * produces a spurious gap either side of it.
+ */
+export function buildArtifactSkipLedger(
+  document: ArtifactDocument,
+  chunks: readonly ArtifactChunk[],
+  options: ArtifactSkipLedgerOptions = {},
+): ArtifactSkipLedgerEntry[] {
+  const index = buildLineIndex(document.content);
+  const buffer = index.buffer;
+  const totalBytes = buffer.length;
+
+  const semanticLossEntries = findSemanticLossEntries(document, index, chunks);
+  const plausibilityEntries = findImplausibleFragmentEntries(
+    document,
+    chunks,
+    options.checkPlausibility,
+  );
+
+  if (totalBytes === 0) {
+    return [...semanticLossEntries, ...plausibilityEntries];
+  }
+
+  const sortedSpans = chunks
+    .map((chunk): [number, number] => [chunk.range.startByte, chunk.range.endByte])
+    .filter(([start, end]) => end > start)
+    .sort((a, b) => a[0] - b[0]);
+
+  const merged: [number, number][] = [];
+  for (const [start, end] of sortedSpans) {
+    const last = merged.at(-1);
+    if (last !== undefined && start <= last[1]) {
+      last[1] = Math.max(last[1], end);
+    } else {
+      merged.push([start, end]);
+    }
+  }
+
+  const gapEntries: ArtifactSkipLedgerEntry[] = [];
+  let cursor = 0;
+  for (const [start, end] of merged) {
+    if (start > cursor) {
+      gapEntries.push(buildEntry(document, index, cursor, start));
+    }
+    cursor = Math.max(cursor, end);
+  }
+  if (cursor < totalBytes) {
+    gapEntries.push(buildEntry(document, index, cursor, totalBytes));
+  }
+
+  // Byte gaps first (in document order), semantic-loss findings after — both
+  // are real E4-relevant findings, but a gap is "content with no chunk at
+  // all" while semantic loss is "a chunk exists but its own identity is
+  // broken", a useful distinction for a human scanning the ledger.
+  return [...gapEntries, ...semanticLossEntries, ...plausibilityEntries];
+}
+
+/**
+ * Baut je Chunk, den `check` als unplausibel meldet, einen Ledger-Eintrag
+ * mit Grund `"implausible_fragment"`. Ohne `check` ist das Ergebnis leer —
+ * ein Aufrufer, der `buildArtifactSkipLedger` direkt und ohne Optionen
+ * benutzt, sieht exakt dasselbe Verhalten wie vor WP-118.
+ */
+function findImplausibleFragmentEntries(
+  document: ArtifactDocument,
+  chunks: readonly ArtifactChunk[],
+  check: ChunkPlausibilityCheck | undefined,
+): ArtifactSkipLedgerEntry[] {
+  if (check === undefined) return [];
+  const entries: ArtifactSkipLedgerEntry[] = [];
+  for (const chunk of chunks) {
+    const detail = check(chunk);
+    if (detail === undefined) continue;
+    entries.push({
+      artifactName: document.artifactName,
+      path: document.path,
+      range: chunk.range,
+      reason: "implausible_fragment",
+      contentPreview: `${detail} (kind="${chunk.kind}" title=${
+        chunk.title === undefined ? "(none)" : JSON.stringify(chunk.title)
+      })`.slice(0, PREVIEW_LENGTH),
+    });
+  }
+  return entries;
+}
+
+function buildEntry(
+  document: ArtifactDocument,
+  index: LineIndex,
+  startByte: number,
+  endByte: number,
+): ArtifactSkipLedgerEntry {
+  const gapContent = index.buffer.toString("utf8", startByte, endByte);
+  const startLine = lineNumberForByte(index, startByte);
+  const endLine = endByte > startByte ? lineNumberForByte(index, endByte - 1) : startLine;
+  return {
+    artifactName: document.artifactName,
+    path: document.path,
+    range: { startLine, endLine, startByte, endByte },
+    reason: classify(gapContent),
+    contentPreview: gapContent.slice(0, PREVIEW_LENGTH),
+  };
+}
+
+/**
+ * See the module doc's "Byte coverage alone is BLIND..." note: finds chunks
+ * that violate the structural invariant every legitimate `ArtifactChunk`
+ * must satisfy, independent of any particular format's grammar.
+ *
+ * 1. A chunk whose own range is empty or inverted (`endByte <= startByte`)
+ *    — an adapter tried to carve out a section and captured zero bytes for
+ *    it. `chunk.content`/`contentHash` are trusted as the preview source
+ *    here (not re-sliced from `document`) precisely because the chunk's own
+ *    declared range cannot be trusted to slice anything meaningful.
+ * 2. Two (or more) chunks that claim the EXACT same byte range but disagree
+ *    on `kind`/`title` — the same bytes were classified twice, differently.
+ *    Deliberately exact-range-only: a legitimately nested overlap (e.g. a
+ *    Protobuf RPC inside its service) never has an identical range to its
+ *    parent, so this never fires on that intentional case.
+ */
+function findSemanticLossEntries(
+  document: ArtifactDocument,
+  index: LineIndex,
+  chunks: readonly ArtifactChunk[],
+): ArtifactSkipLedgerEntry[] {
+  const entries: ArtifactSkipLedgerEntry[] = [];
+
+  for (const chunk of chunks) {
+    if (chunk.range.endByte > chunk.range.startByte) continue;
+    entries.push({
+      artifactName: document.artifactName,
+      path: document.path,
+      range: chunk.range,
+      reason: "semantic_loss",
+      contentPreview: `degenerate chunk: kind="${chunk.kind}" title=${
+        chunk.title === undefined ? "(none)" : JSON.stringify(chunk.title)
+      } produced an empty/inverted range [${chunk.range.startByte}, ${chunk.range.endByte}) — a section boundary was found but no content was captured for it`.slice(
+        0,
+        PREVIEW_LENGTH,
+      ),
+    });
+  }
+
+  const byRange = new Map<string, ArtifactChunk[]>();
+  for (const chunk of chunks) {
+    if (chunk.range.endByte <= chunk.range.startByte) continue; // already reported above
+    const key = `${chunk.range.startByte}:${chunk.range.endByte}`;
+    const group = byRange.get(key);
+    if (group) {
+      group.push(chunk);
+    } else {
+      byRange.set(key, [chunk]);
+    }
+  }
+  for (const group of byRange.values()) {
+    if (group.length < 2) continue;
+    const identities = new Set(group.map((chunk) => `${chunk.kind}${chunk.title ?? ""}`));
+    if (identities.size < 2) continue; // same range, same identity: not a conflict
+    const first = group[0]!;
+    const startLine = lineNumberForByte(index, first.range.startByte);
+    const endLine =
+      first.range.endByte > first.range.startByte
+        ? lineNumberForByte(index, first.range.endByte - 1)
+        : startLine;
+    entries.push({
+      artifactName: document.artifactName,
+      path: document.path,
+      range: { startLine, endLine, startByte: first.range.startByte, endByte: first.range.endByte },
+      reason: "semantic_loss",
+      contentPreview:
+        `conflicting classification: ${group.length} chunks share byte range [${first.range.startByte}, ${
+          first.range.endByte
+        }) with different identities: ${group.map((chunk) => `kind="${chunk.kind}" title=${chunk.title ?? "(none)"}`).join(" vs. ")}`.slice(
+          0,
+          PREVIEW_LENGTH,
+        ),
+    });
+  }
+
+  return entries;
+}

package/src/ids.ts

@@ -0,0 +1,57 @@
+/**
+ * Deterministic `ArtifactChunk.chunkId` derivation.
+ *
+ * `packages/domain/src/identity.ts` defines one `buildXId` helper per ID
+ * kind from spec.md §5, but `ArtifactChunk` (architecture.md §20) is an
+ * Untangle-decision shape with no spec.md §5 identity formula of its own —
+ * domain deliberately leaves it to this package (see README
+ * "Entscheidungen"). This mirrors `buildChunkId`'s approach exactly: a
+ * `uuidv5` under the shared Untangle namespace, over a kind-tagged,
+ * unit-separator-joined component list, so a re-chunk of unchanged input
+ * reproduces the exact same id (stable across index runs) while chunk ids
+ * from different artifacts/documents/kinds can never collide.
+ *
+ * No `Date.now()`/`Math.random()` anywhere — pure function of its inputs
+ * (rule 5).
+ */
+import { ID_COMPONENT_SEPARATOR, uuidv5 } from "@untangle-code/domain";
+
+export interface ArtifactChunkIdInput {
+  artifactName: string;
+  /** "/"-normalized document path (as carried on `ArtifactDocument.path`). */
+  documentPath: string;
+  /** Semantic chunk kind, e.g. "sql_table", "markdown_section". */
+  kind: string;
+  /** 0-based position among this document's chunks, so equal-kind chunks never collide. */
+  ordinal: number;
+}
+
+function assertNonEmpty(value: string, label: string): void {
+  if (value.length === 0) {
+    throw new Error(`buildArtifactChunkId: "${label}" must not be empty`);
+  }
+  if (value.includes(ID_COMPONENT_SEPARATOR)) {
+    throw new Error(`buildArtifactChunkId: "${label}" must not contain the U+001F separator`);
+  }
+}
+
+/** Deterministic `ArtifactChunk.chunkId` (see module doc). */
+export function buildArtifactChunkId(input: ArtifactChunkIdInput): string {
+  assertNonEmpty(input.artifactName, "artifactName");
+  assertNonEmpty(input.documentPath, "documentPath");
+  assertNonEmpty(input.kind, "kind");
+  if (!Number.isInteger(input.ordinal) || input.ordinal < 0) {
+    throw new Error(
+      `buildArtifactChunkId: ordinal must be a non-negative integer, got ${input.ordinal}`,
+    );
+  }
+  return uuidv5(
+    [
+      "artifact_chunk",
+      input.artifactName,
+      input.documentPath,
+      input.kind,
+      String(input.ordinal),
+    ].join(ID_COMPONENT_SEPARATOR),
+  );
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+/**
+ * @untangle-code/context-artifacts — the ONLY public export of this
+ * package.
+ *
+ * `createArtifactAdapterRegistry()` returns an `ArtifactAdapter`
+ * (`@untangle-code/domain` `ports.ts`, architecture.md §20) that dispatches
+ * to one of the built-in format adapters — Markdown/ADR, SQL schema,
+ * OpenAPI, AsyncAPI, Protobuf, Terraform/HCL, Kubernetes YAML, Docker/
+ * Compose — or the safe generic text fallback. Individual `create*Adapter()`
+ * factories are exported too, both for direct golden-testing (one per
+ * adapter, see each `src/adapters/*.test.ts`) and so a caller who only
+ * needs one format can skip the registry entirely.
+ *
+ * Also exported: cross-artifact config validation (`validateArtifactConfigs`,
+ * spec.md §19.2's project-wide unique name requirement), staleness
+ * snapshotting (`computeArtifactStalenessSnapshot`/`isArtifactStale`,
+ * spec.md §19.2's "config hash + content hash"), and the skip ledger
+ * (`buildArtifactSkipLedger`, BUILD_PLAN §12 E4) — see README.md
+ * "Entscheidungen" for why these last two exist as this package's own
+ * derived utilities rather than domain port additions.
+ */
+export type { ArtifactAdapterRegistry, ArtifactAdapterRegistryOptions } from "./registry.js";
+export { createArtifactAdapterRegistry } from "./registry.js";
+
+export type { MarkdownAdapterOptions } from "./adapters/markdown.js";
+export { createMarkdownAdapter } from "./adapters/markdown.js";
+export type { SqlAdapterOptions, SqlDialect } from "./adapters/sql.js";
+export { createSqlAdapter, DEFAULT_SQL_DIALECT } from "./adapters/sql.js";
+export type { OpenApiAdapterOptions } from "./adapters/openapi.js";
+export { createOpenApiAdapter } from "./adapters/openapi.js";
+export type { AsyncApiAdapterOptions } from "./adapters/asyncapi.js";
+export { createAsyncApiAdapter } from "./adapters/asyncapi.js";
+export type { ProtobufAdapterOptions } from "./adapters/protobuf.js";
+export { createProtobufAdapter } from "./adapters/protobuf.js";
+export type { TerraformAdapterOptions } from "./adapters/terraform.js";
+export { createTerraformAdapter } from "./adapters/terraform.js";
+export type { KubernetesAdapterOptions } from "./adapters/kubernetes.js";
+export { createKubernetesAdapter } from "./adapters/kubernetes.js";
+export type { DockerAdapterOptions } from "./adapters/docker.js";
+export { createDockerAdapter } from "./adapters/docker.js";
+export type { TextFallbackAdapterOptions } from "./adapters/text.js";
+export { createTextFallbackAdapter, TEXT_WINDOW_LINES } from "./adapters/text.js";
+
+export { validateArtifactConfigs } from "./config-validation.js";
+
+export type { ArtifactStalenessSnapshot } from "./staleness.js";
+export {
+  computeArtifactConfigHash,
+  computeArtifactContentHash,
+  computeArtifactStalenessSnapshot,
+  isArtifactStale,
+} from "./staleness.js";
+
+export type {
+  ArtifactSkipLedgerEntry,
+  ArtifactSkipLedgerOptions,
+  ArtifactSkipReason,
+  ChunkPlausibilityCheck,
+  SkipLedgerReporter,
+} from "./coverage.js";
+export { buildArtifactSkipLedger, defaultSkipLedgerReporter } from "./coverage.js";
+
+export { buildArtifactChunkId } from "./ids.js";
+export type { ArtifactChunkIdInput } from "./ids.js";
+
+// Line-indexing primitives, exposed for a custom adapter registered via
+// `createArtifactAdapterRegistry([...])` that wants the same byte-accurate
+// SourceRange conventions this package's own adapters use.
+export type { LineIndex } from "./text/line-index.js";
+export {
+  buildLineIndex,
+  rangeForLines,
+  sliceBytes,
+  sliceLines,
+  splitLines,
+} from "./text/line-index.js";
+
+// Plausibilitätsprüfung geschnittener Fragmente (WP-118), damit ein eigener
+// Adapter dieselbe E4-Absicherung bekommt wie die eingebauten.
+export type {
+  BlockCommentRule,
+  BracketRule,
+  DelimiterImbalance,
+  DelimiterImbalanceKind,
+  DelimiterScanOptions,
+  HeredocStyle,
+  QuoteRule,
+} from "./text/delimiter-balance.js";
+export { describeDelimiterImbalances, findDelimiterImbalances } from "./text/delimiter-balance.js";
+
+// The YAML subset parser, exposed for the same reason (e.g. a custom
+// Kubernetes CRD-aware adapter built on top of this package's parser).
+export type {
+  YamlDocumentSpan,
+  YamlMapEntry,
+  YamlNode,
+  YamlScalarValue,
+} from "./text/yaml-lite.js";
+export {
+  YamlParseError,
+  mapGet,
+  parseYamlNode,
+  scalarString,
+  splitYamlDocuments,
+} from "./text/yaml-lite.js";

package/src/registry.ts

@@ -0,0 +1,155 @@
+/**
+ * `ArtifactAdapterRegistry` (architecture.md §20) — a composite
+ * `ArtifactAdapter` that dispatches to the right concrete format adapter
+ * and NEVER fails to produce a result: the generic text-fallback adapter
+ * is always registered last as a catch-all, so `read()`/`chunk()` always
+ * succeed for every file (spec.md §19.2's "sicherer Text-Fallback";
+ * rule 4 / BUILD_PLAN §12 E4 — nothing is silently unindexable).
+ *
+ * Dispatch order (auto-detection priority, see each adapter's own
+ * `supports()` for its exact rule):
+ *
+ * 1. OpenAPI / AsyncAPI  — filename-hint + yaml/json extension
+ * 2. Docker / Compose    — `Dockerfile*` / `(docker-)compose.y*ml` filename
+ * 3. Kubernetes          — any other `.yaml`/`.yml`
+ * 4. Markdown, SQL, Protobuf, Terraform — unambiguous extensions
+ * 5. Text fallback       — catch-all
+ *
+ * `chunk()`/`links()` reuse the SAME per-adapter `supports()` rule, called
+ * with `(document.type, document.path)` instead of the config's declared
+ * type — every non-"text" `ArtifactDocument.type` is itself one adapter's
+ * own literal (`"sql"`, `"openapi"`, …), so this always resolves
+ * correctly without needing a second identity mechanism; the Docker
+ * adapter's `supports()` additionally recognizes `type === "text"` for
+ * exactly this reason (its documents carry type `"text"`, see `docker.ts`).
+ */
+import type {
+  ArtifactAdapter,
+  ArtifactChunk,
+  ArtifactDocument,
+  ArtifactInput,
+  ArtifactLink,
+  PortCallOptions,
+} from "@untangle-code/domain";
+import { jobCancelledError } from "@untangle-code/observability";
+
+import { createAsyncApiAdapter } from "./adapters/asyncapi.js";
+import { createDockerAdapter } from "./adapters/docker.js";
+import { createKubernetesAdapter } from "./adapters/kubernetes.js";
+import { createMarkdownAdapter } from "./adapters/markdown.js";
+import { createOpenApiAdapter } from "./adapters/openapi.js";
+import { createProtobufAdapter } from "./adapters/protobuf.js";
+import type { SkipLedgerReporter } from "./adapters/shared.js";
+import { createSqlAdapter } from "./adapters/sql.js";
+import { createTerraformAdapter } from "./adapters/terraform.js";
+import { createTextFallbackAdapter } from "./adapters/text.js";
+
+export interface ArtifactAdapterRegistry extends ArtifactAdapter {
+  /** Registers an additional adapter with LOWER priority than every built-in one (inserted just before the text fallback). */
+  register(adapter: ArtifactAdapter): void;
+  listAdapters(): readonly ArtifactAdapter[];
+}
+
+type ArtifactFile = ArtifactInput["files"][number];
+
+class DefaultArtifactAdapterRegistry implements ArtifactAdapterRegistry {
+  private readonly textFallback: ArtifactAdapter;
+  private adapters: ArtifactAdapter[];
+
+  constructor(builtins: ArtifactAdapter[], textFallback: ArtifactAdapter) {
+    this.textFallback = textFallback;
+    this.adapters = [...builtins, textFallback];
+  }
+
+  register(adapter: ArtifactAdapter): void {
+    // Keep the text fallback last no matter when custom adapters are added.
+    const withoutFallback = this.adapters.filter((existing) => existing !== this.textFallback);
+    this.adapters = [...withoutFallback, adapter, this.textFallback];
+  }
+
+  listAdapters(): readonly ArtifactAdapter[] {
+    return [...this.adapters];
+  }
+
+  supports(type: string, path: string): boolean {
+    return this.adapters.some((adapter) => adapter.supports(type, path));
+  }
+
+  private resolve(type: string, path: string): ArtifactAdapter {
+    return this.adapters.find((adapter) => adapter.supports(type, path)) ?? this.textFallback;
+  }
+
+  async read(input: ArtifactInput, options?: PortCallOptions): Promise<ArtifactDocument[]> {
+    const declaredType = input.config.type ?? "auto";
+    const groups = new Map<ArtifactAdapter, ArtifactFile[]>();
+    for (const file of input.files) {
+      if (options?.signal?.aborted) {
+        throw jobCancelledError(`context artifact "${input.config.name}" read was aborted`, {
+          operation: "context_artifact_read",
+          context: { artifactName: input.config.name },
+        });
+      }
+      const adapter = this.resolve(declaredType, file.path);
+      const existing = groups.get(adapter);
+      if (existing) {
+        existing.push(file);
+      } else {
+        groups.set(adapter, [file]);
+      }
+    }
+
+    const documents: ArtifactDocument[] = [];
+    for (const [adapter, files] of groups) {
+      const group = await adapter.read({ config: input.config, files }, options);
+      documents.push(...group);
+    }
+    return documents;
+  }
+
+  chunk(document: ArtifactDocument): ArtifactChunk[] {
+    return this.resolve(document.type, document.path).chunk(document);
+  }
+
+  links(document: ArtifactDocument): ArtifactLink[] {
+    const adapter = this.resolve(document.type, document.path);
+    return adapter.links?.(document) ?? [];
+  }
+}
+
+export interface ArtifactAdapterRegistryOptions {
+  /**
+   * BUILD_PLAN §12 E4: overrides how every BUILT-IN adapter's `chunk()`
+   * surfaces a real skip-ledger finding (default: one stderr warning line
+   * per finding — see `coverage.ts`'s `defaultSkipLedgerReporter`). Wire in
+   * a real structured logger here once, instead of passing the same
+   * `onSkipLedgerGap` to every individual `create*Adapter()` call. Does
+   * NOT apply to `extra` adapters — those are already fully constructed
+   * `ArtifactAdapter`s by the time they reach this factory.
+   */
+  onSkipLedgerGap?: SkipLedgerReporter;
+}
+
+/**
+ * Builds a registry with every built-in format adapter registered
+ * (priority order per this module's doc comment), plus any `extra`
+ * adapters appended just before the text fallback.
+ */
+export function createArtifactAdapterRegistry(
+  extra: ArtifactAdapter[] = [],
+  options: ArtifactAdapterRegistryOptions = {},
+): ArtifactAdapterRegistry {
+  const adapterOptions =
+    options.onSkipLedgerGap === undefined ? {} : { onSkipLedgerGap: options.onSkipLedgerGap };
+  const builtins: ArtifactAdapter[] = [
+    createOpenApiAdapter(adapterOptions),
+    createAsyncApiAdapter(adapterOptions),
+    createDockerAdapter(adapterOptions),
+    createKubernetesAdapter(adapterOptions),
+    createMarkdownAdapter(adapterOptions),
+    createSqlAdapter(adapterOptions),
+    createProtobufAdapter(adapterOptions),
+    createTerraformAdapter(adapterOptions),
+    ...extra,
+  ];
+  return new DefaultArtifactAdapterRegistry(builtins, createTextFallbackAdapter(adapterOptions));
+}