@typedstandards/civic-typed-harness 0.6.0 → 0.7.0

package/dist/capture/provenance.js

@@ -1,33 +1,23 @@
-// Civic provenance builder (CAPTURE group) — walks an OTel trace and maps the
+// Provenance builder (CAPTURE group) — walks an OTel trace and maps the
 // analysis pipeline (LLM inference, MCP tool calls, data responses) to a
 // W3C PROV-O JSON-LD graph. Relocated whole from civic-ai-tools-website
 // `src/lib/evidence/provenance.ts:65–392` per the S2 brief §1, rebuilt on
 // @typedstandards/produce-core's generic ProvGraph/ProvNode types and
-// node/edge helpers. Every `civic:` term, urn scheme, and agent coordinate is
-// imported from the format-extension group — this module WALKS, it does not
-// define vocabulary (the package's internal module boundary).
+// node/edge helpers.
 //
-// Config-not-constants: the platform-agent identity, the source-agent
-// registry (server URLs), and the model-agent description are typed config
-// inputs, and the config is REQUIRED — no deployment identity is ever
-// applied silently (ADR-0024 posture at the domain layer).
-// `CIVICAITOOLS_PROVENANCE_CONFIG` is the reference deployment's values,
-// which the reference app passes explicitly; with it, the builder reproduces
-// the reference implementation's output byte-for-byte (property insertion
-// order is preserved throughout — the legacy hash chain's byte contract).
+// THE SEAM (civic-ai-tools#244 P2). This module imports nothing civic: the
+// vocabulary (id scheme and `@context`), the term names it keys properties
+// with, the source registry, the fallback and skill source ids and the
+// dataset-keyed fact all arrive in `ProvenanceBuildConfig`, every one of them
+// required. It WALKS; it neither defines vocabulary nor applies a default.
+// The civic values are applied one layer up, in `src/civic/provenance.ts`,
+// which exports the package's `buildProvenanceGraph`, `ProvenanceConfig` and
+// `CIVICAITOOLS_PROVENANCE_CONFIG` under their existing names and
+// signatures. Given the civic values, this builder emits what it emitted
+// before the seam, byte for byte (property insertion order is preserved
+// throughout — the legacy hash chain's byte contract).
 import { makeProvGraph, makeEntityNode, makeActivityNode, makeAgentNode, provRef, provUsed, provWasGeneratedBy, provWasDerivedFrom, provWasAssociatedWith, xsdDateTime, } from '@typedstandards/produce-core';
 import { hash } from "./trace.js";
-import { CIVIC_VOCABULARY, CIVICAITOOLS_PLATFORM_AGENT, CIVIC_TERM_COMPLETION_TOKENS, CIVIC_TERM_CONTENT_HASH, CIVIC_TERM_CROISSANT_METADATA_URL, CIVIC_TERM_DATASET_ID, CIVIC_TERM_DATASET_URL, CIVIC_TERM_DURATION_MS, CIVIC_TERM_FAILED, CIVIC_TERM_FAILURE_KIND, CIVIC_TERM_OPERATION_TYPE, CIVIC_TERM_PORTAL_DOMAIN, CIVIC_TERM_PROMPT_TOKENS, CIVIC_TERM_RESPONSE_ROWS, CIVIC_TERM_SERVER_URL, CIVIC_TERM_SOURCE_ID, CIVIC_TERM_TOOL_NAME, CIVIC_TERM_URL, } from "../format/vocabulary.js";
-import { CIVIC_SOURCE_REGISTRY, FALLBACK_SOURCE_ID, isDatasetKeyedSource, } from "../format/sources.js";
-/** 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 const CIVICAITOOLS_PROVENANCE_CONFIG = {
-    platformAgent: CIVICAITOOLS_PLATFORM_AGENT,
-    sourceRegistry: CIVIC_SOURCE_REGISTRY,
-    modelAgentDescription: 'Large language model via OpenRouter',
-};
 // --- Helpers ---
 function getAttr(attrs, key) {
     const attr = attrs.find(a => a.key === key);
@@ -71,24 +61,22 @@ function nanoToIso(nano) {
  * - Prompt, skill guidance, data responses, output → prov:Entity
  * - LLM model, MCP server, platform → prov:Agent
  */
-export function buildProvenanceGraph(trace, input, config) {
+export function buildProvenanceGraphWith(trace, input, config) {
     const otel = trace;
     const spans = otel?.resourceSpans?.[0]?.scopeSpans?.[0]?.spans || [];
     // `input.portal` is deliberately not read — see `ProvenanceInput.portal`.
     const { packageId, promptHash, promptText, outputText, model } = input;
     const outputHash = input.outputHash ?? hash(outputText ?? '');
     const registry = config.sourceRegistry;
-    const fallbackSourceId = config.fallbackSourceId ?? FALLBACK_SOURCE_ID;
-    const skillSourceId = config.skillSourceId ?? FALLBACK_SOURCE_ID;
-    // Vocabulary era — settlement-era unless a prior-era reproduction asks
-    // otherwise. Every id and the `@context` below route through it, so a graph
-    // never mixes eras.
-    const vocab = config.vocabulary ?? CIVIC_VOCABULARY;
+    const { fallbackSourceId, skillSourceId, terms } = config;
+    // Every id and the `@context` below route through the one vocabulary, so a
+    // graph never mixes eras.
+    const vocab = config.vocabulary;
     const graph = [];
     // --- Entities ---
     // User prompt
     graph.push(makeEntityNode(vocab.urn(packageId, 'prompt', promptHash), {
-        [CIVIC_TERM_CONTENT_HASH]: `sha256:${promptHash}`,
+        [terms.contentHash]: `sha256:${promptHash}`,
         'dcterms:description': 'User query prompt',
         ...(promptText ? { 'prov:value': promptText } : {}),
     }));
@@ -101,13 +89,13 @@ export function buildProvenanceGraph(trace, input, config) {
     const skillServerUrl = skillSpan ? getAttr(skillSpan.attributes, 'skill.mcp_server_url') : undefined;
     if (skillHash) {
         graph.push(makeEntityNode(vocab.urn(packageId, 'skill', skillHash), {
-            [CIVIC_TERM_CONTENT_HASH]: `sha256:${skillHash}`,
+            [terms.contentHash]: `sha256:${skillHash}`,
             'dcterms:description': 'Composed MCP skill guidance (system prompt)',
         }, ['prov:Plan']));
     }
     // Final output
     graph.push(makeEntityNode(vocab.urn(packageId, 'output', outputHash), {
-        [CIVIC_TERM_CONTENT_HASH]: `sha256:${outputHash}`,
+        [terms.contentHash]: `sha256:${outputHash}`,
         'dcterms:description': 'AI-generated analysis output',
     }));
     // --- Agents ---
@@ -122,11 +110,13 @@ export function buildProvenanceGraph(trace, input, config) {
             : {}),
     }, ['prov:SoftwareAgent']));
     // MCP server agents — one per distinct data source that appears in the
-    // trace. Tool spans carry `mcp.source`; records captured before
-    // source tagging have no source attribute, so they fall back to the
-    // configured fallback source (socrata — the only source at the time) for
-    // backwards compatibility. Agent coordinates come from the source registry;
-    // the skill-fetch span URL overrides the skill source's server URL.
+    // trace. A tool span's source is its `mcp.source` tag; a span with no tag
+    // (records captured before source tagging) resolves by its tool name
+    // through the caller's resolver; a span neither identifies takes the
+    // caller's `fallbackSourceId` (the civic layer's default is `unknown`, the
+    // value the reference app writes for a tool it cannot resolve — ADR-0033
+    // §A). Agent coordinates come from the source registry; the skill-fetch
+    // span URL overrides the skill source's server URL.
     //
     // THE ADDRESS IS THE OPERATOR'S, OR IT IS ABSENT (civic-ai-tools#205, 0.5.0).
     // `serverUrl` is optional on a registry entry and there is no stand-in for a
@@ -143,10 +133,18 @@ export function buildProvenanceGraph(trace, input, config) {
             serverUrl: id === skillSourceId ? skillServerUrl || info.serverUrl : info.serverUrl,
         };
     }
+    // The ONE resolution of a span's source, used for its agent node, its
+    // attribution and its `civic:sourceId` alike.
+    function sourceOfSpan(attributes) {
+        const tagged = getAttr(attributes, 'mcp.source');
+        if (tagged)
+            return tagged;
+        const toolName = getAttr(attributes, 'tool.name');
+        return (toolName ? config.resolver(toolName) : undefined) || fallbackSourceId;
+    }
     const sourcesInTrace = new Set();
     for (const span of toolSpans) {
-        const source = getAttr(span.attributes, 'mcp.source') || fallbackSourceId;
-        sourcesInTrace.add(source);
+        sourcesInTrace.add(sourceOfSpan(span.attributes));
     }
     for (const sourceId of sourcesInTrace) {
         const meta = sourceAgentMap[sourceId] ?? {
@@ -157,23 +155,22 @@ export function buildProvenanceGraph(trace, input, config) {
             'dcterms:title': meta.title,
             // Conditional spread in place, so a known address keeps its
             // position in the key order the legacy chain hashes.
-            ...(meta.serverUrl ? { [CIVIC_TERM_SERVER_URL]: meta.serverUrl } : {}),
-            [CIVIC_TERM_SOURCE_ID]: sourceId,
+            ...(meta.serverUrl ? { [terms.serverUrl]: meta.serverUrl } : {}),
+            [terms.sourceId]: sourceId,
         }, ['prov:SoftwareAgent']));
     }
-    // Resolve a source id to its agent URN, falling back to the configured
-    // fallback source for records that never tagged the span. (Reference
-    // behavior preserved: unknown ids resolve to the fallback source's agent.)
+    // A call is attributed to ITS OWN source's agent: the registry's agent
+    // when the registry carries the source, otherwise the agent node emitted
+    // above for it (ADR-0033 §A). Until 0.7.0 an id the registry lacked was
+    // attributed to the fallback source's agent instead — which, in a run where
+    // that source made no call, named an agent the graph did not contain.
     function agentUrnForSource(sourceId) {
-        const id = sourceId || fallbackSourceId;
-        return (sourceAgentMap[id]?.urn
-            ?? sourceAgentMap[fallbackSourceId]?.urn
-            ?? vocab.sourceAgentUrn(encodeURIComponent(id)));
+        return sourceAgentMap[sourceId]?.urn ?? vocab.sourceAgentUrn(encodeURIComponent(sourceId));
     }
     // Platform
     graph.push(makeAgentNode(vocab.platformUrn(config.platformAgent.id), {
         'dcterms:title': config.platformAgent.title,
-        [CIVIC_TERM_URL]: config.platformAgent.url,
+        [terms.url]: config.platformAgent.url,
     }, ['prov:SoftwareAgent']));
     // --- Activities ---
     // LLM inference spans
@@ -198,8 +195,8 @@ export function buildProvenanceGraph(trace, input, config) {
             ...(span.endTimeUnixNano
                 ? { 'prov:endedAtTime': xsdDateTime(nanoToIso(span.endTimeUnixNano)) }
                 : {}),
-            ...(promptTokens ? { [CIVIC_TERM_PROMPT_TOKENS]: Number(promptTokens) } : {}),
-            ...(completionTokens ? { [CIVIC_TERM_COMPLETION_TOKENS]: Number(completionTokens) } : {}),
+            ...(promptTokens ? { [terms.promptTokens]: Number(promptTokens) } : {}),
+            ...(completionTokens ? { [terms.completionTokens]: Number(completionTokens) } : {}),
         }));
     }
     // MCP tool call spans.
@@ -230,9 +227,15 @@ export function buildProvenanceGraph(trace, input, config) {
         const datasetId = getAttr(span.attributes, 'tool.dataset_id');
         // Absent when the span carried none — never the run's portal.
         const portalDomain = getAttr(span.attributes, 'tool.portal_domain');
-        const toolSource = getAttr(span.attributes, 'mcp.source') || fallbackSourceId;
+        const toolSource = sourceOfSpan(span.attributes);
         const toolAgentUrn = agentUrnForSource(toolSource);
-        const toolSourceDatasetKeyed = isDatasetKeyedSource(toolSource, registry);
+        // The call's other identities (ADR-0033 §B): the name sent on the wire,
+        // the alias of the source and the server's id. Absent when the span
+        // carried none — never derived from the exposed name.
+        const upstreamToolName = getAttr(span.attributes, 'tool.upstream_name');
+        const sourceAlias = getAttr(span.attributes, 'mcp.alias');
+        const serverId = getAttr(span.attributes, 'mcp.server.id');
+        const toolSourceDatasetKeyed = config.isDatasetKeyed(toolSource);
         // Query entity (tool arguments). Find the most recent inference span
         // before this tool call to link as generator.
         const toolStart = Number(span.startTimeUnixNano);
@@ -241,10 +244,10 @@ export function buildProvenanceGraph(trace, input, config) {
             .sort((a, b) => Number(b.endTimeUnixNano || '0') - Number(a.endTimeUnixNano || '0'))[0];
         const queryUrn = vocab.urn(packageId, 'query', queryHash);
         graph.push(makeEntityNode(queryUrn, {
-            [CIVIC_TERM_CONTENT_HASH]: `sha256:${queryHash}`,
+            [terms.contentHash]: `sha256:${queryHash}`,
             // Omitted — not placeholdered — when the span named no tool.
-            ...(toolName ? { [CIVIC_TERM_TOOL_NAME]: toolName } : {}),
-            [CIVIC_TERM_OPERATION_TYPE]: opType,
+            ...(toolName ? { [terms.toolName]: toolName } : {}),
+            [terms.operationType]: opType,
             'dcterms:description': `MCP tool arguments (${opType})`,
             ...(precedingInference
                 ? provWasGeneratedBy(vocab.urn(packageId, 'inference', precedingInference.spanId))
@@ -272,9 +275,9 @@ export function buildProvenanceGraph(trace, input, config) {
                 : `Data response from ${sourceAgentMap[toolSource]?.title || toolSource}`;
             const responseRows = getAttr(span.attributes, 'tool.response_rows');
             graph.push(makeEntityNode(dataUrn, {
-                [CIVIC_TERM_CONTENT_HASH]: `sha256:${responseHash}`,
+                [terms.contentHash]: `sha256:${responseHash}`,
                 'dcterms:description': description,
-                [CIVIC_TERM_SOURCE_ID]: toolSource,
+                [terms.sourceId]: toolSource,
                 ...provWasGeneratedBy(toolCallUrn),
                 // Croissant 1.1 placeholder — only meaningful for dataset-keyed
                 // sources today. The dataset id is stated whenever the span carried
@@ -282,17 +285,17 @@ export function buildProvenanceGraph(trace, input, config) {
                 // the portal as well. Key order is the byte contract.
                 ...(toolSourceDatasetKeyed && datasetId
                     ? {
-                        [CIVIC_TERM_DATASET_ID]: datasetId,
+                        [terms.datasetId]: datasetId,
                         ...(portalDomain
                             ? {
-                                [CIVIC_TERM_PORTAL_DOMAIN]: portalDomain,
-                                [CIVIC_TERM_DATASET_URL]: `https://${portalDomain}/d/${datasetId}`,
+                                [terms.portalDomain]: portalDomain,
+                                [terms.datasetUrl]: `https://${portalDomain}/d/${datasetId}`,
                             }
                             : {}),
-                        [CIVIC_TERM_CROISSANT_METADATA_URL]: null, // hook for future Croissant integration
+                        [terms.croissantMetadataUrl]: null, // hook for future Croissant integration
                     }
                     : {}),
-                ...(responseRows ? { [CIVIC_TERM_RESPONSE_ROWS]: Number(responseRows) } : {}),
+                ...(responseRows ? { [terms.responseRows]: Number(responseRows) } : {}),
             }));
         }
         // Tool call activity — associated with the MCP source agent that handled
@@ -325,7 +328,7 @@ export function buildProvenanceGraph(trace, input, config) {
             'dcterms:description': toolName
                 ? `MCP tool call: ${toolName} (${opType})`
                 : `MCP tool call (${opType})`,
-            [CIVIC_TERM_SOURCE_ID]: toolSource,
+            [terms.sourceId]: toolSource,
             ...provUsed([queryUrn]),
             ...provWasAssociatedWith(toolAgentUrn),
             ...(span.startTimeUnixNano
@@ -334,7 +337,7 @@ export function buildProvenanceGraph(trace, input, config) {
             ...(span.endTimeUnixNano
                 ? { 'prov:endedAtTime': xsdDateTime(nanoToIso(span.endTimeUnixNano)) }
                 : {}),
-            ...(durationMs ? { [CIVIC_TERM_DURATION_MS]: Number(durationMs) } : {}),
+            ...(durationMs ? { [terms.durationMs]: Number(durationMs) } : {}),
             // Appended LAST and spread conditionally, exactly as `civic:durationMs`
             // above is: a span that recorded no rejection yields the key list it
             // yielded at 0.3.1, in the same order, and property insertion order is
@@ -353,8 +356,13 @@ export function buildProvenanceGraph(trace, input, config) {
             // since 0.3.1, because that conditional is unchanged and this one is
             // still appended after it. `capture/provenance.test.ts` drives that
             // combination and pins the whole key list for it.
-            ...(failed === true ? { [CIVIC_TERM_FAILED]: true } : {}),
-            ...(failureKind ? { [CIVIC_TERM_FAILURE_KIND]: failureKind } : {}),
+            ...(failed === true ? { [terms.failed]: true } : {}),
+            ...(failureKind ? { [terms.failureKind]: failureKind } : {}),
+            // Appended after everything above, each only when the span carried
+            // it, so a span without them yields the 0.6.0 key list (ADR-0033 §B).
+            ...(upstreamToolName ? { [terms.upstreamToolName]: upstreamToolName } : {}),
+            ...(sourceAlias ? { [terms.sourceAlias]: sourceAlias } : {}),
+            ...(serverId ? { [terms.serverId]: serverId } : {}),
         }));
     }
     // --- Final output relationships ---

package/dist/capture/run-attributes.d.ts

@@ -0,0 +1,35 @@
+/** One server the run had, as the root span recorded it. */
+export interface RunMcpServer {
+    url: string;
+    name?: string;
+}
+/** What the root span carried, under the derivation's input names. A field
+ *  is absent when its attribute is. */
+export interface ExtractedRunAttributes {
+    assertedDate?: string;
+    runMcpServers?: RunMcpServer[];
+    toolDefinitions?: Array<Record<string, unknown>>;
+    sourcesOffered?: Array<{
+        sourceId: string;
+        alias: string;
+        reason: string;
+    }>;
+    components?: Array<{
+        id: string;
+        version?: string;
+        guidanceHash?: string;
+        guidanceOrigin?: string;
+    }>;
+}
+/** A root-span attribute that is present but not the shape ADR-0033 names. */
+export declare class RunAttributeError extends Error {
+    /** The span attribute that failed to parse. */
+    readonly attribute: string;
+    constructor(attribute: string, message: string);
+}
+/**
+ * Read the run attributes from a trace's root span. Returns `{}` for a trace
+ * with no root span — including a BlobRef trace's inspection view
+ * (`traceForInspection`), whose caller passes the fields as inputs instead.
+ */
+export declare function extractRunAttributes(trace: Record<string, unknown>): ExtractedRunAttributes;

package/dist/capture/run-attributes.js

@@ -0,0 +1,105 @@
+// Run-attribute extraction (CAPTURE group) — reads the facts the producer
+// recorded on the trace's ROOT span at run time (ADR-0033 §D, §E): the date
+// the prompt asserted, the servers the run had, the tools it offered, the
+// sources it was offered and the components that composed its prompt.
+//
+// WHY THE TRACE (civic-ai-tools-website#495). A record is packaged after the
+// run, sometimes much later; a fact read at packaging is packaging-time state.
+// The trace is the one artifact that travels from the run to the package, so
+// the producer writes each run-time fact there and this module reads it back.
+//
+// SHAPE, NOT POLICY. This module checks that each attribute parses as the
+// shape ADR-0033 names (JSON text of an array of objects whose named fields
+// are strings) and returns it under the derivation's input names. The values
+// — the date form, the reason set, the hash form, the origin set — are policy,
+// checked by the format group's derivation, which refuses a bad one by name.
+//
+// An ABSENT attribute is an absent field. A PRESENT attribute that does not
+// parse is refused with `RunAttributeError`, never read as absent: absence
+// here would hand the caller back to its packaging-time state, which is the
+// defect this module exists to remove.
+/** A root-span attribute that is present but not the shape ADR-0033 names. */
+export class RunAttributeError extends Error {
+    /** The span attribute that failed to parse. */
+    attribute;
+    constructor(attribute, message) {
+        super(`${attribute}: ${message}`);
+        this.name = 'RunAttributeError';
+        this.attribute = attribute;
+    }
+}
+/** The trace's root span: the first span with no parent. */
+function rootSpan(trace) {
+    // Untyped walk over the caller's trace shape, as skill extraction does.
+    const spans = trace?.resourceSpans?.[0]?.scopeSpans?.[0]?.spans;
+    if (!Array.isArray(spans))
+        return undefined;
+    return spans.find((s) => s && !s.parentSpanId);
+}
+function stringAttr(span, key) {
+    const attr = span.attributes?.find((a) => a.key === key);
+    return attr?.value?.stringValue;
+}
+/** Parse an attribute as JSON text of an array of plain objects, each of
+ *  whose `required` fields is a string and each of whose `optional` fields,
+ *  when present, is a string. */
+function objectArray(attribute, text, required, optional = []) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new RunAttributeError(attribute, 'is not JSON text');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new RunAttributeError(attribute, 'is not a JSON array');
+    }
+    parsed.forEach((entry, i) => {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new RunAttributeError(attribute, `entry ${i} is not an object`);
+        }
+        for (const field of required) {
+            if (typeof entry[field] !== 'string') {
+                throw new RunAttributeError(attribute, `entry ${i} has no string ${field}`);
+            }
+        }
+        for (const field of optional) {
+            const value = entry[field];
+            if (value !== undefined && typeof value !== 'string') {
+                throw new RunAttributeError(attribute, `entry ${i}: ${field} is not a string`);
+            }
+        }
+    });
+    return parsed;
+}
+/**
+ * Read the run attributes from a trace's root span. Returns `{}` for a trace
+ * with no root span — including a BlobRef trace's inspection view
+ * (`traceForInspection`), whose caller passes the fields as inputs instead.
+ */
+export function extractRunAttributes(trace) {
+    const root = rootSpan(trace);
+    if (!root)
+        return {};
+    const out = {};
+    const assertedDate = stringAttr(root, 'analysis.asserted_date');
+    if (assertedDate !== undefined)
+        out.assertedDate = assertedDate;
+    const servers = stringAttr(root, 'analysis.mcp_servers');
+    if (servers !== undefined) {
+        out.runMcpServers = objectArray('analysis.mcp_servers', servers, ['url'], ['name']);
+    }
+    const tools = stringAttr(root, 'analysis.tool_definitions');
+    if (tools !== undefined) {
+        out.toolDefinitions = objectArray('analysis.tool_definitions', tools, []);
+    }
+    const offered = stringAttr(root, 'analysis.sources_offered');
+    if (offered !== undefined) {
+        out.sourcesOffered = objectArray('analysis.sources_offered', offered, ['sourceId', 'alias', 'reason']);
+    }
+    const components = stringAttr(root, 'analysis.components');
+    if (components !== undefined) {
+        out.components = objectArray('analysis.components', components, ['id'], ['version', 'guidanceHash', 'guidanceOrigin']);
+    }
+    return out;
+}

package/dist/capture/trace.d.ts

@@ -50,7 +50,8 @@ export type TraceRandomBytes = (byteLength: number) => Uint8Array;
 /**
  * TraceBuilder identity + determinism inputs. The identity strings name the
  * capturing service, so they are per-instance config (config-not-constants);
- * the reference deployment's values are `CIVICAITOOLS_TRACE_CONFIG` below.
+ * the reference deployment's values are `CIVICAITOOLS_TRACE_CONFIG`
+ * (src/civic/trace.ts).
  * The identity fields are required; `now`/`randomBytes` are operational
  * fallbacks, not identity, and default to the runtime's clock and CSPRNG.
  */
@@ -69,9 +70,6 @@ export interface TraceBuilderConfig {
      *  `crypto.getRandomValues` (Web Crypto — Node 18+ and every browser). */
     randomBytes?: TraceRandomBytes;
 }
-/** The civicaitools.org reference deployment's capture identity. Passed
- *  explicitly by the reference app — never applied as a default. */
-export declare const CIVICAITOOLS_TRACE_CONFIG: TraceBuilderConfig;
 export declare class TraceBuilder {
     readonly traceId: string;
     readonly rootSpanId: string;

package/dist/capture/trace.js

@@ -8,7 +8,9 @@
 //     name/version, semconv version) are REQUIRED typed config inputs
 //     (config-not-constants, S2 brief §2); the reference deployment's values
 //     are exported as `CIVICAITOOLS_TRACE_CONFIG` for explicit use, never
-//     applied as a default.
+//     applied as a default. Since 0.7.0 that constant lives in
+//     src/civic/trace.ts (civic-ai-tools#246): capture defines no deployment
+//     value.
 //
 // Clock + RNG are INHERENT to capture (span timestamps and ids are what
 // capture *is*): this module is the sanctioned exception to the package's
@@ -34,14 +36,6 @@ function attrsFromRecord(attrs) {
 export function hash(content) {
     return sha256Hex(content);
 }
-/** The civicaitools.org reference deployment's capture identity. Passed
- *  explicitly by the reference app — never applied as a default. */
-export const CIVICAITOOLS_TRACE_CONFIG = {
-    serviceName: 'civic-ai-tools-website',
-    scopeName: 'civic-ai-tools-evidence',
-    scopeVersion: '0.1.0',
-    semconvVersion: '1.30.0',
-};
 function defaultRandomBytes(byteLength) {
     const buf = new Uint8Array(byteLength);
     globalThis.crypto.getRandomValues(buf);

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

@@ -0,0 +1,58 @@
+import { type DataSourceEntry, type ToolCallSummary, type TraceSpan } from '../capture/data-sources.ts';
+import { type CivicSourceRegistry, type ToolSourceResolver } from '../format/sources.ts';
+export type { DataSourceEntry, ToolCallSummary } from '../capture/data-sources.ts';
+/** Optional knobs for `resolveToolSource` / `buildDataSources`. Defaults are
+ *  the civic demo values. */
+export interface DataSourceOptions {
+    /** 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 `unknown` (`UNKNOWN_SOURCE_ID`, ADR-0033 §A): not a registry
+     *  entry, so such a call mints no entry. Until 0.7.0 the default was
+     *  `socrata`. */
+    fallbackSourceId?: string;
+}
+/**
+ * Resolve the MCP source for a tool call. Prefers the `mcp.source` attribute
+ * recorded on the matching `mcp_tool_call` span (the trace is the source of
+ * truth); falls back to the resolver's static mapping for packages written
+ * before source tagging or callers that ship an empty trace.
+ *
+ * Tool calls are paired to spans by index — the reference capture emits one
+ * span per call in order, so positional matching is exact in the normal
+ * 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;
+/**
+ * Build the per-source evidence-package `dataSources` array.
+ *
+ * Dataset-keyed sources (Socrata) contribute one entry per unique
+ * `dataset_id` observed across tool calls that also carried a `portal`
+ * argument; a dataset-keyed call that carried no portal contributes NO
+ * entry. Aggregate sources (Data Commons, Boston OpenContext — registry
+ * entries carrying `aggregatePortalUrl`) contribute a single entry when any
+ * of their tool calls was made. Unknown source ids contribute no entry. Each
+ * entry is tagged with `sourceId` so downstream consumers can distinguish
+ * provenance. Emission order: the dataset-keyed entries (first-seen order),
+ * then aggregate sources in registry insertion order — matching the
+ * reference implementation.
+ *
+ * A call the producer recorded as FAILED (`ToolCallSummary.failed`) asserts
+ * no access and contributes nothing on either branch; it keeps its position
+ * in the walk, because calls are paired to spans by index. The walk itself,
+ * and why each branch is shaped as it is, is `buildDataSourcesWith` in
+ * capture/data-sources.ts.
+ *
+ * @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.
+ */
+export declare function buildDataSources(toolCalls: ToolCallSummary[], trace: Record<string, unknown>, fallbackPortal: string | undefined, now: string, options?: DataSourceOptions): DataSourceEntry[];

package/dist/civic/data-sources.js

@@ -0,0 +1,63 @@
+// Civic data-source population (CIVIC layer) — the package's
+// `buildDataSources`, `resolveToolSource` and `DataSourceOptions`, under the
+// names and signatures they had when they lived in capture/data-sources.ts.
+//
+// The seam (civic-ai-tools#244 P2): capture/data-sources.ts walks the calls
+// and the trace and takes every civic input as a parameter; this module
+// supplies the civic defaults — `civicToolSourceResolver`,
+// `CIVIC_SOURCE_REGISTRY`, `UNKNOWN_SOURCE_ID` and the format group's
+// `isDatasetKeyedSource` — wherever the caller leaves one out.
+import { buildDataSourcesWith, resolveToolSourceWith, } from "../capture/data-sources.js";
+import { CIVIC_SOURCE_REGISTRY, UNKNOWN_SOURCE_ID, civicToolSourceResolver, isDatasetKeyedSource, } from "../format/sources.js";
+/**
+ * Resolve the MCP source for a tool call. Prefers the `mcp.source` attribute
+ * recorded on the matching `mcp_tool_call` span (the trace is the source of
+ * truth); falls back to the resolver's static mapping for packages written
+ * before source tagging or callers that ship an empty trace.
+ *
+ * Tool calls are paired to spans by index — the reference capture emits one
+ * span per call in order, so positional matching is exact in the normal
+ * flow. When the counts diverge, the static resolver still identifies the
+ * source.
+ */
+export function resolveToolSource(toolCall, span, resolver = civicToolSourceResolver, fallbackSourceId = UNKNOWN_SOURCE_ID) {
+    return resolveToolSourceWith(toolCall, span, resolver, fallbackSourceId);
+}
+/**
+ * Build the per-source evidence-package `dataSources` array.
+ *
+ * Dataset-keyed sources (Socrata) contribute one entry per unique
+ * `dataset_id` observed across tool calls that also carried a `portal`
+ * argument; a dataset-keyed call that carried no portal contributes NO
+ * entry. Aggregate sources (Data Commons, Boston OpenContext — registry
+ * entries carrying `aggregatePortalUrl`) contribute a single entry when any
+ * of their tool calls was made. Unknown source ids contribute no entry. Each
+ * entry is tagged with `sourceId` so downstream consumers can distinguish
+ * provenance. Emission order: the dataset-keyed entries (first-seen order),
+ * then aggregate sources in registry insertion order — matching the
+ * reference implementation.
+ *
+ * A call the producer recorded as FAILED (`ToolCallSummary.failed`) asserts
+ * no access and contributes nothing on either branch; it keeps its position
+ * in the walk, because calls are paired to spans by index. The walk itself,
+ * and why each branch is shaped as it is, is `buildDataSourcesWith` in
+ * capture/data-sources.ts.
+ *
+ * @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.
+ */
+export function buildDataSources(toolCalls, trace, fallbackPortal, now, options = {}) {
+    const resolver = options.resolver ?? civicToolSourceResolver;
+    const registry = options.registry ?? CIVIC_SOURCE_REGISTRY;
+    const fallbackSourceId = options.fallbackSourceId ?? UNKNOWN_SOURCE_ID;
+    return buildDataSourcesWith(toolCalls, trace, now, {
+        resolver,
+        registry,
+        fallbackSourceId,
+        isDatasetKeyed: (sourceId) => isDatasetKeyedSource(sourceId, registry),
+    });
+}