@typedstandards/civic-typed-harness 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,206 @@
 Factual record of what changed per published version. Section references are
 to the Typed Standards specification unless noted otherwise.
 
+## 0.4.0 — 2026-09-04
+
+Minor: two optional input fields are added and no existing export is removed
+or retyped. `fallbackPortal` and `ProvenanceInput.portal`, inert since 0.3.1,
+are widened and deprecated rather than dropped — removing either is breaking
+and waits for a major.
+
+**What this release claims about golden bytes, and what it does not.** Every
+golden byte is unchanged — both vocabulary eras, all eight
+golden-reproduction cases, and `__fixtures__/website-golden.json`. That
+sentence has appeared in every release note since 0.3.0, and it is narrower
+than it reads: **`__fixtures__/reference-golden.json` carries no spans at
+all** — `spanId` and `scopeSpans` each occur zero times across its eight
+cases, whose traces are empty `resourceSpans` arrays or BlobRefs. So those
+eight cases are green for anything the tool-span loop does, including the
+rejection marker this release adds, and their green is not evidence about it.
+
+`website-golden.json` is the only golden fixture that exercises span-derived
+output: five tool-call activities and four data-response descriptions. It is
+the fixture that proves this release's byte-stability claim, and the one the
+conditional spread of `civic:failed` was measured against — driven red by
+making that spread unconditional, which moves it. Read
+[civic-ai-tools#199](https://github.com/npstorey/civic-ai-tools/issues/199)
+before citing a green golden suite as evidence about the graph builder.
+
+**The reader-facing source name is measured, not changed**
+([civic-ai-tools#194](https://github.com/npstorey/civic-ai-tools/issues/194),
+Wave N10 P-H3). Tests only: no exported behaviour changes, and every golden
+byte — both vocabulary eras, all eight golden-reproduction cases — is
+unchanged.
+
+- **The change #194 asks for moves frozen golden bytes.** A data response the
+  builder cannot describe by a portal is described by its source's registry
+  `agentTitle` (`Data response from Socrata MCP Server`) — the agent's title,
+  implementation language on a reader-facing surface. Reading the registry's
+  `displayName` instead — the reader-facing name, in the registry beside
+  `agentTitle` since the package's first release — is a one-expression change,
+  and it rewrites two lines inside `__fixtures__/website-golden.json`'s
+  captured graph: the data-commons and boston-opencontext data responses, both
+  on the agent-title branch. Three whole-graph byte-parity assertions read
+  those two lines. A golden fixture is never edited to match new behaviour, so
+  the change waits on a decision about whether those bytes move.
+- **The vocabulary era cannot carry it.** `CivicVocabulary` binds exactly two
+  literals — the `civic:` namespace and the id-scheme prefix
+  (`makeCivicVocabulary(ns, urnPrefix)`) — and both era suites assert the two
+  eras differ by those and by nothing else. A description's wording is neither
+  of them and is not era-scoped: the same prefix is emitted under both eras, so
+  gating it on the era would make prior-era reproduction and settlement-era
+  emission disagree about a reader's wording rather than about an identifier.
+- **Two instruments, both able to fail.** `provenance.test.ts` now pins the
+  agent node's `dcterms:title` to the registry `agentTitle` — those are signed
+  bytes in both golden fixtures and the one thing that does not move under
+  either decision — and names the two golden descriptions at stake, asserting
+  each reads by agent title today and *not* by display name. The sources they
+  drive all carry two distinct registry names, which is what makes the
+  assertions able to fail; a builder changed under either one turns it red.
+- **What holds still either way.** The portal branch
+  (`Data response from data.cityofnewyork.us`) and the unknown-source fallback
+  (`Data response from euro stat`, the raw source id) move under neither
+  decision.
+
+**The PROV-O activity for a rejected call says it was rejected**
+([civic-ai-tools#193](https://github.com/npstorey/civic-ai-tools/issues/193),
+Wave N10 P-H2). Additive: no existing export is removed or retyped, and every
+golden byte — both vocabulary eras, all eight golden-reproduction cases — is
+unchanged.
+
+- **Two new activity terms.** `CIVIC_TERM_FAILED` (`civic:failed`) and
+  `CIVIC_TERM_FAILURE_KIND` (`civic:failureKind`) are declared in
+  `src/format/vocabulary.ts` and exported from the package root. A `civic:`
+  property name is vocabulary as much as the namespace it hangs under, so the
+  capture-side builder imports them rather than spelling them; `purity.test.ts`
+  now lists both, which is what makes that a claim able to fail.
+- **`buildProvenanceGraph` reads the span's failure.** A tool span the producer
+  ended with the boolean `error: true` yields a tool-call activity carrying
+  `civic:failed: true`, and `civic:failureKind` with the span's `error.kind`
+  verbatim when it carried one. Previously the builder read nine `tool.*` /
+  `mcp.*` attributes and never asked about the outcome, so a call the source
+  REFUSED and one that answered were the same node with the same description —
+  and, a rejected call having no response hash, the absent data-response entity
+  was the only trace of the rejection in the graph. `error.kind` is the one
+  attribute name across this package and the reference producer.
+- **`error` is the assertion, `error.kind` only a label on one.** A span
+  carrying a kind and no assertion is not a rejection and yields neither key —
+  the posture `ToolCallSummary.failed` / `failureKind` already takes.
+- **A new boolean attribute reader.** The module's string attribute reader
+  returns `stringValue ?? intValue` and cannot see `boolValue` at all, so it
+  returned `undefined` for a span that really did record a rejection.
+  `getBoolAttr` is a separate, strictly-typed reader rather than a widening of
+  the string one: the nine attributes that reader serves are strings by
+  contract, and a truthiness test would read the string `"false"` as an
+  assertion of failure. Only the boolean `true` marks an activity.
+- **The description states no cause.** `dcterms:description` is byte-unchanged
+  — it states what the call WAS, and the marker states how it ended. The
+  classified kind is the only cause the graph will ever carry: the reference
+  producer stopped writing a rejection's raw text onto the span in this same
+  wave, and the builder does not read it back in one layer up.
+- **Byte consequence.** Both terms are spread conditionally and appended after
+  every key the activity already carried, exactly as `civic:durationMs` is. A
+  span that recorded no rejection yields the 0.3.1 key list in the 0.3.1 order,
+  and `civic:failed: false` is never emitted — a producer that stated "not
+  failed" and one that stated nothing must read the same, which is what makes a
+  marker that IS present mean something. A rejected span carries no
+  `tool.duration_ms` from the reference producer today
+  ([civic-ai-tools-website#413](https://github.com/npstorey/civic-ai-tools-website/issues/413)),
+  so `civic:durationMs` does not fire beside the two new keys.
+
+**A call the record states as failed asserts no access**
+([civic-ai-tools#192](https://github.com/npstorey/civic-ai-tools/issues/192),
+Wave N10 P-H1). Additive: no existing export is removed, no existing caller
+changes, and every golden byte — both vocabulary eras, all eight
+golden-reproduction cases — is unchanged.
+
+- **`ToolCallSummary` can see the rejection.** Two new OPTIONAL fields:
+  `failed?: boolean`, the producer's assertion that the source rejected this
+  call, and `failureKind?: string`, the producer's own open label for why.
+  The harness never interprets the label, and `buildDataSources` never reads
+  it — `failed` is the assertion, `failureKind` only a label on one. A
+  summary carrying neither is exactly the 0.3.1 shape, and absence means
+  "not recorded as failed", never "succeeded".
+- **`buildDataSources` mints nothing from a rejected call.** A call whose
+  summary carries `failed: true` contributes no dataset-keyed entry for the
+  dataset it never read, and marks no aggregate source accessed. Previously
+  the population could not see the failure at all, so a rejected call minted
+  its dataset's entry and, on an aggregate source, marked that source
+  accessed at a timestamp — inside the bytes a publisher signs. The rejected
+  call keeps its POSITION in the walk (calls pair to spans by index), and it
+  remains on the PROV-O graph's tool-call activities and in the caller's own
+  `queries[]`. A source with any non-rejected call is still accessed; a
+  dataset a successful call also read still gets its entry.
+- **The two inert inputs are marked deprecated, not removed.**
+  `buildDataSources`'s `fallbackPortal` — accepted and not consulted since
+  0.3.1 — now also accepts `undefined`, so a caller that has stopped
+  consulting it can stop supplying a value; it stays third of five positional
+  parameters, because dropping a positional parameter is breaking.
+  `ProvenanceInput.portal` becomes optional and carries `@deprecated`;
+  removing it outright would make the reference app's object literal an
+  excess-property error. Both removals wait for a major.
+- **Byte consequence.** A package built from a record that states no failure
+  is byte-identical to one built by 0.3.1 — the walk reaches the new branch
+  only when a summary carries `failed: true`. A package built from a record
+  that DOES state a failure loses the `dataSources` entries that failure
+  never earned; that is the defect being fixed, and the wave re-emits
+  nothing.
+- **Type-level gate.** `src/capture/data-sources.assert.ts` pins the shape at
+  compile time. `tsconfig.json` excludes `src/**/*.test.ts`, so the suite
+  type-checks nothing — a test can drive a field the type does not have and
+  `npm run typecheck` stays green.
+
+## 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.assert.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/capture/data-sources.assert.js

@@ -0,0 +1,37 @@
+// Type-level acceptance gate for the 0.4.0 additive change (civic-ai-tools#192):
+// `ToolCallSummary` can see a rejection the producer recorded, and BOTH new
+// fields are OPTIONAL — a caller that records no outcome passes neither and
+// compiles exactly as it did at 0.3.1.
+//
+// Why a file rather than a test: `tsconfig.json` EXCLUDES `src/**/*.test.ts`,
+// so the suite type-checks nothing. A test can drive a field the type does not
+// have and `npm run typecheck` stays green — which is exactly what happened
+// while this phase's red instrument was the only thing pinning the shape. The
+// type is pinned here instead, mirroring `src/required-config.assert.ts`.
+//
+// Compile-time only: nothing here is exported, and the guard is never invoked.
+import { buildDataSources } from "./data-sources.js";
+function pinsToolCallSummaryShape() {
+    // The 0.3.1 shape is still a ToolCallSummary — both new fields are optional.
+    const unrecorded = { name: 'get_data', args: {} };
+    // A recorded outcome is expressible, with or without a producer label.
+    const rejected = { name: 'get_data', args: {}, failed: true };
+    const succeeded = { name: 'get_data', args: {}, failed: false };
+    const labelled = {
+        name: 'get_data',
+        args: {},
+        failed: true,
+        failureKind: 'unavailable',
+    };
+    // @ts-expect-error #192 — `failed` is the producer's boolean assertion, never a string
+    const wrongFailedType = { name: 'get_data', args: {}, failed: 'yes' };
+    // @ts-expect-error #192 — `failureKind` is an open producer label (string), never a flag
+    const wrongKindType = { name: 'get_data', args: {}, failureKind: true };
+    // `fallbackPortal` stays positional third of five for callers that still
+    // pass it, and since 0.4.0 accepts `undefined` from callers that do not.
+    buildDataSources([unrecorded, rejected, succeeded, labelled], trace, 'portal.example', 'now');
+    buildDataSources([unrecorded], trace, undefined, 'now');
+    void wrongFailedType;
+    void wrongKindType;
+}
+void pinsToolCallSummaryShape;

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

@@ -6,6 +6,22 @@ export type { DataSourceEntry };
 export interface ToolCallSummary {
     name: string;
     args: Record<string, unknown>;
+    /** Did the producer record this call as REJECTED by the source? A call
+     *  recorded as failed asserts no access: it contributes no dataset-keyed
+     *  entry and marks no aggregate source accessed (see `buildDataSources`).
+     *
+     *  Optional, and absent is absent: a producer that records no outcome
+     *  passes neither this nor `failureKind`, and gets exactly the entries it
+     *  got before the fields existed. Absence means "not recorded as failed",
+     *  never "succeeded". Added 0.4.0. */
+    failed?: boolean;
+    /** The producer's own label for why the call was rejected, carried so a
+     *  caller can hand its record through unchanged. An open string with no
+     *  normative vocabulary: the harness never interprets it, and this module
+     *  never reads it. `failed` is the assertion and `failureKind` only a label
+     *  on one — a summary carrying a kind but no `failed` is not treated as a
+     *  rejection. Added 0.4.0. */
+    failureKind?: string;
 }
 interface TraceSpan {
     name: string;
@@ -47,12 +63,29 @@ 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.
+ *
+ * A call the producer recorded as FAILED (`ToolCallSummary.failed`) asserts
+ * no access and contributes nothing on either branch: no dataset-keyed entry
+ * for a dataset it never read, and no accessed-marking of its aggregate
+ * source. It keeps its POSITION in the walk, because calls are paired to
+ * spans by index. The call is still on the PROV-O graph's tool-call
+ * 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.
  */
-export declare function buildDataSources(toolCalls: ToolCallSummary[], trace: Record<string, unknown>, fallbackPortal: string, now: string, options?: DataSourceOptions): DataSourceEntry[];
+export declare function buildDataSources(toolCalls: ToolCallSummary[], trace: Record<string, unknown>, fallbackPortal: string | undefined, now: string, options?: DataSourceOptions): DataSourceEntry[];

package/dist/capture/data-sources.js

@@ -51,13 +51,30 @@ 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.
+ *
+ * A call the producer recorded as FAILED (`ToolCallSummary.failed`) asserts
+ * no access and contributes nothing on either branch: no dataset-keyed entry
+ * for a dataset it never read, and no accessed-marking of its aggregate
+ * source. It keeps its POSITION in the walk, because calls are paired to
+ * spans by index. The call is still on the PROV-O graph's tool-call
+ * 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.
  */
 export function buildDataSources(toolCalls, trace, fallbackPortal, now, options = {}) {
     const resolver = options.resolver ?? civicToolSourceResolver;
@@ -68,11 +85,29 @@ export function buildDataSources(toolCalls, trace, fallbackPortal, now, options
     const aggregateAccessed = new Set();
     for (let i = 0; i < toolCalls.length; i++) {
         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]`,
+        // 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 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,7 +15,17 @@ export interface ProvenanceInput {
      *  itself is exactly this value by construction. */
     outputHash?: string;
     model: string;
-    portal: 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.
+     *
+     *  @deprecated Inert since 0.3.1 and optional since 0.4.0 — a caller that
+     *  has stopped consulting it should stop passing it. The field stays in
+     *  the type so callers that do pass it (the reference app does, as an
+     *  object literal) keep compiling; removing it outright would make that
+     *  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 {
@@ -45,7 +55,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

@@ -17,10 +17,12 @@
 // 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, } from "../format/vocabulary.js";
+import { CIVIC_VOCABULARY, CIVICAITOOLS_PLATFORM_AGENT, CIVIC_TERM_FAILED, CIVIC_TERM_FAILURE_KIND, } 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,
@@ -31,6 +33,30 @@ function getAttr(attrs, key) {
     const attr = attrs.find(a => a.key === key);
     return attr?.value?.stringValue ?? attr?.value?.intValue ?? undefined;
 }
+/**
+ * Read an attribute the producer wrote as a BOOLEAN.
+ *
+ * `getAttr` above returns `stringValue ?? intValue` and cannot see the third
+ * OTel value shape at all — `TraceBuilder` encodes a boolean as
+ * `{ boolValue }` (trace.ts), so `getAttr(attrs, 'error')` returns `undefined`
+ * for a span the producer really did end with `error: true`. This is a
+ * separate reader rather than a widening of `getAttr` on purpose: the nine
+ * attributes `getAttr` serves are strings by contract and feed hashes,
+ * descriptions and `Number()`, and teaching it a fourth return shape would
+ * change what all nine yield for value shapes nobody has measured.
+ *
+ * The comparison is strict, and only `true` counts. A truthiness test over
+ * `stringValue` would read the string `"false"` as an assertion of failure —
+ * marking a call that ANSWERED as refused, inside bytes a publisher signs.
+ * The cost of the strictness is that a producer encoding this attribute as a
+ * string gets no marker; the reference producer does not, and under-reading a
+ * foreign encoding leaves the graph silent, where over-reading one would make
+ * it lie.
+ */
+function getBoolAttr(attrs, key) {
+    const attr = attrs.find(a => a.key === key);
+    return typeof attr?.value?.boolValue === 'boolean' ? attr.value.boolValue : undefined;
+}
 function nanoToIso(nano) {
     const ms = Math.floor(Number(nano) / 1_000_000);
     return new Date(ms).toISOString();
@@ -48,7 +74,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 +194,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 +234,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 +246,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 +269,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
                     }
                     : {}),
@@ -230,8 +291,32 @@ export function buildProvenanceGraph(trace, input, config) {
         // 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');
+        // Did the SOURCE REFUSE this call? Before 0.4.0 the graph never asked, so
+        // a refused call and one that answered were the same node with the same
+        // description — the absence of a data-response entity was the only trace
+        // of the rejection, and absence stated as nothing is not absence stated.
+        //
+        // `error` is the ASSERTION and `error.kind` only a LABEL on one. A span
+        // carrying a kind and no assertion is not a rejection, so the kind is read
+        // and stated only inside the failure branch — the posture
+        // `ToolCallSummary.failed`/`failureKind` already takes on the other input.
+        // `error.kind` is the one attribute name across this package and the
+        // reference producer (Wave N10 D5); neither side invents a second.
+        //
+        // The kind is the ONLY cause this graph will ever state. The producer
+        // stopped writing a rejection's raw text onto the span in the same wave —
+        // that text is authored by the source, can name a host, a port or a stack
+        // frame, and the trace travels inline inside the bytes an instance signs.
+        // Reading it here would put it back one layer up; the classified vocabulary
+        // widens instead. Nor does the description change: it states what the call
+        // WAS, and the marker below states how it ended.
+        const failed = getBoolAttr(span.attributes, 'error');
+        const failureKind = failed === true ? getAttr(span.attributes, 'error.kind') : undefined;
         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),
@@ -242,6 +327,17 @@ export function buildProvenanceGraph(trace, input, config) {
                 ? { 'prov:endedAtTime': xsdDateTime(nanoToIso(span.endTimeUnixNano)) }
                 : {}),
             ...(durationMs ? { 'civic: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
+            // the legacy chain's byte contract. `false` is never emitted — a
+            // producer that stated "not failed" and one that stated nothing must
+            // read the same, which is what makes a marker that IS present mean
+            // something. A rejected span carries no `tool.duration_ms` from the
+            // reference producer today (civic-ai-tools-website#413), so
+            // `civic:durationMs` simply does not fire beside these two.
+            ...(failed === true ? { [CIVIC_TERM_FAILED]: true } : {}),
+            ...(failureKind ? { [CIVIC_TERM_FAILURE_KIND]: failureKind } : {}),
         }));
     }
     // --- Final output relationships ---

package/dist/format/vocabulary.d.ts

@@ -11,6 +11,30 @@ export declare const PRIOR_ERA_CIVIC_NS = "https://civicaitools.org/ns/evidence/
 /** The prior-era id-scheme root, frozen inside records signed before the
  *  2026-08-19 settlement. Never emitted for new packages. */
 export declare const PRIOR_ERA_CIVIC_URN_PREFIX = "urn:civic-evidence";
+/**
+ * `civic:failed` — a tool-call activity whose call the SOURCE REFUSED.
+ *
+ * Emitted with the boolean `true` and only when the producer stated the
+ * rejection; never emitted as `false`. A literal `false` would assert an
+ * outcome, and "recorded as not-failed" must stay indistinguishable from
+ * "nothing recorded" — the same absent-is-absent posture `ToolCallSummary`
+ * takes for `failed`. A reader that finds no key learns that the record
+ * states nothing, which is the truth about every package minted before 0.4.0.
+ */
+export declare const CIVIC_TERM_FAILED = "civic:failed";
+/**
+ * `civic:failureKind` — the producer's own classified label for WHY a call
+ * carrying {@link CIVIC_TERM_FAILED} was refused.
+ *
+ * An open string with no normative vocabulary here: the harness states the
+ * label verbatim and never interprets or re-derives it. It is a label on an
+ * assertion, not the assertion — a record that carries a kind and no failure
+ * is not a rejection, and the term is emitted only alongside
+ * {@link CIVIC_TERM_FAILED}. The reference producer's four values are
+ * `timeout`, `unavailable`, `not_configured` and `unknown`; a producer with a
+ * wider vocabulary widens this field rather than putting prose in it.
+ */
+export declare const CIVIC_TERM_FAILURE_KIND = "civic:failureKind";
 /**
  * One era of the civic vocabulary: the two literals plus the emitters bound
  * to them. The vocabulary is not deployment configuration (a deployment does

package/dist/format/vocabulary.js

@@ -32,6 +32,45 @@ export const PRIOR_ERA_CIVIC_NS = 'https://civicaitools.org/ns/evidence/';
 /** The prior-era id-scheme root, frozen inside records signed before the
  *  2026-08-19 settlement. Never emitted for new packages. */
 export const PRIOR_ERA_CIVIC_URN_PREFIX = 'urn:civic-evidence';
+// --- Term names ---
+//
+// A `civic:` property name is vocabulary as much as the namespace it hangs
+// under: it is the word a reader of a signed graph interprets, so it is
+// declared here and imported by the builder that emits it, never spelled as a
+// literal inside capture/ (`purity.test.ts` enforces that for the terms below).
+// Both terms are era-independent — the settlement moved the NAMESPACE, not the
+// property names — so they carry no era qualifier and are minted for the first
+// time after it.
+//
+// The settlement-era property names that predate Wave N10 (`civic:sourceId`,
+// `civic:durationMs`, `civic:datasetId` and their siblings) are still inline
+// literals in the capture-side builder. That is a real inconsistency, recorded
+// rather than fixed in passing: moving them is a byte-sensitive change across
+// every golden fixture and belongs to a phase of its own.
+/**
+ * `civic:failed` — a tool-call activity whose call the SOURCE REFUSED.
+ *
+ * Emitted with the boolean `true` and only when the producer stated the
+ * rejection; never emitted as `false`. A literal `false` would assert an
+ * outcome, and "recorded as not-failed" must stay indistinguishable from
+ * "nothing recorded" — the same absent-is-absent posture `ToolCallSummary`
+ * takes for `failed`. A reader that finds no key learns that the record
+ * states nothing, which is the truth about every package minted before 0.4.0.
+ */
+export const CIVIC_TERM_FAILED = 'civic:failed';
+/**
+ * `civic:failureKind` — the producer's own classified label for WHY a call
+ * carrying {@link CIVIC_TERM_FAILED} was refused.
+ *
+ * An open string with no normative vocabulary here: the harness states the
+ * label verbatim and never interprets or re-derives it. It is a label on an
+ * assertion, not the assertion — a record that carries a kind and no failure
+ * is not a rejection, and the term is emitted only alongside
+ * {@link CIVIC_TERM_FAILED}. The reference producer's four values are
+ * `timeout`, `unavailable`, `not_configured` and `unknown`; a producer with a
+ * wider vocabulary widens this field rather than putting prose in it.
+ */
+export const CIVIC_TERM_FAILURE_KIND = 'civic:failureKind';
 /** Bind the emitters to one era's two literals. */
 export function makeCivicVocabulary(ns, urnPrefix) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typedstandards/civic-typed-harness",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",