@typedstandards/civic-typed-harness 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,136 @@
 Factual record of what changed per published version. Section references are
 to the Typed Standards specification unless noted otherwise.
 
+## 0.7.0 — 2026-10-15
+
+- **The seam inside the harness** ([civic-ai-tools#244](https://github.com/npstorey/civic-ai-tools/issues/244) P2).
+  `src/capture/provenance.ts` and `src/capture/data-sources.ts` import
+  nothing from `src/format/`, type-only imports included. The capture
+  builders take the vocabulary, the sixteen `civic:` term names, the source
+  registry, the fallback and skill source ids and the dataset-keyed fact as
+  required parameters.
+- **What moved.** `buildProvenanceGraph`, `ProvenanceConfig` and
+  `CIVICAITOOLS_PROVENANCE_CONFIG` moved to `src/civic/provenance.ts`;
+  `buildDataSources`, `resolveToolSource` and `DataSourceOptions` moved to
+  `src/civic/data-sources.ts`. These modules apply the civic defaults
+  (`CIVIC_VOCABULARY`, `CIVIC_SOURCE_REGISTRY`, `FALLBACK_SOURCE_ID`,
+  `civicToolSourceResolver`, `isDatasetKeyedSource`) and call the capture
+  builders. The compile-only pin `data-sources.assert.ts` moved with
+  `buildDataSources`, byte-unchanged.
+- **The API is unchanged.** The package entry exports the same names with
+  the same signatures, and the capture builders are not exported. The golden
+  suites pass with no fixture edited.
+- `src/purity.test.ts` gains the rule: a capture module imports no module from
+  outside `src/capture/`. A package import, such as
+  `@typedstandards/produce-core`, is allowed.
+
+The record fields of [ADR-0033](../../docs/adr/0033-composed-harness-record-fields.md)
+(sprint R2, H2). Signed bytes move only where one of these inputs is passed,
+where a call's source is not in the registry, and in a datHere environment
+block that no longer states two placeholders.
+
+- **Every call is attributed to its own source** (ADR-0033 §A). A call tagged
+  with a source the registry lacks was attributed to Socrata's agent — in a
+  run where Socrata made no call, an agent the graph did not contain — and is
+  now attributed to its own source's agent. An untagged span resolves by its
+  tool name, as `dataSources` already did (`ProvenanceConfig.resolver`, new,
+  default `civicToolSourceResolver`). A span neither identifies is attributed
+  to the new `UNKNOWN_SOURCE_ID` (`'unknown'`), the value the reference app
+  writes for a tool it cannot resolve; `resolveToolSource` and
+  `buildDataSources` default to it too, so an unknown call mints no
+  `dataSources` entry. `FALLBACK_SOURCE_ID` (`'socrata'`) stays exported and is
+  no longer a default for attribution. The capture builder's
+  `ProvenanceBuildConfig` gains a required `resolver`.
+- **Each call states its upstream name, alias and server** (§B): the span
+  attributes `tool.upstream_name`, `mcp.alias` and `mcp.server.id` become
+  three new terms, `civic:upstreamToolName`, `civic:sourceAlias` and
+  `civic:serverId`, appended to the tool-call activity when present.
+  `ProvenanceTerms` gains the three keys.
+- **The environment block states `temperature` and `toolDefinitions` only
+  when passed** (§C; [civic-ai-tools#240](https://github.com/npstorey/civic-ai-tools/issues/240)):
+  `buildDatHereEnvironment` takes an optional fourth argument and
+  `DatHerePolicyInput` two optional fields. Both keep their 0.6.0 key
+  positions, so passing the recorded `0` and `[]` reproduces an earlier
+  package byte for byte. Specification §8.7.1 requirement 3 is amended in
+  v0.1.11 to match.
+- **The run-time servers win** (§D; civic-ai-tools-website#495):
+  `DatHerePolicyInput.runMcpServers` is preferred over `mcpServers` and
+  `skillMcpServerUrl`; `withRunServerAddresses(registry, servers)` (new) gives
+  the graph's source agents the run's addresses.
+- **A new `org.civicaitools.composition` block** (§E;
+  civic-ai-tools-website#475): `assertedDate`, `sourcesOffered` and
+  `components`, under every content profile, emitted only when one is
+  passed. `COMPOSITION_EXTENSION_KEY`, `SOURCE_OFFERED_REASONS`,
+  `GUIDANCE_ORIGINS`, `buildCompositionExtension` and `RecordFieldError`
+  (new). A value outside the record's form is refused, never dropped.
+- **`extractRunAttributes(trace)`** (new, capture): reads `analysis.asserted_date`,
+  `analysis.mcp_servers`, `analysis.tool_definitions`,
+  `analysis.sources_offered` and `analysis.components` from the trace's root
+  span; a present attribute that does not parse throws `RunAttributeError`.
+- **`CIVICAITOOLS_TRACE_CONFIG` moved to `src/civic/trace.ts`**
+  ([civic-ai-tools#246](https://github.com/npstorey/civic-ai-tools/issues/246)),
+  re-exported under the same name. `src/purity.test.ts` gains the rule: no
+  capture module exports a value binding.
+- **The goldens.** No frozen fixture is edited, and `src/frozen-fixtures.test.ts`
+  (new) pins the sha256 of `website-golden.json` and `reference-golden.json`.
+  The website golden's derived graph moves in one field (tool-4's
+  `prov:wasAssociatedWith`), reached by a second named lift with its count
+  asserted; `span-carrying-golden.json`'s two recorded hashes are regenerated
+  with a dated note. `reference-golden.json`'s eight cases reproduce byte for
+  byte given their recorded environment values, and a new-default leg pins
+  the bytes without them.
+- `capture/data-sources.test.ts`'s "Unknown tool with no trace span defaults
+  to socrata (pre-M9.1 backward compat)" is rewritten: the tool is `unknown`.
+
+The dependency floor (sprint R2, G4).
+
+- **Dependency floor raised:** `@typedstandards/produce-core` `^0.7.0` →
+  `^0.8.0`, and the `@typedstandards/verify-core` devDependency `^0.12.0` →
+  `^0.13.0`, the version produce-core 0.8.0 resolves. Under 0.x semver
+  `^0.7.0` excludes 0.8.0, so a consumer that pins produce-core `^0.8.0`
+  would install a second copy of each core beside this package's.
+- **What the two releases bring.** produce-core 0.8.0 emits four more
+  attestation sub-types and adds `EnvelopeInput.vcsRef` and raw-bytes/v1 over
+  a BlobRef; an input that supplies none of them builds the same bytes.
+  verify-core 0.13.0 adds the `superseded` lifecycle status, the key binding
+  in `verifyLifecycleChain` and `checkAttestationNode`. The harness reads none
+  of these.
+- The lockfile resolves produce-core 0.8.0 and verify-core 0.13.0, one copy
+  each, and no other entry moves. The golden byte-compat suite passes
+  unchanged.
+- A consumer that pins produce-core 0.7.x no longer shares its copy with this
+  package.
+- **README:** the runtime-dependency line names `^0.8.0`.
+
+## 0.6.0 — 2026-09-26
+
+The list is derived from
+`git log 65e8a1d..<this release> -- packages/civic-typed-harness/` — `65e8a1d`
+is the 0.5.0 release's last commit, its dating fix. No harness source changes
+in that range.
+
+- **Dependency floor raised:** `@typedstandards/produce-core` `^0.3.0 ||
+  ^0.4.0` → `^0.7.0`, and the `@typedstandards/verify-core` devDependency
+  `^0.9.0` → `^0.12.0`, the version produce-core 0.7.0 resolves. The two move
+  together so the install holds one copy of verify-core: with only the
+  devDependency moved, produce-core 0.3.0 kept verify-core 0.9.0 and the
+  harness tests imported a second copy. The raise went to `^0.6.0` /
+  `^0.11.0` first ([civic-ai-tools#232](https://github.com/npstorey/civic-ai-tools/issues/232))
+  and was not published at that range.
+- **What the two releases bring.** verify-core 0.11.0 is the first release
+  that exports `KNOWN_TYPE_URIS`, which the hub's `check:verifier-subtype-set`
+  compares with the specification's §8.12.1 table. verify-core 0.12.0 (the
+  certificate-chain split, typedstandards#100) adds a member to
+  `ChainFailReason` and to `Rfc3161FailReason`; the harness reads neither.
+  produce-core 0.7.0 changes none of its own source.
+- The lockfile resolves produce-core 0.7.0 and verify-core 0.12.0, one copy
+  each, and no other entry moves. The golden byte-compat suite passes
+  unchanged.
+- A consumer that pins produce-core 0.3.x through 0.6.x no longer shares its
+  copy with this package: under 0.x semver `^0.7.0` excludes them.
+- **README:** the runtime-dependency line named produce-core `^0.2.0`, a range
+  this package has not declared since 0.3.0. It names `^0.7.0`.
+
 ## 0.5.0 — 2026-09-18
 
 The list is derived from

package/README.md

@@ -9,10 +9,11 @@ The civic **domain harness** for [Typed Standards](../../docs/architecture/typed
 | Module group | Modules | What it is |
 |---|---|---|
 | **`src/format/`** — the civic format-extension | `vocabulary.ts`, `sources.ts`, `dathere.ts`, `profiles.ts` | What extends the *standard*: the `civic:` JSON-LD namespace and `urn:civic-record:` id scheme (both in two eras — new emissions mint the settlement-era terms, the prior-era terms stay exported and reproducible because they are frozen inside already-signed records; spec Appendix J), the civic source registry, the datHere envelope-policy derivations (producerProfile, canonicalization rule, summary emission, environment extension), and the captureMethod vocabulary surface. |
-| **`src/capture/`** — the capture machinery | `trace.ts`, `skill-metadata.ts`, `data-sources.ts`, `provenance.ts` | What *produces* under it: the OTel `TraceBuilder`, skill-metadata extraction, data-source population, and the provenance **builder** — which imports its vocabulary from the format group and walks the trace. |
+| **`src/capture/`** — the capture machinery | `trace.ts`, `skill-metadata.ts`, `run-attributes.ts`, `data-sources.ts`, `provenance.ts` | What *produces* under it: the OTel `TraceBuilder`, skill-metadata extraction, run-attribute extraction (`extractRunAttributes`), data-source population, and the provenance **builder**, which walks the trace. Capture imports no module from outside `src/capture/`; its one import beyond it is the `@typedstandards/produce-core` package. The vocabulary, the term names, the source registry and their defaults arrive as parameters, and capture defines no deployment value (it exports no `const`). |
+| **`src/civic/`** — the civic defaults over capture | `data-sources.ts`, `provenance.ts`, `run-servers.ts`, `trace.ts` | The package's `buildDataSources`, `resolveToolSource` and `buildProvenanceGraph`, with `DataSourceOptions`, `ProvenanceConfig` and `CIVICAITOOLS_PROVENANCE_CONFIG`: they pass the format group's vocabulary, terms and registry to the capture builders and apply the civic defaults. Also `withRunServerAddresses` and the reference deployment's trace identity, `CIVICAITOOLS_TRACE_CONFIG`. |
 | **`src/rubric/`** — the adversarial rubric | `adversarial-eval-core.ts` | The civic six-criterion evaluation rubric (pure core: rubric text, pinned version hash, prompt builder, response parser). The model runner and result emission stay implementation-side. |
 
-**The internal boundary is load-bearing:** no capture module defines vocabulary, and no format-extension module walks a trace — this sentence reserves a future split of the format-extension group into its own package (a civic extension *of Typed Standards*, distinct from the civic *harness* proper) as a mechanical move rather than a re-partition. The boundary is enforced by `src/purity.test.ts`.
+**The internal boundary is load-bearing:** no capture module defines vocabulary or imports a module from outside `src/capture/` (a package import, `@typedstandards/produce-core`, is allowed), and no format-extension module walks a trace — this sentence reserves a future split of the format-extension group into its own package (a civic extension *of Typed Standards*, distinct from the civic *harness* proper) as a mechanical move rather than a re-partition. The boundary is enforced by `src/purity.test.ts`.
 
 ## Config, not constants — and required, never defaulted
 
@@ -45,17 +46,44 @@ const graph = buildProvenanceGraph(trace, input, CIVICAITOOLS_PROVENANCE_CONFIG)
 
 Likewise: `buildDatHereEnvironment` / `deriveDatHereEnvelopeFields` take `CIVICAITOOLS_ENVIRONMENT_CONFIG`, `new TraceBuilder(...)` takes `CIVICAITOOLS_TRACE_CONFIG`, and `isDatasetKeyedSource` / `displayNameForSource` / `formatDataSourcesSummary` take `CIVIC_SOURCE_REGISTRY`. The acceptance condition is encoded in `src/required-config.assert.ts`: reintroducing any of the removed defaults fails `npm run typecheck`.
 
+## What a record states about its run (0.7.0, [ADR-0033](../../docs/adr/0033-composed-harness-record-fields.md))
+
+**Every call is attributed to its own source.** A tool span's source is its `mcp.source` tag; an untagged span resolves by its tool name through the resolver (`ProvenanceConfig.resolver`, default `civicToolSourceResolver`); a span neither identifies is attributed to `UNKNOWN_SOURCE_ID` (`'unknown'`), never to Socrata. The same order holds in `dataSources[]`, where an unknown call mints no entry. A caller may still pass `fallbackSourceId` explicitly, for example `'socrata'` to reproduce an earlier record of an untagged span.
+
+**Each call states both its names, its alias and its server**, when the span carries them: `tool.upstream_name`, `mcp.alias` and `mcp.server.id` become `civic:upstreamToolName`, `civic:sourceAlias` and `civic:serverId` on the tool-call activity. `civic:toolName` stays the name the model called.
+
+**The environment block states only what is known.** `temperature` and `toolDefinitions` are emitted only when passed (`DatHerePolicyInput.temperature`, `.toolDefinitions`; spec §8.7.1 requirement 3 as amended in v0.1.11). To reproduce a package made before 0.7.0, pass the values it recorded (`temperature: 0`, `toolDefinitions: []`); its bytes come back exactly.
+
+**Run-time facts come from the trace.** The producer writes them on the trace's root span at run time, and `extractRunAttributes(trace)` returns them under the derivation's input names:
+
+| Root-span attribute (JSON text unless noted) | Input | Lands in |
+|---|---|---|
+| `analysis.asserted_date` (plain `YYYY-MM-DD`) | `assertedDate` | `extensions["org.civicaitools.composition"].assertedDate` |
+| `analysis.mcp_servers` | `runMcpServers` | `org.civicaitools.environment.mcpServers` (wins over `mcpServers` and `skillMcpServerUrl`); `withRunServerAddresses(registry, servers)` gives the graph's agents the run's addresses |
+| `analysis.tool_definitions` | `toolDefinitions` | `org.civicaitools.environment.toolDefinitions` |
+| `analysis.sources_offered` | `sourcesOffered` | `org.civicaitools.composition.sourcesOffered` |
+| `analysis.components` | `components` | `org.civicaitools.composition.components` |
+
+```ts
+const fields = deriveDatHereEnvelopeFields(
+  { model, contentProfile, summary, extensions, ...extractRunAttributes(trace) },
+  { host },
+);
+```
+
+An absent attribute is an absent field. A present attribute that does not parse is refused (`RunAttributeError`), and a value outside the record's form — a date that is not a calendar date, a reason outside `configured` / `not-configured` / `selected` / `not-selected`, a guidance hash that is not lowercase hex SHA-256, an origin outside `endpoint` / `inline` / `fallback` — is refused by the derivation (`RecordFieldError`), never dropped. The `org.civicaitools.composition` block is emitted under every content profile, appended after the other extensions, and only when one of its fields is passed: a package built with none of these inputs has 0.6.0's extensions bytes, except that a datHere environment block no longer states the two placeholders.
+
 ## Purity contract (harness-grade)
 
 No I/O, no network, no environment reads, no Node built-ins, browser-safe — anywhere in the package. Clock and RNG are permitted **in capture modules only** (span timestamps and ids are what capture *is*) and are injectable for deterministic tests. Enforced mechanically twice: `eslint.config.mjs` (`no-restricted-imports` / `-globals` / `-properties` / `-syntax`) and `src/purity.test.ts` (browser-safety + determinism + module-boundary checks under `node --test`).
 
-Runtime dependency: **`@typedstandards/produce-core` (`^0.2.0`) only.** The verify-core primitives the harness consumes (`sha256Hex`, `isBlobRef`, the canonicalization-rule URIs, the Q32 vocabulary table, the `CaptureMethod` type) are reached through produce-core's 0.2.0 re-exports rather than imported from `@typedstandards/verify-core` directly — one declared dependency, no phantom, and still one hashing implementation across producer, harness, and verifier by construction (produce-core re-exports the same bindings verify-core defines, verified by reference identity).
+Runtime dependency: **`@typedstandards/produce-core` (`^0.8.0`) only.** The verify-core primitives the harness consumes (`sha256Hex`, `isBlobRef`, the canonicalization-rule URIs, the Q32 vocabulary table, the `CaptureMethod` type) are reached through produce-core's 0.2.0 re-exports rather than imported from `@typedstandards/verify-core` directly — one declared dependency, no phantom, and still one hashing implementation across producer, harness, and verifier by construction (produce-core re-exports the same bindings verify-core defines, verified by reference identity).
 
 > **Q32 adjacency** (open-questions registry): the captureMethod vocabulary re-exported from `src/format/profiles.ts` is verify-core's hardcoded fallback table, pending versioned, content-addressed guidance bundles. Flagged, not solved, here.
 
 ## Byte-compatibility
 
-The port is tested for **byte parity** against golden outputs captured from the reference implementation (`src/__fixtures__/website-golden.json`): with the reference config passed explicitly, `buildProvenanceGraph` and `buildDataSources` reproduce the app's output byte-for-byte, and `RUBRIC_VERSION_SHA256` is asserted against the exact reference digest (moving the rubric changes no hashes). Both captured fixtures predate the 2026-08-19 vocabulary settlement, so their byte-parity legs run with `PRIOR_ERA_CIVIC_VOCABULARY` injected — the fixtures are never rewritten — beside a settlement-era leg asserting the same bytes with exactly the two Appendix J literals substituted. Fixture-level byte-compat against produce-core's `reference-golden.json` (`src/golden-reproduction.test.ts`) and the produce→verify composition round-trip (`src/composition-roundtrip.test.ts`) landed in S2 P2 and run with the suite.
+The port is tested for **byte parity** against golden outputs captured from the reference implementation (`src/__fixtures__/website-golden.json`): with the reference config passed explicitly, `buildProvenanceGraph` and `buildDataSources` reproduce the app's output byte-for-byte, lifted over the two behaviours the harness has deliberately changed since (the #205 address fallback in 0.5.0 and the fallback attribution in 0.7.0, each a named transform of the frozen bytes with its node count asserted; both frozen fixtures' sha256 is asserted by `src/frozen-fixtures.test.ts`), and `RUBRIC_VERSION_SHA256` is asserted against the exact reference digest (moving the rubric changes no hashes). Both captured fixtures predate the 2026-08-19 vocabulary settlement, so their byte-parity legs run with `PRIOR_ERA_CIVIC_VOCABULARY` injected — the fixtures are never rewritten — beside a settlement-era leg asserting the same bytes with exactly the two Appendix J literals substituted. Fixture-level byte-compat against produce-core's `reference-golden.json` (`src/golden-reproduction.test.ts`) and the produce→verify composition round-trip (`src/composition-roundtrip.test.ts`) landed in S2 P2 and run with the suite.
 
 ## Develop
 

package/dist/capture/data-sources.d.ts

@@ -1,5 +1,4 @@
 import type { DataSourceEntry } from '@typedstandards/produce-core';
-import { type CivicSourceRegistry, type ToolSourceResolver } from '../format/sources.ts';
 export type { DataSourceEntry };
 /** The caller-supplied per-tool-call summary the population walks alongside
  *  the trace. */
@@ -23,7 +22,9 @@ export interface ToolCallSummary {
      *  rejection. Added 0.4.0. */
     failureKind?: string;
 }
-interface TraceSpan {
+/** The span shape the resolver inspects. Exported for the civic layer's
+ *  signatures; the package entry does not export it. */
+export interface TraceSpan {
     name: string;
     attributes?: Array<{
         key: string;
@@ -34,18 +35,23 @@ interface TraceSpan {
         };
     }>;
 }
-/** Optional knobs for `resolveToolSource` / `buildDataSources`. Defaults are
- *  the civic demo values. */
-export interface DataSourceOptions {
+/** Every input the population reads besides the calls and the trace, each
+ *  one explicit. */
+export interface DataSourceBuildConfig {
     /** Tool-name → source-id resolver (fallback when a span carries no
-     *  `mcp.source` attribute). Default: the civic map. */
-    resolver?: ToolSourceResolver;
-    /** Source registry driving catalog types, endpoints, and the
-     *  dataset-keyed vs aggregate split. Default: the civic registry. */
-    registry?: CivicSourceRegistry;
-    /** Source id for calls neither the trace nor the resolver can identify.
-     *  Default `socrata` (pre-M9.1 packages predate source tagging). */
-    fallbackSourceId?: string;
+     *  `mcp.source` attribute). */
+    resolver: (toolName: string) => string | undefined;
+    /** Source id → catalog type and, for an aggregate source, the portal URL of
+     *  its single entry. Insertion order is emission order. */
+    registry: Record<string, {
+        catalogType: string;
+        aggregatePortalUrl?: string;
+    }>;
+    /** Source id for calls neither the trace nor the resolver can identify. */
+    fallbackSourceId: string;
+    /** Is this source dataset-keyed (one entry per dataset)? Supplied by the
+     *  caller, consistent with `registry`. */
+    isDatasetKeyed: (sourceId: string) => boolean;
 }
 /**
  * Resolve the MCP source for a tool call. Prefers the `mcp.source` attribute
@@ -58,7 +64,7 @@ export interface DataSourceOptions {
  * flow. When the counts diverge, the static resolver still identifies the
  * source.
  */
-export declare function resolveToolSource(toolCall: ToolCallSummary, span: TraceSpan | undefined, resolver?: ToolSourceResolver, fallbackSourceId?: string): string;
+export declare function resolveToolSourceWith(toolCall: ToolCallSummary, span: TraceSpan | undefined, resolver: (toolName: string) => string | undefined, fallbackSourceId: string): string;
 /**
  * Build the per-source evidence-package `dataSources` array.
  *
@@ -81,11 +87,8 @@ export declare function resolveToolSource(toolCall: ToolCallSummary, span: Trace
  * activities and in the caller's own `queries[]` — what it is not is an
  * assertion, inside signed bytes, that a source was reached at a timestamp.
  *
- * @param fallbackPortal DEPRECATED, and inert since 0.3.1: an entry states
- * the portal the call carried, never the run's. It stays third of five
- * positional parameters so existing callers keep compiling, and since 0.4.0
- * it also accepts `undefined`, which is what a caller that has stopped
- * consulting it should pass. Dropping it is a breaking change and waits for
- * a major.
+ * The run's portal is not a parameter: an entry states the portal the call
+ * carried, never the run's (the civic layer's `buildDataSources` keeps its
+ * inert `fallbackPortal` positional for existing callers).
  */
-export declare function buildDataSources(toolCalls: ToolCallSummary[], trace: Record<string, unknown>, fallbackPortal: string | undefined, now: string, options?: DataSourceOptions): DataSourceEntry[];
+export declare function buildDataSourcesWith(toolCalls: ToolCallSummary[], trace: Record<string, unknown>, now: string, config: DataSourceBuildConfig): DataSourceEntry[];

package/dist/capture/data-sources.js

@@ -2,17 +2,19 @@
 // spans plus the caller-supplied tool-call summary to produce one
 // `dataSources` entry per (source, datasetId) tuple. Relocated from
 // civic-ai-tools-website `src/lib/evidence/data-sources.ts:78–185` per the S2
-// brief §1, with two changes:
-//   - The tool-name → source-id resolver is a CALLER-SUPPLIED input (the
-//     app's MCP registry stays app-side); `civicToolSourceResolver` is the
-//     exported civic default.
-//   - The per-source coordinates (catalog types, endpoints) come from the
-//     format-extension group's source registry instead of module constants —
-//     which sources are dataset-keyed vs aggregate is registry-driven.
+// brief §1.
+//
+// THE SEAM (civic-ai-tools#244 P2). This module imports nothing civic: the
+// tool-name → source-id resolver, the source registry (catalog types,
+// endpoints, the dataset-keyed vs aggregate split), the fallback source id
+// and the dataset-keyed fact all arrive as parameters, every one of them
+// required. The civic defaults are applied one layer up, in
+// `src/civic/data-sources.ts`, which exports the package's `buildDataSources`,
+// `resolveToolSource` and `DataSourceOptions` under their existing names and
+// signatures.
 //
 // `DataSourceEntry` is produce-core's envelope input shape — the harness
 // populates it, never redefines it.
-import { CIVIC_SOURCE_REGISTRY, FALLBACK_SOURCE_ID, civicToolSourceResolver, isDatasetKeyedSource, } from "../format/sources.js";
 function getToolSpans(trace) {
     try {
         // Untyped walk over the caller's trace shape.
@@ -42,7 +44,7 @@ function spanAttr(span, key) {
  * flow. When the counts diverge, the static resolver still identifies the
  * source.
  */
-export function resolveToolSource(toolCall, span, resolver = civicToolSourceResolver, fallbackSourceId = FALLBACK_SOURCE_ID) {
+export function resolveToolSourceWith(toolCall, span, resolver, fallbackSourceId) {
     return spanAttr(span, 'mcp.source')
         ?? resolver(toolCall.name)
         ?? fallbackSourceId;
@@ -69,17 +71,12 @@ export function resolveToolSource(toolCall, span, resolver = civicToolSourceReso
  * activities and in the caller's own `queries[]` — what it is not is an
  * assertion, inside signed bytes, that a source was reached at a timestamp.
  *
- * @param fallbackPortal DEPRECATED, and inert since 0.3.1: an entry states
- * the portal the call carried, never the run's. It stays third of five
- * positional parameters so existing callers keep compiling, and since 0.4.0
- * it also accepts `undefined`, which is what a caller that has stopped
- * consulting it should pass. Dropping it is a breaking change and waits for
- * a major.
+ * The run's portal is not a parameter: an entry states the portal the call
+ * carried, never the run's (the civic layer's `buildDataSources` keeps its
+ * inert `fallbackPortal` positional for existing callers).
  */
-export function buildDataSources(toolCalls, trace, fallbackPortal, now, options = {}) {
-    const resolver = options.resolver ?? civicToolSourceResolver;
-    const registry = options.registry ?? CIVIC_SOURCE_REGISTRY;
-    const fallbackSourceId = options.fallbackSourceId ?? FALLBACK_SOURCE_ID;
+export function buildDataSourcesWith(toolCalls, trace, now, config) {
+    const { resolver, registry, fallbackSourceId } = config;
     const toolSpans = getToolSpans(trace);
     const datasetKeyed = new Map();
     const aggregateAccessed = new Set();
@@ -87,12 +84,12 @@ export function buildDataSources(toolCalls, trace, fallbackPortal, now, options
         const tc = toolCalls[i];
         // A call the producer recorded as rejected reached no data, so it mints
         // no entry on either branch below. The walk keeps its index rather than
-        // filtering the list: `resolveToolSource` pairs a call to `toolSpans[i]`,
+        // filtering the list: `resolveToolSourceWith` pairs a call to `toolSpans[i]`,
         // and a filtered list would shift every later call onto the wrong span.
         if (tc.failed)
             continue;
-        const source = resolveToolSource(tc, toolSpans[i], resolver, fallbackSourceId);
-        if (isDatasetKeyedSource(source, registry)) {
+        const source = resolveToolSourceWith(tc, toolSpans[i], resolver, fallbackSourceId);
+        if (config.isDatasetKeyed(source)) {
             const datasetId = tc.args.dataset_id;
             const portal = tc.args.portal;
             // An entry is minted only from what the call carried: a dataset id AND

package/dist/capture/provenance.d.ts

@@ -1,6 +1,4 @@
 import { type ProvGraph, type ProvNode } from '@typedstandards/produce-core';
-import { type CivicVocabulary, type PlatformAgentConfig } from '../format/vocabulary.ts';
-import { type CivicSourceRegistry } from '../format/sources.ts';
 export type { ProvGraph, ProvNode };
 /** Package-level inputs to the graph build. */
 export interface ProvenanceInput {
@@ -27,41 +25,88 @@ export interface ProvenanceInput {
      *  literal an excess-property error, so removal waits for a major. */
     portal?: string;
 }
-/** Instance configuration for the graph build (config-not-constants). */
-export interface ProvenanceConfig {
+/** The id scheme and `@context` the builder emits under. Structural: the
+ *  format group's vocabulary objects satisfy it, and this module never
+ *  imports them. */
+export interface ProvenanceVocabulary {
+    /** The graph's JSON-LD `@context`, in emission order. */
+    context(): Record<string, string>;
+    /** Package-scoped node id. */
+    urn(packageId: string, type: string, id: string): string;
+    /** Model-agent id. */
+    modelUrn(model: string): string;
+    /** MCP source-agent id. The builder encodes an UNKNOWN id with
+     *  `encodeURIComponent` before passing it. */
+    sourceAgentUrn(sourceId: string): string;
+    /** Platform-agent id. */
+    platformUrn(platformId: string): string;
+}
+/** The property names the builder keys its domain-specific properties with,
+ *  one per property. The builder spells none of them; the civic layer passes
+ *  the format group's declared terms. */
+export interface ProvenanceTerms {
+    readonly contentHash: string;
+    readonly serverUrl: string;
+    readonly sourceId: string;
+    readonly url: string;
+    readonly promptTokens: string;
+    readonly completionTokens: string;
+    readonly toolName: string;
+    readonly operationType: string;
+    readonly datasetId: string;
+    readonly portalDomain: string;
+    readonly datasetUrl: string;
+    readonly croissantMetadataUrl: string;
+    readonly responseRows: string;
+    readonly durationMs: string;
+    readonly failed: string;
+    readonly failureKind: string;
+    /** The wire name of a call whose exposed name is aliased (ADR-0033 §B). */
+    readonly upstreamToolName: string;
+    /** The alias of the source that answered a call. */
+    readonly sourceAlias: string;
+    /** The identity of the server that answered a call. */
+    readonly serverId: string;
+}
+/** One source the builder can name as an agent. Structural: a format-group
+ *  registry entry satisfies it. */
+export interface ProvenanceSourceInfo {
+    /** The agent's `dcterms:title`. */
+    agentTitle: string;
+    /** The agent's server URL. Absent means the graph states no address for
+     *  the source (civic-ai-tools#205). */
+    serverUrl?: string;
+}
+/** Every input the builder reads, each one explicit. */
+export interface ProvenanceBuildConfig {
     /** Platform-agent identity — the deployment publishing the record. */
-    platformAgent: PlatformAgentConfig;
-    /** Source registry supplying agent titles and MCP server URLs. Caller-
-     *  supplied configuration: an instance passes the addresses it is pointed
-     *  at, and an entry with no `serverUrl` makes its agent omit
-     *  `civic:serverUrl` (civic-ai-tools#205). */
-    sourceRegistry: CivicSourceRegistry;
-    /** Source id untagged tool spans fall back to. Default `socrata`
-     *  (pre-source-tagging captures were Socrata-only). */
-    fallbackSourceId?: string;
-    /** Source whose agent `civic:serverUrl` the trace's skill-fetch span URL
-     *  overrides when present (the skill is fetched from that source's MCP
-     *  server). Default `socrata`. */
-    skillSourceId?: string;
-    /** `dcterms:description` of the model agent. When unset, the model agent
-     *  carries no `dcterms:description` at all — the field is omitted from the
-     *  graph (honest omission), never filled with a fallback. */
+    platformAgent: {
+        id: string;
+        title: string;
+        url: string;
+    };
+    /** Source id → agent coordinates. Insertion order is agent order. */
+    sourceRegistry: Record<string, ProvenanceSourceInfo>;
+    /** Is this source dataset-keyed (its data responses carry the dataset id,
+     *  portal and dataset URL)? Supplied by the caller, consistent with
+     *  `sourceRegistry`. */
+    isDatasetKeyed: (sourceId: string) => boolean;
+    /** Tool-name → source-id resolver, consulted for a span that carries no
+     *  `mcp.source` tag. */
+    resolver: (toolName: string) => string | undefined;
+    /** Source id for a span neither its tag nor the resolver identifies. */
+    fallbackSourceId: string;
+    /** Source whose agent server URL the trace's skill-fetch span URL
+     *  overrides when present. */
+    skillSourceId: string;
+    /** `dcterms:description` of the model agent; omitted from the graph when
+     *  unset, never filled with a fallback. */
     modelAgentDescription?: string;
-    /** Vocabulary era to emit (spec Appendix J). Defaults to the settlement-era
-     *  `CIVIC_VOCABULARY` — the only value a new emission may use. Supply
-     *  `PRIOR_ERA_CIVIC_VOCABULARY` ONLY to reproduce or verify a record signed
-     *  before the 2026-08-19 settlement, whose identifiers are frozen under the
-     *  hash it was signed with. Unlike the other fields here this is not
-     *  deployment identity, so it is defaulted rather than required: emitting
-     *  the current vocabulary is never the silent-attribution hazard ADR-0024
-     *  guards against. */
-    vocabulary?: CivicVocabulary;
+    /** Id scheme and `@context`. */
+    vocabulary: ProvenanceVocabulary;
+    /** Property names. */
+    terms: ProvenanceTerms;
 }
-/** The civicaitools.org reference deployment's values. Passed explicitly by
- *  the reference app — never applied as a default, and never spread into
- *  another instance's config, which would assert infrastructure that
- *  instance doesn't run. */
-export declare const CIVICAITOOLS_PROVENANCE_CONFIG: ProvenanceConfig;
 /**
  * Build a W3C PROV-O JSON-LD graph from an OTel trace and package metadata.
  *
@@ -71,4 +116,4 @@ export declare const CIVICAITOOLS_PROVENANCE_CONFIG: ProvenanceConfig;
  * - Prompt, skill guidance, data responses, output → prov:Entity
  * - LLM model, MCP server, platform → prov:Agent
  */
-export declare function buildProvenanceGraph(trace: Record<string, unknown>, input: ProvenanceInput, config: ProvenanceConfig): ProvGraph;
+export declare function buildProvenanceGraphWith(trace: Record<string, unknown>, input: ProvenanceInput, config: ProvenanceBuildConfig): ProvGraph;