@typedstandards/civic-typed-harness 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,57 @@
 Factual record of what changed per published version. Section references are
 to the Typed Standards specification unless noted otherwise.
 
+## 0.3.1 — 2026-09-02
+
+**The graph states what the span carried, and states absence as absence**
+([civic-ai-tools-website#384](https://github.com/npstorey/civic-ai-tools-website/issues/384),
+Wave N9 P-H1). Patch, not breaking: no existing export is removed or
+retyped, and every golden byte — both vocabulary eras, all eight
+golden-reproduction cases — is unchanged.
+
+- **`buildProvenanceGraph` no longer invents a tool name.** An
+  `mcp_tool_call` span with no `tool.name` yields a query entity with no
+  `civic:toolName` key (omitted, not placeholdered) and a tool-call activity
+  described as `MCP tool call (<operation type>)`. Previously the builder
+  substituted `get_data`.
+- **`buildProvenanceGraph` no longer attributes a data response to the run's
+  portal.** `civic:portalDomain` and `civic:datasetUrl` are emitted only when
+  the span carried both `tool.portal_domain` and `tool.dataset_id`. A
+  dataset-keyed span with no portal is described by its source agent's
+  registry title (`Data response from Socrata MCP Server`), the form
+  aggregate and unknown sources already took; a span with a dataset id and
+  no portal states `civic:datasetId` and mints no URL. Previously the builder
+  substituted `ProvenanceInput.portal` — the run's selected portal — which
+  attributed every `search` and `fetch` response to a portal the call never
+  addressed (the Socrata server's `search` and `fetch` take no portal and
+  answer from the portal that server is configured for). The graph does not
+  parse tool arguments: a portal embedded in a `fetch` id is not a portal the
+  span carried.
+- **`buildDataSources` no longer mints an entry on `fallbackPortal`.** A
+  dataset-keyed call whose arguments carry `dataset_id` but no `portal`
+  contributes no `dataSources` entry — `DataSourceEntry.portalUrl` is a
+  required string in produce-core, so an entry with no portal is not a shape
+  this package can emit — and the call remains on the graph's tool-call
+  activities. Calls that carry a portal (every `get_data` call from the
+  reference producer, whose loop injects the run portal before the record is
+  built) are unchanged.
+- **Unchanged signatures, two inputs now unused.** `ProvenanceInput.portal`
+  and the `fallbackPortal` parameter of `buildDataSources` keep their exact
+  types and positions, are accepted, and are not consulted; both say so at
+  the declaration.
+- **Byte consequence.** A package produced by this version from a trace
+  whose tool spans all carry `tool.name`, and carry `tool.portal_domain`
+  wherever they carry a response hash, is byte-identical to one produced by
+  0.3.0. Where a span carried less, the 0.3.0 output asserted a value the
+  span did not, and this version's output differs from it by exactly that
+  assertion. Packages already signed under 0.3.0 are untouched and remain
+  verifiable exactly as published.
+- **Dependency range widened, nothing resolved differently.**
+  `@typedstandards/produce-core` is accepted at `^0.3.0 || ^0.4.0` so a
+  consumer that takes produce-core 0.4.0 (an additive minor) resolves one
+  copy rather than nesting a second under this package. The lockfile here
+  still resolves 0.3.0.
+
 ## 0.3.0 — 2026-08-20
 
 **Settlement-era civic vocabulary + produce-core 0.3.0**

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

@@ -47,12 +47,18 @@ export declare function resolveToolSource(toolCall: ToolCallSummary, span: Trace
  * 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,
+ * `dataset_id` observed across tool calls that also carried a `portal`
+ * argument; a dataset-keyed call that carried no portal contributes NO
+ * entry (the loop body says why). 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.
+ *
+ * `fallbackPortal` is accepted and NOT consulted since 0.3.1: an entry
+ * states the portal the call carried, never the run's. The parameter stays
+ * in the signature so existing callers keep compiling.
  */
 export declare function buildDataSources(toolCalls: ToolCallSummary[], trace: Record<string, unknown>, fallbackPortal: string, now: string, options?: DataSourceOptions): DataSourceEntry[];

package/dist/capture/data-sources.js

@@ -51,13 +51,19 @@ export function resolveToolSource(toolCall, span, resolver = civicToolSourceReso
  * 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,
+ * `dataset_id` observed across tool calls that also carried a `portal`
+ * argument; a dataset-keyed call that carried no portal contributes NO
+ * entry (the loop body says why). 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.
+ *
+ * `fallbackPortal` is accepted and NOT consulted since 0.3.1: an entry
+ * states the portal the call carried, never the run's. The parameter stays
+ * in the signature so existing callers keep compiling.
  */
 export function buildDataSources(toolCalls, trace, fallbackPortal, now, options = {}) {
     const resolver = options.resolver ?? civicToolSourceResolver;
@@ -71,8 +77,20 @@ export function buildDataSources(toolCalls, trace, fallbackPortal, now, options
         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) {
+            const portal = tc.args.portal;
+            // An entry is minted only from what the call carried: a dataset id AND
+            // a portal. A dataset-keyed call with a dataset id and no portal
+            // contributes no entry. `DataSourceEntry.portalUrl` is a required
+            // string (produce-core), so "an entry with no portal" is not a shape
+            // this package can emit; and substituting the run's portal
+            // (`fallbackPortal`, before 0.3.1) attributed the call to a portal it
+            // never addressed. Omission is the honest shape — the call is still on
+            // the PROV-O graph's tool-call activities, stated without a portal.
+            // The branch is latent for the reference producer, whose loop injects
+            // the run portal into `get_data` arguments before the record is built
+            // (run-tool-loop.ts:799 at the time of writing); any caller whose
+            // summary carries `dataset_id` without `portal` reaches it.
+            if (datasetId && portal) {
                 let byDataset = datasetKeyed.get(source);
                 if (!byDataset) {
                     byDataset = new Map();

package/dist/capture/provenance.d.ts

@@ -15,6 +15,12 @@ export interface ProvenanceInput {
      *  itself is exactly this value by construction. */
     outputHash?: string;
     model: string;
+    /** The run's selected portal. Accepted and NOT consulted by the graph
+     *  builder since 0.3.1: the graph states the portal a tool span carried
+     *  (`tool.portal_domain`) and states absence as absence — it never
+     *  substitutes the run's portal for one the call did not address. The
+     *  field stays in the type so callers that pass it (the reference app
+     *  does, as an object literal) keep compiling. */
     portal: string;
 }
 /** Instance configuration for the graph build (config-not-constants). */
@@ -45,7 +51,9 @@ export interface ProvenanceConfig {
     vocabulary?: CivicVocabulary;
 }
 /** The civicaitools.org reference deployment's values. Passed explicitly by
- *  the reference app — never applied as a default. */
+ *  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.

package/dist/capture/provenance.js

@@ -20,7 +20,9 @@ import { hash } from "./trace.js";
 import { CIVIC_VOCABULARY, CIVICAITOOLS_PLATFORM_AGENT, } 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. */
+ *  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,
@@ -48,7 +50,8 @@ function nanoToIso(nano) {
 export function buildProvenanceGraph(trace, input, config) {
     const otel = trace;
     const spans = otel?.resourceSpans?.[0]?.scopeSpans?.[0]?.spans || [];
-    const { packageId, promptHash, promptText, outputText, model, portal } = input;
+    // `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;
@@ -167,17 +170,34 @@ export function buildProvenanceGraph(trace, input, config) {
             ...(completionTokens ? { 'civic:completionTokens': Number(completionTokens) } : {}),
         }));
     }
-    // MCP tool call spans
+    // MCP tool call spans.
+    //
+    // Every node derived from a span states what the span carried, and states
+    // absence as absence: a span with no `tool.name` yields nodes that name no
+    // tool, and a span with no `tool.portal_domain` yields a data response
+    // attributed to no portal. Nothing here substitutes the run's selected
+    // portal (`input.portal`, accepted and unused since 0.3.1) or a default
+    // tool name for a value the producer did not write. The reference
+    // producer's loop always writes `tool.name`, and writes
+    // `tool.portal_domain` only when the call's arguments carried a portal —
+    // which its portal injection does for `get_data` and for no other tool.
+    // The Socrata server's `search` (one argument, `query`) and `fetch` (one
+    // argument, `id`) address the portal that server is configured for, which
+    // the producer does not know. A `fetch` id may embed a portal, but that
+    // grammar belongs to the server: the graph does not parse arguments, so an
+    // id is never a portal the span carried.
     const dataResponseUrns = [];
     for (const span of toolSpans) {
         const toolCallUrn = vocab.urn(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';
+        // Absent when the span carried none — never defaulted.
+        const toolName = getAttr(span.attributes, 'tool.name');
         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;
+        // 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 toolAgentUrn = agentUrnForSource(toolSource);
         const toolSourceDatasetKeyed = isDatasetKeyedSource(toolSource, registry);
@@ -190,7 +210,8 @@ export function buildProvenanceGraph(trace, input, config) {
         const queryUrn = vocab.urn(packageId, 'query', queryHash);
         graph.push(makeEntityNode(queryUrn, {
             'civic:contentHash': `sha256:${queryHash}`,
-            'civic:toolName': toolName,
+            // Omitted — not placeholdered — when the span named no tool.
+            ...(toolName ? { 'civic:toolName': toolName } : {}),
             'civic:operationType': opType,
             'dcterms:description': `MCP tool arguments (${opType})`,
             ...(precedingInference
@@ -201,10 +222,20 @@ export function buildProvenanceGraph(trace, input, config) {
         if (responseHash) {
             const dataUrn = vocab.urn(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
+            // Description: the portal the span carried, when it carried one;
+            // otherwise the agent that answered the call, by its registry title —
+            // the form aggregate and unknown sources already take. A dataset-keyed
+            // source whose span carried a dataset id but no portal takes the
+            // agent-title form too, with the dataset id stated below as
+            // `civic:datasetId` and no URL minted (a dataset URL needs a host the
+            // span did not carry). That branch is latent by construction for the
+            // reference producer — its loop injects the run portal into `get_data`
+            // arguments before the span opens (run-tool-loop.ts:799 at the time of
+            // writing), and `get_data` is the only tool whose arguments carry a
+            // dataset id — but any producer that writes `tool.dataset_id` without
+            // `tool.portal_domain` reaches it, so it is stated honestly rather
+            // than left dead.
+            const description = toolSourceDatasetKeyed && portalDomain
                 ? `Data response from ${portalDomain}`
                 : `Data response from ${sourceAgentMap[toolSource]?.title || toolSource}`;
             const responseRows = getAttr(span.attributes, 'tool.response_rows');
@@ -214,12 +245,18 @@ export function buildProvenanceGraph(trace, input, config) {
                 'civic:sourceId': toolSource,
                 ...provWasGeneratedBy(toolCallUrn),
                 // Croissant 1.1 placeholder — only meaningful for dataset-keyed
-                // sources today.
+                // sources today. The dataset id is stated whenever the span carried
+                // one; the portal and the dataset URL only when the span carried
+                // the portal as well. Key order is the byte contract.
                 ...(toolSourceDatasetKeyed && datasetId
                     ? {
                         'civic:datasetId': datasetId,
-                        'civic:portalDomain': portalDomain,
-                        'civic:datasetUrl': `https://${portalDomain}/d/${datasetId}`,
+                        ...(portalDomain
+                            ? {
+                                'civic:portalDomain': portalDomain,
+                                'civic:datasetUrl': `https://${portalDomain}/d/${datasetId}`,
+                            }
+                            : {}),
                         'civic:croissantMetadataUrl': null, // hook for future Croissant integration
                     }
                     : {}),
@@ -231,7 +268,10 @@ export function buildProvenanceGraph(trace, input, config) {
         // 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})`,
+            // Names the tool only when the span did.
+            'dcterms:description': toolName
+                ? `MCP tool call: ${toolName} (${opType})`
+                : `MCP tool call (${opType})`,
             'civic:sourceId': toolSource,
             ...provUsed([queryUrn]),
             ...provWasAssociatedWith(toolAgentUrn),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typedstandards/civic-typed-harness",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Civic-domain harness for Typed Standards evidence packages — the DOMAIN layer of the ADR-0021 format/domain line: civic PROV-O vocabulary and provenance builder, datHere envelope-policy derivations, and the capture machinery (trace builder, skill-metadata extraction, data-source population, adversarial rubric core). Derives; @typedstandards/produce-core assembles.",
   "license": "MIT",
   "author": "Nathan Storey",
@@ -33,7 +33,7 @@
     "prepublishOnly": "npm run clean && npm run build"
   },
   "dependencies": {
-    "@typedstandards/produce-core": "^0.3.0"
+    "@typedstandards/produce-core": "^0.3.0 || ^0.4.0"
   },
   "devDependencies": {
     "@typedstandards/verify-core": "^0.9.0",