@typedstandards/civic-typed-harness 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog — @typedstandards/civic-typed-harness
+
+Factual record of what changed per published version. Section references are
+to the Typed Standards specification unless noted otherwise.
+
+## 0.1.0 — 2026-08-02
+
+Initial release: the civic **domain harness** for Typed Standards evidence
+packages — the DOMAIN side of the format/domain line drawn in
+[ADR-0021](../../docs/adr/0021-produce-core-extraction.md), relocated whole
+from the reference application and packaged per
+[ADR-0022](../../docs/adr/0022-civic-typed-harness-packaging.md). Operating
+rule: **the harness derives, the core assembles.**
+
+- **Published as `@typedstandards/civic-typed-harness`.** The package landed
+  in-repo under the working name `civic-typed-harness`, `private: true`, with
+  the final npm name deferred to the project's naming taxonomy (ADR-0022 §B).
+  The decision selected the standard's scope with the full layer-3 basename;
+  rationale, the alternatives scored, and the named reversal condition are in
+  the planning-side naming memo (`naming-research-harness-scope.md`), recorded
+  as a dated addendum to ADR-0022.
+- **Format-extension group** (`src/format/`) — the `civic:` JSON-LD namespace
+  and `urn:civic-evidence:` id scheme, the civic source registry, the datHere
+  envelope-policy derivations (producerProfile, content-canonicalization rule,
+  summary emission, the `org.civicaitools.environment` extension), and the
+  captureMethod vocabulary surface (verify-core's Q32 fallback-table entry,
+  single-sourced — flagged, not solved, here).
+- **Capture group** (`src/capture/`) — the OTel-compatible `TraceBuilder`,
+  skill-metadata extraction, data-source population, and the civic provenance
+  graph builder. Clock and RNG are permitted here only, and are injectable.
+- **Rubric group** (`src/rubric/`) — the civic six-criterion adversarial
+  evaluation core: rubric text, the Q26-pinned `RUBRIC_VERSION_SHA256`, prompt
+  builder, and response parser. The model runner and result emission stay
+  implementation-side; this module performs no I/O.
+- **Config, not constants** (ADR-0020 posture at the domain layer) — every
+  value naming a deployment (platform-agent identity/URL, MCP server URLs, the
+  environment-extension `host`, trace `service.name` and scope identity) is a
+  typed config input with the demo values exported as overridable defaults.
+- **Single declared runtime dependency: `@typedstandards/produce-core`**
+  (`^0.2.0`). The verify-core primitives the harness consumes (`sha256Hex`,
+  `isBlobRef`, the canonicalization-rule URIs, the Q32 vocabulary table and
+  the `CaptureMethod` type) are reached through produce-core 0.2.0's
+  re-exports rather than importing `@typedstandards/verify-core` directly —
+  no phantom dependency, and producer, harness, and verifier still share one
+  hashing implementation by construction (typedstandards#35 class of bug,
+  flagged in civic-ai-tools#116 P1).
+- **Purity contract (harness-grade)** — no I/O, no network, no environment
+  reads, no Node built-ins, browser-safe throughout; enforced twice, by
+  `eslint.config.mjs` and by `src/purity.test.ts`, which also enforces the
+  internal format/capture module boundary that reserves the future package
+  split (ADR-0022 §C).
+- **Byte-compatibility proof** — golden fixtures captured from the reference
+  implementation: provenance graphs and dataSources arrays reproduce
+  byte-for-byte under the demo default config, `RUBRIC_VERSION_SHA256` is
+  asserted against the exact reference digest, and a produce→verify
+  composition round-trip runs the harness output through produce-core's
+  envelope assembly and verify-core's §9.2 verification sequence.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nathan Storey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @typedstandards/civic-typed-harness
+
+The civic **domain harness** for [Typed Standards](../../docs/architecture/typed-standards-specification.md) evidence packages — the DOMAIN side of the format/domain line drawn in [ADR-0021](../../docs/adr/0021-produce-core-extraction.md), relocated from the reference app as an installable package ([ADR-0022](../../docs/adr/0022-civic-typed-harness-packaging.md)). The operating rule: **the harness derives, the core assembles** — everything here produces domain-derived values (civic vocabulary terms, datHere policy fields, provenance graphs, capture artifacts) that feed [`@typedstandards/produce-core`](https://www.npmjs.com/package/@typedstandards/produce-core)'s neutral envelope assembly.
+
+> **Name.** The package landed in-repo under the working name `civic-typed-harness` with the final npm name deferred (ADR-0022 §B). It publishes as **`@typedstandards/civic-typed-harness`** — the standard's scope with the full layer-3 basename; the rationale, the alternatives scored, and the named reversal condition are recorded in the planning-side naming memo and summarized in the [ADR-0022 addendum](../../docs/adr/0022-civic-typed-harness-packaging.md#addendum-2026-08-02--final-npm-name).
+
+## What's inside
+
+| 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-evidence:` id scheme, 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/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`.
+
+## Config, not constants
+
+Every value that names a deployment is a **typed config input**, with the civicaitools.org demo values exported as overridable defaults:
+
+| Value | Config type | Demo default export |
+|---|---|---|
+| Platform-agent identity/URL | `PlatformAgentConfig` | `CIVICAITOOLS_PLATFORM_AGENT` |
+| MCP source registry (server URLs, catalog types, display names) | `CivicSourceRegistry` | `CIVIC_SOURCE_REGISTRY` |
+| Tool-name → source-id resolver | `ToolSourceResolver` | `civicToolSourceResolver` |
+| Environment-extension `host` | `DatHereEnvironmentConfig` | `CIVICAITOOLS_ENVIRONMENT_CONFIG` |
+| Trace `service.name` / scope identity | `TraceBuilderConfig` | `CIVICAITOOLS_TRACE_CONFIG` |
+| Provenance build (all of the above + model-agent description) | `ProvenanceConfig` | `CIVICAITOOLS_PROVENANCE_CONFIG` |
+
+## 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).
+
+> **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 demo default config, `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). 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
+
+```bash
+npm install          # from the repo root (npm workspaces)
+npm test  --workspace @typedstandards/civic-typed-harness
+npm run lint  --workspace @typedstandards/civic-typed-harness
+npm run build --workspace @typedstandards/civic-typed-harness
+```

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

@@ -0,0 +1,58 @@
+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. */
+export interface ToolCallSummary {
+    name: string;
+    args: Record<string, unknown>;
+}
+interface TraceSpan {
+    name: string;
+    attributes?: Array<{
+        key: string;
+        value?: {
+            stringValue?: string;
+            intValue?: string;
+            boolValue?: boolean;
+        };
+    }>;
+}
+/** 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 `socrata` (pre-M9.1 packages predate source tagging). */
+    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. 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.
+ */
+export declare function buildDataSources(toolCalls: ToolCallSummary[], trace: Record<string, unknown>, fallbackPortal: string, now: string, options?: DataSourceOptions): DataSourceEntry[];

package/dist/capture/data-sources.js

@@ -0,0 +1,119 @@
+// Data-source population (CAPTURE group) — walks the trace's `mcp_tool_call`
+// 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.
+//
+// `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.
+        const spans = trace?.resourceSpans?.[0]?.scopeSpans?.[0]?.spans;
+        if (!Array.isArray(spans))
+            return [];
+        return spans.filter((s) => s.name === 'mcp_tool_call');
+    }
+    catch {
+        return [];
+    }
+}
+function spanAttr(span, key) {
+    if (!span)
+        return undefined;
+    const attr = span.attributes?.find((a) => a.key === key);
+    return attr?.value?.stringValue ?? attr?.value?.intValue ?? undefined;
+}
+/**
+ * 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 = FALLBACK_SOURCE_ID) {
+    return spanAttr(span, 'mcp.source')
+        ?? resolver(toolCall.name)
+        ?? fallbackSourceId;
+}
+/**
+ * Build the per-source evidence-package `dataSources` array.
+ *
+ * Dataset-keyed sources (Socrata) contribute one entry per unique
+ * `dataset_id` observed across tool calls. 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.
+ */
+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;
+    const toolSpans = getToolSpans(trace);
+    const datasetKeyed = new Map();
+    const aggregateAccessed = new Set();
+    for (let i = 0; i < toolCalls.length; i++) {
+        const tc = toolCalls[i];
+        const source = resolveToolSource(tc, toolSpans[i], resolver, fallbackSourceId);
+        if (isDatasetKeyedSource(source, registry)) {
+            const datasetId = tc.args.dataset_id;
+            const portal = tc.args.portal || fallbackPortal;
+            if (datasetId) {
+                let byDataset = datasetKeyed.get(source);
+                if (!byDataset) {
+                    byDataset = new Map();
+                    datasetKeyed.set(source, byDataset);
+                }
+                if (!byDataset.has(datasetId)) {
+                    byDataset.set(datasetId, { portalUrl: `https://${portal}`, datasetId });
+                }
+            }
+        }
+        else if (registry[source]?.aggregatePortalUrl !== undefined) {
+            aggregateAccessed.add(source);
+        }
+        // Unknown sources contribute no dataSources entry (their provenance is
+        // still visible on the PROV-O graph's tool-call activities).
+    }
+    const entries = [];
+    for (const [sourceId, info] of Object.entries(registry)) {
+        if (info.aggregatePortalUrl === undefined) {
+            const byDataset = datasetKeyed.get(sourceId);
+            if (!byDataset)
+                continue;
+            for (const { portalUrl, datasetId } of byDataset.values()) {
+                entries.push({
+                    sourceId,
+                    catalogType: info.catalogType,
+                    portalUrl,
+                    datasetId,
+                    datasetUrl: `${portalUrl}/d/${datasetId}`,
+                    accessTimestamp: now,
+                });
+            }
+        }
+        else if (aggregateAccessed.has(sourceId)) {
+            entries.push({
+                sourceId,
+                catalogType: info.catalogType,
+                portalUrl: info.aggregatePortalUrl,
+                accessTimestamp: now,
+            });
+        }
+    }
+    return entries;
+}

package/dist/capture/provenance.d.ts

@@ -0,0 +1,48 @@
+import { type ProvGraph, type ProvNode } from '@typedstandards/produce-core';
+import { 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 {
+    packageId: string;
+    promptHash: string;
+    promptText?: string;
+    /** Inline output text. Used to derive the output hash unless
+     *  `outputHash` is supplied explicitly. */
+    outputText?: string;
+    /** Pre-computed SHA-256 hex of the output. Supplied when the output is
+     *  stored as a BlobRef and inline text isn't available; the ref hash
+     *  itself is exactly this value by construction. */
+    outputHash?: string;
+    model: string;
+    portal: string;
+}
+/** Instance configuration for the graph build (config-not-constants). */
+export interface ProvenanceConfig {
+    /** Platform-agent identity — the deployment publishing the evidence. */
+    platformAgent: PlatformAgentConfig;
+    /** Source registry supplying agent titles and MCP server URLs. */
+    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. Default names the demo
+     *  deployment's model gateway. */
+    modelAgentDescription?: string;
+}
+/** Demo default: the civicaitools.org reference deployment. */
+export declare const CIVICAITOOLS_PROVENANCE_CONFIG: ProvenanceConfig;
+/**
+ * Build a W3C PROV-O JSON-LD graph from an OTel trace and package metadata.
+ *
+ * Walks the trace spans and maps them to PROV concepts:
+ * - LLM inference spans → prov:Activity
+ * - MCP tool call spans → prov:Activity
+ * - 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;

package/dist/capture/provenance.js

@@ -0,0 +1,290 @@
+// Civic 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).
+//
+// Config-not-constants: the platform-agent identity, the source-agent
+// registry (server URLs), and the model-agent description are typed config
+// inputs; `CIVICAITOOLS_PROVENANCE_CONFIG` is the demo default and
+// reproduces the reference implementation's output 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 { makeCivicProvContext, civicUrn, civicModelUrn, civicSourceAgentUrn, civicPlatformUrn, CIVICAITOOLS_PLATFORM_AGENT, } from "../format/vocabulary.js";
+import { CIVIC_SOURCE_REGISTRY, FALLBACK_SOURCE_ID, isDatasetKeyedSource, } from "../format/sources.js";
+/** Demo default: the civicaitools.org reference deployment. */
+export const CIVICAITOOLS_PROVENANCE_CONFIG = {
+    platformAgent: CIVICAITOOLS_PLATFORM_AGENT,
+    sourceRegistry: CIVIC_SOURCE_REGISTRY,
+};
+const DEFAULT_MODEL_AGENT_DESCRIPTION = 'Large language model via OpenRouter';
+// --- Helpers ---
+function getAttr(attrs, key) {
+    const attr = attrs.find(a => a.key === key);
+    return attr?.value?.stringValue ?? attr?.value?.intValue ?? undefined;
+}
+function nanoToIso(nano) {
+    const ms = Math.floor(Number(nano) / 1_000_000);
+    return new Date(ms).toISOString();
+}
+// --- Builder ---
+/**
+ * Build a W3C PROV-O JSON-LD graph from an OTel trace and package metadata.
+ *
+ * Walks the trace spans and maps them to PROV concepts:
+ * - LLM inference spans → prov:Activity
+ * - MCP tool call spans → prov:Activity
+ * - Prompt, skill guidance, data responses, output → prov:Entity
+ * - LLM model, MCP server, platform → prov:Agent
+ */
+export function buildProvenanceGraph(trace, input, config = CIVICAITOOLS_PROVENANCE_CONFIG) {
+    const otel = trace;
+    const spans = otel?.resourceSpans?.[0]?.scopeSpans?.[0]?.spans || [];
+    const { packageId, promptHash, promptText, outputText, model, portal } = 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;
+    const modelDescription = config.modelAgentDescription ?? DEFAULT_MODEL_AGENT_DESCRIPTION;
+    const graph = [];
+    // --- Entities ---
+    // User prompt
+    graph.push(makeEntityNode(civicUrn(packageId, 'prompt', promptHash), {
+        'civic:contentHash': `sha256:${promptHash}`,
+        'dcterms:description': 'User query prompt',
+        ...(promptText ? { 'prov:value': promptText } : {}),
+    }));
+    // Skill guidance (from skill_fetch span). The skill is a composition of
+    // per-source guidance, so the description is source-neutral. Per-source
+    // tool agents are emitted from the tool spans below based on which sources
+    // were actually invoked.
+    const skillSpan = spans.find(s => s.name === 'skill_fetch');
+    const skillHash = skillSpan ? getAttr(skillSpan.attributes, 'skill.text_hash') : undefined;
+    const skillServerUrl = skillSpan ? getAttr(skillSpan.attributes, 'skill.mcp_server_url') : undefined;
+    if (skillHash) {
+        graph.push(makeEntityNode(civicUrn(packageId, 'skill', skillHash), {
+            'civic:contentHash': `sha256:${skillHash}`,
+            'dcterms:description': 'Composed MCP skill guidance (system prompt)',
+        }, ['prov:Plan']));
+    }
+    // Final output
+    graph.push(makeEntityNode(civicUrn(packageId, 'output', outputHash), {
+        'civic:contentHash': `sha256:${outputHash}`,
+        'dcterms:description': 'AI-generated analysis output',
+    }));
+    // --- Agents ---
+    // LLM model
+    const modelUrn = civicModelUrn(model);
+    graph.push(makeAgentNode(modelUrn, {
+        'dcterms:title': model,
+        'dcterms:description': modelDescription,
+    }, ['prov:SoftwareAgent']));
+    // MCP server agents — one per distinct data source that appears in the
+    // trace. Tool spans carry `mcp.source`; evidence 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.
+    const toolSpans = spans.filter(s => s.name === 'mcp_tool_call');
+    const sourceAgentMap = {};
+    for (const [id, info] of Object.entries(registry)) {
+        sourceAgentMap[id] = {
+            urn: civicSourceAgentUrn(id),
+            title: info.agentTitle,
+            serverUrl: id === skillSourceId ? skillServerUrl || info.serverUrl : info.serverUrl,
+        };
+    }
+    const sourcesInTrace = new Set();
+    for (const span of toolSpans) {
+        const source = getAttr(span.attributes, 'mcp.source') || fallbackSourceId;
+        sourcesInTrace.add(source);
+    }
+    for (const sourceId of sourcesInTrace) {
+        const meta = sourceAgentMap[sourceId] ?? {
+            urn: civicSourceAgentUrn(encodeURIComponent(sourceId)),
+            title: `${sourceId} MCP Server`,
+            serverUrl: sourceId,
+        };
+        graph.push(makeAgentNode(meta.urn, {
+            'dcterms:title': meta.title,
+            'civic:serverUrl': meta.serverUrl,
+            'civic: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.)
+    function agentUrnForSource(sourceId) {
+        const id = sourceId || fallbackSourceId;
+        return (sourceAgentMap[id]?.urn
+            ?? sourceAgentMap[fallbackSourceId]?.urn
+            ?? civicSourceAgentUrn(encodeURIComponent(id)));
+    }
+    // Platform
+    graph.push(makeAgentNode(civicPlatformUrn(config.platformAgent.id), {
+        'dcterms:title': config.platformAgent.title,
+        'civic:url': config.platformAgent.url,
+    }, ['prov:SoftwareAgent']));
+    // --- Activities ---
+    // LLM inference spans
+    const inferenceSpans = spans.filter(s => s.name === 'llm_inference');
+    const inferenceUrns = [];
+    for (const span of inferenceSpans) {
+        const spanUrn = civicUrn(packageId, 'inference', span.spanId);
+        inferenceUrns.push(spanUrn);
+        const used = [provRef(civicUrn(packageId, 'prompt', promptHash))];
+        if (skillHash) {
+            used.push(provRef(civicUrn(packageId, 'skill', skillHash)));
+        }
+        const promptTokens = getAttr(span.attributes, 'gen_ai.response.prompt_tokens');
+        const completionTokens = getAttr(span.attributes, 'gen_ai.response.completion_tokens');
+        graph.push(makeActivityNode(spanUrn, {
+            'dcterms:description': `LLM inference call (iteration ${getAttr(span.attributes, 'gen_ai.inference_index') || '0'})`,
+            ...provWasAssociatedWith(modelUrn),
+            'prov:used': used,
+            ...(span.startTimeUnixNano
+                ? { 'prov:startedAtTime': xsdDateTime(nanoToIso(span.startTimeUnixNano)) }
+                : {}),
+            ...(span.endTimeUnixNano
+                ? { 'prov:endedAtTime': xsdDateTime(nanoToIso(span.endTimeUnixNano)) }
+                : {}),
+            ...(promptTokens ? { 'civic:promptTokens': Number(promptTokens) } : {}),
+            ...(completionTokens ? { 'civic:completionTokens': Number(completionTokens) } : {}),
+        }));
+    }
+    // MCP tool call spans
+    const dataResponseUrns = [];
+    for (const span of toolSpans) {
+        const toolCallUrn = civicUrn(packageId, 'tool-call', span.spanId);
+        const argsStr = getAttr(span.attributes, 'tool.arguments') || '{}';
+        const queryHash = hash(argsStr);
+        const responseHash = getAttr(span.attributes, 'tool.response_hash');
+        const toolName = getAttr(span.attributes, 'tool.name') || 'get_data';
+        const opType = getAttr(span.attributes, 'tool.operation_type') || 'unknown';
+        const datasetId = getAttr(span.attributes, 'tool.dataset_id');
+        const portalDomain = getAttr(span.attributes, 'tool.portal_domain') || portal;
+        const toolSource = getAttr(span.attributes, 'mcp.source') || fallbackSourceId;
+        const toolAgentUrn = agentUrnForSource(toolSource);
+        const toolSourceDatasetKeyed = isDatasetKeyedSource(toolSource, registry);
+        // Query entity (tool arguments). Find the most recent inference span
+        // before this tool call to link as generator.
+        const toolStart = Number(span.startTimeUnixNano);
+        const precedingInference = inferenceSpans
+            .filter(is => Number(is.endTimeUnixNano || '0') <= toolStart)
+            .sort((a, b) => Number(b.endTimeUnixNano || '0') - Number(a.endTimeUnixNano || '0'))[0];
+        const queryUrn = civicUrn(packageId, 'query', queryHash);
+        graph.push(makeEntityNode(queryUrn, {
+            'civic:contentHash': `sha256:${queryHash}`,
+            'civic:toolName': toolName,
+            'civic:operationType': opType,
+            'dcterms:description': `MCP tool arguments (${opType})`,
+            ...(precedingInference
+                ? provWasGeneratedBy(civicUrn(packageId, 'inference', precedingInference.spanId))
+                : {}),
+        }));
+        // Data response entity
+        if (responseHash) {
+            const dataUrn = civicUrn(packageId, 'data', responseHash);
+            dataResponseUrns.push(dataUrn);
+            // Description varies by source — dataset-keyed sources (Socrata) have
+            // a portal domain; aggregate/unknown sources are described by their
+            // agent title.
+            const description = toolSourceDatasetKeyed
+                ? `Data response from ${portalDomain}`
+                : `Data response from ${sourceAgentMap[toolSource]?.title || toolSource}`;
+            const responseRows = getAttr(span.attributes, 'tool.response_rows');
+            graph.push(makeEntityNode(dataUrn, {
+                'civic:contentHash': `sha256:${responseHash}`,
+                'dcterms:description': description,
+                'civic:sourceId': toolSource,
+                ...provWasGeneratedBy(toolCallUrn),
+                // Croissant 1.1 placeholder — only meaningful for dataset-keyed
+                // sources today.
+                ...(toolSourceDatasetKeyed && datasetId
+                    ? {
+                        'civic:datasetId': datasetId,
+                        'civic:portalDomain': portalDomain,
+                        'civic:datasetUrl': `https://${portalDomain}/d/${datasetId}`,
+                        'civic:croissantMetadataUrl': null, // hook for future Croissant integration
+                    }
+                    : {}),
+                ...(responseRows ? { 'civic:responseRows': Number(responseRows) } : {}),
+            }));
+        }
+        // Tool call activity — associated with the MCP source agent that handled
+        // the call. In multi-source analyses each call may target a different
+        // agent (e.g. socrata for `get_data`, data-commons for `get_observations`).
+        const durationMs = getAttr(span.attributes, 'tool.duration_ms');
+        graph.push(makeActivityNode(toolCallUrn, {
+            'dcterms:description': `MCP tool call: ${toolName} (${opType})`,
+            'civic:sourceId': toolSource,
+            ...provUsed([queryUrn]),
+            ...provWasAssociatedWith(toolAgentUrn),
+            ...(span.startTimeUnixNano
+                ? { 'prov:startedAtTime': xsdDateTime(nanoToIso(span.startTimeUnixNano)) }
+                : {}),
+            ...(span.endTimeUnixNano
+                ? { 'prov:endedAtTime': xsdDateTime(nanoToIso(span.endTimeUnixNano)) }
+                : {}),
+            ...(durationMs ? { 'civic:durationMs': Number(durationMs) } : {}),
+        }));
+    }
+    // --- Final output relationships ---
+    // Output wasGeneratedBy the last inference or synthesis span
+    const synthesisSpan = spans.find(s => s.name === 'synthesis');
+    const lastInference = inferenceSpans.length > 0
+        ? inferenceSpans[inferenceSpans.length - 1]
+        : undefined;
+    const generatorSpan = synthesisSpan || lastInference;
+    if (generatorSpan) {
+        const generatorUrn = synthesisSpan
+            ? civicUrn(packageId, 'synthesis', synthesisSpan.spanId)
+            : civicUrn(packageId, 'inference', generatorSpan.spanId);
+        // Add synthesis activity if it exists
+        if (synthesisSpan) {
+            graph.push(makeActivityNode(generatorUrn, {
+                'dcterms:description': 'Output synthesis',
+                ...provWasAssociatedWith(modelUrn),
+                ...(synthesisSpan.startTimeUnixNano
+                    ? { 'prov:startedAtTime': xsdDateTime(nanoToIso(synthesisSpan.startTimeUnixNano)) }
+                    : {}),
+                ...(synthesisSpan.endTimeUnixNano
+                    ? { 'prov:endedAtTime': xsdDateTime(nanoToIso(synthesisSpan.endTimeUnixNano)) }
+                    : {}),
+            }));
+        }
+        // Output wasGeneratedBy
+        graph.push(makeEntityNode(civicUrn(packageId, 'output', outputHash), {
+            ...provWasGeneratedBy(generatorUrn),
+            ...(dataResponseUrns.length > 0
+                ? provWasDerivedFrom(dataResponseUrns)
+                : {}),
+        }));
+    }
+    // Add data responses to inference used list (inference used data to synthesize)
+    if (dataResponseUrns.length > 0 && inferenceUrns.length > 0) {
+        const lastInferenceUrn = inferenceUrns[inferenceUrns.length - 1];
+        const existing = graph.find(n => n['@id'] === lastInferenceUrn);
+        if (existing && Array.isArray(existing['prov:used'])) {
+            for (const dUrn of dataResponseUrns) {
+                existing['prov:used'].push(provRef(dUrn));
+            }
+        }
+    }
+    // --- Skill hadPlan relationship ---
+    if (skillHash && inferenceUrns.length > 0) {
+        graph.push(makeActivityNode(inferenceUrns[0], {
+            'prov:qualifiedAssociation': {
+                '@type': 'prov:Association',
+                'prov:agent': provRef(modelUrn),
+                'prov:hadPlan': provRef(civicUrn(packageId, 'skill', skillHash)),
+            },
+        }));
+    }
+    return makeProvGraph(makeCivicProvContext(), graph);
+}