@typedstandards/civic-typed-harness 0.1.0

package/dist/capture/skill-metadata.d.ts

@@ -0,0 +1,23 @@
+import { type BlobRef } from '@typedstandards/produce-core';
+/** Skill metadata extracted from a trace's `skill_fetch` span. Feeds the
+ *  envelope's `skillMetadata` block (and the datHere policy's
+ *  `skillMcpServerUrl` input). */
+export interface ExtractedSkillMetadata {
+    systemPromptHash?: string;
+    mcpServerUrl?: string;
+    skillText?: string;
+}
+/**
+ * Extract skill metadata from the trace's `skill_fetch` span. Returns `{}`
+ * when the trace has no such span (or is not span-shaped) — callers shipping
+ * trace-as-BlobRef should supply an explicit override instead (the packager
+ * cannot inspect spans it does not have).
+ */
+export declare function extractSkillMetadata(trace: Record<string, unknown>): ExtractedSkillMetadata;
+/**
+ * Resolve the span-walkable view of a trace input. When the trace is a
+ * BlobRef the capture machinery cannot inspect spans (data-source detection,
+ * skill extraction, PROV-O construction all degrade gracefully on the empty
+ * trace this returns); otherwise the trace object passes through unchanged.
+ */
+export declare function traceForInspection(trace: Record<string, unknown> | BlobRef): Record<string, unknown>;

package/dist/capture/skill-metadata.js

@@ -0,0 +1,45 @@
+// Skill-metadata extraction (CAPTURE group) — OTel `skill_fetch` span
+// walking, relocated from civic-ai-tools-website
+// `src/lib/evidence/packager.ts:303–322` (extraction) and `:354–357` (the
+// trace-as-BlobRef inspection fallback) per the S2 brief §1.
+import { isBlobRef } from '@typedstandards/produce-core';
+/**
+ * Extract skill metadata from the trace's `skill_fetch` span. Returns `{}`
+ * when the trace has no such span (or is not span-shaped) — callers shipping
+ * trace-as-BlobRef should supply an explicit override instead (the packager
+ * cannot inspect spans it does not have).
+ */
+export function extractSkillMetadata(trace) {
+    try {
+        // Untyped walk over the caller's trace shape.
+        const spans = trace?.resourceSpans?.[0]?.scopeSpans?.[0]?.spans;
+        if (!Array.isArray(spans))
+            return {};
+        const skillSpan = spans.find((s) => s.name === 'skill_fetch');
+        if (!skillSpan)
+            return {};
+        const attrs = {};
+        for (const a of skillSpan.attributes || []) {
+            attrs[a.key] = a.value?.stringValue || '';
+        }
+        return {
+            systemPromptHash: attrs['skill.text_hash'] || undefined,
+            mcpServerUrl: attrs['skill.mcp_server_url'] || undefined,
+            skillText: attrs['skill.text'] || undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolve the span-walkable view of a trace input. When the trace is a
+ * BlobRef the capture machinery cannot inspect spans (data-source detection,
+ * skill extraction, PROV-O construction all degrade gracefully on the empty
+ * trace this returns); otherwise the trace object passes through unchanged.
+ */
+export function traceForInspection(trace) {
+    return isBlobRef(trace)
+        ? { resourceSpans: [] }
+        : trace;
+}

package/dist/capture/trace.d.ts

@@ -0,0 +1,104 @@
+export interface SpanEvent {
+    timeUnixNano: string;
+    name: string;
+    attributes: OTelAttribute[];
+}
+export interface OTelAttribute {
+    key: string;
+    value: {
+        stringValue?: string;
+        intValue?: string;
+        boolValue?: boolean;
+    };
+}
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano?: string;
+    attributes: OTelAttribute[];
+    events: SpanEvent[];
+    status: {
+        code: number;
+    };
+}
+export interface OTelTrace {
+    resourceSpans: Array<{
+        resource: {
+            attributes: OTelAttribute[];
+        };
+        scopeSpans: Array<{
+            scope: {
+                name: string;
+                version: string;
+            };
+            spans: Span[];
+        }>;
+    }>;
+}
+/** SHA-256 hash of a string, returned as hex. Backed by @noble/hashes via
+ *  verify-core — same digest bytes as `node:crypto`, browser-safe. */
+export declare function hash(content: string): string;
+/** Millisecond clock. Injectable for deterministic tests. */
+export type TraceClock = () => number;
+/** Cryptographically-random byte source. Injectable for deterministic
+ *  tests. */
+export type TraceRandomBytes = (byteLength: number) => Uint8Array;
+/**
+ * TraceBuilder identity + determinism inputs. The identity strings name the
+ * capturing service, so they are per-instance config (config-not-constants);
+ * the demo values are `CIVICAITOOLS_TRACE_CONFIG` below.
+ */
+export interface TraceBuilderConfig {
+    /** OTel resource `service.name`. */
+    serviceName: string;
+    /** Instrumentation scope name. */
+    scopeName: string;
+    /** Scope version — also emitted as resource `service.version`. */
+    scopeVersion: string;
+    /** OTel semantic-conventions version advertised on the resource. */
+    semconvVersion: string;
+    /** Millisecond clock; defaults to `Date.now`. */
+    now?: TraceClock;
+    /** Random byte source for trace/span ids; defaults to the runtime's
+     *  `crypto.getRandomValues` (Web Crypto — Node 18+ and every browser). */
+    randomBytes?: TraceRandomBytes;
+}
+/** Demo default: the civicaitools.org reference deployment's capture
+ *  identity. */
+export declare const CIVICAITOOLS_TRACE_CONFIG: TraceBuilderConfig;
+export declare class TraceBuilder {
+    readonly traceId: string;
+    readonly rootSpanId: string;
+    private spans;
+    private readonly config;
+    private readonly now;
+    private readonly randomBytes;
+    constructor(config?: TraceBuilderConfig);
+    private randomHex;
+    private nowNano;
+    /**
+     * Start a new span. Returns the span ID.
+     * If no parentSpanId is given, the span is parented to the root.
+     */
+    startSpan(name: string, parentSpanId?: string, attributes?: Record<string, string | number | boolean>): string;
+    /** End a span, optionally merging additional attributes. */
+    endSpan(spanId: string, attributes?: Record<string, string | number | boolean>): void;
+    /** Record a point-in-time event within an existing span. */
+    recordEvent(spanId: string, name: string, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * Start the root span. Call this at the very beginning of the analysis.
+     * The root span uses the pre-generated rootSpanId.
+     */
+    startRoot(name: string, attributes?: Record<string, string | number | boolean>): void;
+    /** End the root span. */
+    endRoot(attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * Finalize and return the complete trace as OTel-compatible JSON.
+     * Any spans that were started but not ended are closed at finalize time.
+     */
+    finalize(): OTelTrace;
+}

package/dist/capture/trace.js

@@ -0,0 +1,166 @@
+// OTel-compatible trace capture (CAPTURE group) — types + TraceBuilder,
+// relocated whole from civic-ai-tools-website `src/lib/evidence/trace.ts:1–199`
+// per the S2 brief §1, with two changes:
+//   - `hash()` is re-backed by the @noble/hashes SHA-256 that verify-core
+//     implements and @typedstandards/produce-core re-exports (0.2.0), removing
+//     the module's only `node:crypto` use — the harness is browser-safe.
+//   - The resource/scope identity constants (`service.name`, scope
+//     name/version, semconv version) are typed config inputs with the demo
+//     values as the exported default (config-not-constants, S2 brief §2).
+//
+// Clock + RNG are INHERENT to capture (span timestamps and ids are what
+// capture *is*): this module is the sanctioned exception to the package's
+// determinism rule, and both are injectable for deterministic tests.
+import { sha256Hex } from '@typedstandards/produce-core';
+// --- Helpers ---
+function toAttr(key, value) {
+    if (typeof value === 'number') {
+        return { key, value: { intValue: String(value) } };
+    }
+    if (typeof value === 'boolean') {
+        return { key, value: { boolValue: value } };
+    }
+    return { key, value: { stringValue: value } };
+}
+function attrsFromRecord(attrs) {
+    if (!attrs)
+        return [];
+    return Object.entries(attrs).map(([k, v]) => toAttr(k, v));
+}
+/** SHA-256 hash of a string, returned as hex. Backed by @noble/hashes via
+ *  verify-core — same digest bytes as `node:crypto`, browser-safe. */
+export function hash(content) {
+    return sha256Hex(content);
+}
+/** Demo default: the civicaitools.org reference deployment's capture
+ *  identity. */
+export const CIVICAITOOLS_TRACE_CONFIG = {
+    serviceName: 'civic-ai-tools-website',
+    scopeName: 'civic-ai-tools-evidence',
+    scopeVersion: '0.1.0',
+    semconvVersion: '1.30.0',
+};
+function defaultRandomBytes(byteLength) {
+    const buf = new Uint8Array(byteLength);
+    globalThis.crypto.getRandomValues(buf);
+    return buf;
+}
+// --- TraceBuilder ---
+export class TraceBuilder {
+    traceId;
+    rootSpanId;
+    spans = new Map();
+    config;
+    now;
+    randomBytes;
+    constructor(config = CIVICAITOOLS_TRACE_CONFIG) {
+        this.config = config;
+        this.now = config.now ?? Date.now;
+        this.randomBytes = config.randomBytes ?? defaultRandomBytes;
+        this.traceId = this.randomHex(16); // 128-bit
+        this.rootSpanId = this.randomHex(8); // 64-bit
+    }
+    randomHex(bytes) {
+        return Array.from(this.randomBytes(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+    }
+    nowNano() {
+        // millisecond precision expressed as nanoseconds string
+        return `${this.now()}000000`;
+    }
+    /**
+     * Start a new span. Returns the span ID.
+     * If no parentSpanId is given, the span is parented to the root.
+     */
+    startSpan(name, parentSpanId, attributes) {
+        const spanId = this.randomHex(8);
+        this.spans.set(spanId, {
+            traceId: this.traceId,
+            spanId,
+            parentSpanId: parentSpanId ?? this.rootSpanId,
+            name,
+            kind: 1, // INTERNAL
+            startTimeUnixNano: this.nowNano(),
+            attributes: attrsFromRecord(attributes),
+            events: [],
+            status: { code: 0 },
+        });
+        return spanId;
+    }
+    /** End a span, optionally merging additional attributes. */
+    endSpan(spanId, attributes) {
+        const span = this.spans.get(spanId);
+        if (!span)
+            return;
+        span.endTimeUnixNano = this.nowNano();
+        if (attributes) {
+            span.attributes.push(...attrsFromRecord(attributes));
+        }
+    }
+    /** Record a point-in-time event within an existing span. */
+    recordEvent(spanId, name, attributes) {
+        const span = this.spans.get(spanId);
+        if (!span)
+            return;
+        span.events.push({
+            timeUnixNano: this.nowNano(),
+            name,
+            attributes: attrsFromRecord(attributes),
+        });
+    }
+    /**
+     * Start the root span. Call this at the very beginning of the analysis.
+     * The root span uses the pre-generated rootSpanId.
+     */
+    startRoot(name, attributes) {
+        this.spans.set(this.rootSpanId, {
+            traceId: this.traceId,
+            spanId: this.rootSpanId,
+            // root has no parent
+            name,
+            kind: 2, // SERVER
+            startTimeUnixNano: this.nowNano(),
+            attributes: attrsFromRecord(attributes),
+            events: [],
+            status: { code: 0 },
+        });
+    }
+    /** End the root span. */
+    endRoot(attributes) {
+        this.endSpan(this.rootSpanId, attributes);
+    }
+    /**
+     * Finalize and return the complete trace as OTel-compatible JSON.
+     * Any spans that were started but not ended are closed at finalize time.
+     */
+    finalize() {
+        const finalTime = this.nowNano();
+        for (const span of this.spans.values()) {
+            if (!span.endTimeUnixNano) {
+                span.endTimeUnixNano = finalTime;
+            }
+        }
+        return {
+            resourceSpans: [
+                {
+                    resource: {
+                        attributes: [
+                            toAttr('service.name', this.config.serviceName),
+                            toAttr('service.version', this.config.scopeVersion),
+                            toAttr('telemetry.sdk.language', 'typescript'),
+                            toAttr('otel.semconv.version', this.config.semconvVersion),
+                        ],
+                    },
+                    scopeSpans: [
+                        {
+                            scope: {
+                                name: this.config.scopeName,
+                                version: this.config.scopeVersion,
+                            },
+                            spans: Array.from(this.spans.values()),
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+}

package/dist/format/dathere.d.ts

@@ -0,0 +1,83 @@
+/** The datHere content-profile label (ADR-0004). */
+export declare const DATHERE_CONTENT_PROFILE = "datHere";
+/** Producer Profile auto-derived for the datHere content profile (ADR-0006):
+ *  compound `<profile-type>/<profile-subtype>`. */
+export declare const DATHERE_PRODUCER_PROFILE = "ai-assisted-analysis/datHere";
+/** Reverse-DNS key of the auto-emitted environment extension. */
+export declare const ENVIRONMENT_EXTENSION_KEY = "org.civicaitools.environment";
+/** Demo default for the environment extension's `host` field: the
+ *  civicaitools.org reference deployment. Config-not-constants — every other
+ *  instance supplies its own via `DatHereEnvironmentConfig`. */
+export declare const CIVICAITOOLS_ENVIRONMENT_HOST = "civicaitools.org";
+/** Per-instance configuration for the environment extension. */
+export interface DatHereEnvironmentConfig {
+    /** Publishing host recorded in `org.civicaitools.environment.host`. */
+    host: string;
+}
+/** The civicaitools.org demo default. */
+export declare const CIVICAITOOLS_ENVIRONMENT_CONFIG: DatHereEnvironmentConfig;
+/**
+ * Derive the envelope's `producerProfile` (ADR-0006): the explicit value when
+ * supplied, else auto-derived from the datHere content profile, else
+ * `undefined` (and thereby unemitted — pre-ADR-0006 canonical JSON stays
+ * byte-identical).
+ */
+export declare function deriveProducerProfile(producerProfile?: string, contentProfile?: string): string | undefined;
+/**
+ * Select the content-canonicalization rule URI (spec §8.2) for a content
+ * profile: `dathere-ag-jupyter/v1` for datHere (fingerprints the executed
+ * notebook), `legacy-json/v1` for everything else (whole-package rule).
+ */
+export declare function selectContentCanonicalization(contentProfile?: string): string;
+/**
+ * Summary-emission decision (ADR-0004 §7): the datHere profile REQUIRES the
+ * summary in canonical JSON (covered by the envelope hash); every other
+ * profile keeps it off-envelope (DB-row only in the reference app), so their
+ * package hashes stay byte-identical to pre-ADR-0004 behavior. Returns the
+ * value to pass as the envelope's `summary` field, or `undefined` to omit.
+ */
+export declare function deriveSummaryEmission(contentProfile?: string, summary?: string): string | undefined;
+/**
+ * Build the `org.civicaitools.environment` extension content for a datHere
+ * package. Per OES §9.1.1 requirement 3 the extension MUST carry
+ * `modelVersion`, `temperature`, `mcpServers`, `toolDefinitions`, `host`.
+ *
+ * Prototype limitations carried over from the reference implementation
+ * (known gaps, tightened in follow-up work): `temperature` placeholder `0`,
+ * `toolDefinitions` placeholder `[]`; `mcpServers` derives from the trace's
+ * skill-fetch span URL (the analysis's primary MCP server). Fields captured
+ * honestly: `modelVersion` and `host`.
+ */
+export declare function buildDatHereEnvironment(model: string, skillMcpServerUrl: string | undefined, config?: DatHereEnvironmentConfig): Record<string, unknown>;
+/** Input to the composite datHere-policy derivation. */
+export interface DatHerePolicyInput {
+    /** Model identifier (becomes `environment.modelVersion`). */
+    model: string;
+    /** Content-profile label; absence means the default profile. */
+    contentProfile?: string;
+    /** Explicit producerProfile — wins over auto-derivation when supplied. */
+    producerProfile?: string;
+    /** Candidate summary text (emitted only under the datHere profile). */
+    summary?: string;
+    /** MCP server URL from the trace's skill-fetch span (capture-side
+     *  extraction — see src/capture/skill-metadata.ts). */
+    skillMcpServerUrl?: string;
+    /** Caller-supplied extensions to layer the environment extension onto. */
+    extensions?: Record<string, unknown>;
+}
+/** The derived envelope-field values, ready to spread into produce-core's
+ *  `EnvelopeInput`. Fields are `undefined` exactly when the reference
+ *  packager left them unemitted. */
+export interface DatHereEnvelopeFields {
+    producerProfile?: string;
+    contentCanonicalization: string;
+    summary?: string;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Composite derivation: everything the reference packager derived inline for
+ * the datHere policy, as one call. Non-datHere inputs pass through with only
+ * the legacy canonicalization rule and any caller-supplied extensions —
+ * byte-identical envelopes via the core's conditional spreads.
+ */
+export declare function deriveDatHereEnvelopeFields(input: DatHerePolicyInput, config?: DatHereEnvironmentConfig): DatHereEnvelopeFields;

package/dist/format/dathere.js

@@ -0,0 +1,111 @@
+// datHere envelope policy (FORMAT-EXTENSION group) — the derivations the
+// reference app's packager did inline, relocated from civic-ai-tools-website
+// `src/lib/evidence/packager.ts` per the S2 brief §1:
+//   - `:26`       DATHERE_PRODUCER_PROFILE constant
+//   - `:286–301`  `org.civicaitools.environment` extension builder
+//   - `:393–395`  producerProfile derivation
+//   - `:407–410`  content-canonicalization rule selection
+//   - `:464–466`  summary-emission decision
+//   - `:477–484`  extension layering
+//
+// Output = explicit envelope-field values for @typedstandards/produce-core's
+// `buildEnvelope` (ADR-0021's operating rule: the harness DERIVES, the core
+// ASSEMBLES). Byte discipline: every field is emitted exactly when the
+// reference packager emitted it, so equivalent inputs produce byte-identical
+// canonical JSON through the core's conditional spreads.
+//
+// The canonicalization rule URIs are verify-core's, reached through
+// @typedstandards/produce-core's 0.2.0 re-exports (the harness's single
+// declared dependency); the harness re-emits, never redefines, them.
+import { DATHERE_AG_JUPYTER_CANONICALIZATION, LEGACY_JSON_CANONICALIZATION, } from '@typedstandards/produce-core';
+/** The datHere content-profile label (ADR-0004). */
+export const DATHERE_CONTENT_PROFILE = 'datHere';
+/** Producer Profile auto-derived for the datHere content profile (ADR-0006):
+ *  compound `<profile-type>/<profile-subtype>`. */
+export const DATHERE_PRODUCER_PROFILE = 'ai-assisted-analysis/datHere';
+/** Reverse-DNS key of the auto-emitted environment extension. */
+export const ENVIRONMENT_EXTENSION_KEY = 'org.civicaitools.environment';
+/** Demo default for the environment extension's `host` field: the
+ *  civicaitools.org reference deployment. Config-not-constants — every other
+ *  instance supplies its own via `DatHereEnvironmentConfig`. */
+export const CIVICAITOOLS_ENVIRONMENT_HOST = 'civicaitools.org';
+/** The civicaitools.org demo default. */
+export const CIVICAITOOLS_ENVIRONMENT_CONFIG = {
+    host: CIVICAITOOLS_ENVIRONMENT_HOST,
+};
+/**
+ * Derive the envelope's `producerProfile` (ADR-0006): the explicit value when
+ * supplied, else auto-derived from the datHere content profile, else
+ * `undefined` (and thereby unemitted — pre-ADR-0006 canonical JSON stays
+ * byte-identical).
+ */
+export function deriveProducerProfile(producerProfile, contentProfile) {
+    return (producerProfile
+        ?? (contentProfile === DATHERE_CONTENT_PROFILE
+            ? DATHERE_PRODUCER_PROFILE
+            : undefined));
+}
+/**
+ * Select the content-canonicalization rule URI (spec §8.2) for a content
+ * profile: `dathere-ag-jupyter/v1` for datHere (fingerprints the executed
+ * notebook), `legacy-json/v1` for everything else (whole-package rule).
+ */
+export function selectContentCanonicalization(contentProfile) {
+    return contentProfile === DATHERE_CONTENT_PROFILE
+        ? DATHERE_AG_JUPYTER_CANONICALIZATION
+        : LEGACY_JSON_CANONICALIZATION;
+}
+/**
+ * Summary-emission decision (ADR-0004 §7): the datHere profile REQUIRES the
+ * summary in canonical JSON (covered by the envelope hash); every other
+ * profile keeps it off-envelope (DB-row only in the reference app), so their
+ * package hashes stay byte-identical to pre-ADR-0004 behavior. Returns the
+ * value to pass as the envelope's `summary` field, or `undefined` to omit.
+ */
+export function deriveSummaryEmission(contentProfile, summary) {
+    return contentProfile === DATHERE_CONTENT_PROFILE && summary
+        ? summary
+        : undefined;
+}
+/**
+ * Build the `org.civicaitools.environment` extension content for a datHere
+ * package. Per OES §9.1.1 requirement 3 the extension MUST carry
+ * `modelVersion`, `temperature`, `mcpServers`, `toolDefinitions`, `host`.
+ *
+ * Prototype limitations carried over from the reference implementation
+ * (known gaps, tightened in follow-up work): `temperature` placeholder `0`,
+ * `toolDefinitions` placeholder `[]`; `mcpServers` derives from the trace's
+ * skill-fetch span URL (the analysis's primary MCP server). Fields captured
+ * honestly: `modelVersion` and `host`.
+ */
+export function buildDatHereEnvironment(model, skillMcpServerUrl, config = CIVICAITOOLS_ENVIRONMENT_CONFIG) {
+    const mcpServers = [];
+    if (skillMcpServerUrl) {
+        mcpServers.push({ url: skillMcpServerUrl });
+    }
+    return {
+        modelVersion: model,
+        temperature: 0,
+        mcpServers,
+        toolDefinitions: [],
+        host: config.host,
+    };
+}
+/**
+ * Composite derivation: everything the reference packager derived inline for
+ * the datHere policy, as one call. Non-datHere inputs pass through with only
+ * the legacy canonicalization rule and any caller-supplied extensions —
+ * byte-identical envelopes via the core's conditional spreads.
+ */
+export function deriveDatHereEnvelopeFields(input, config = CIVICAITOOLS_ENVIRONMENT_CONFIG) {
+    const extensions = { ...(input.extensions ?? {}) };
+    if (input.contentProfile === DATHERE_CONTENT_PROFILE) {
+        extensions[ENVIRONMENT_EXTENSION_KEY] = buildDatHereEnvironment(input.model, input.skillMcpServerUrl, config);
+    }
+    return {
+        producerProfile: deriveProducerProfile(input.producerProfile, input.contentProfile),
+        contentCanonicalization: selectContentCanonicalization(input.contentProfile),
+        summary: deriveSummaryEmission(input.contentProfile, input.summary),
+        ...(Object.keys(extensions).length > 0 ? { extensions } : {}),
+    };
+}

package/dist/format/profiles.d.ts

@@ -0,0 +1,13 @@
+import { type CaptureMethod } from '@typedstandards/produce-core';
+export type { CaptureMethod };
+/** The profile TYPE the civic harness publishes under (the segment before the
+ *  first `/` of the compound producerProfile). */
+export declare const AI_ASSISTED_ANALYSIS_PROFILE_TYPE = "ai-assisted-analysis";
+/**
+ * The captureMethod vocabulary for the `ai-assisted-analysis` profile type —
+ * verify-core's Q32 fallback-table entry, re-exported (single-sourced, so the
+ * harness cannot drift from what the verifier accepts):
+ * `chat-flow-stream` · `claude-code-jsonl-readback` ·
+ * `claude-code-self-report` (legacy, deprecated 2026-04-28).
+ */
+export declare const AI_ASSISTED_ANALYSIS_CAPTURE_METHODS: readonly CaptureMethod[];

package/dist/format/profiles.js

@@ -0,0 +1,26 @@
+// captureMethod vocabulary surface (FORMAT-EXTENSION group) — the profile
+// constants the civic harness publishes under, re-exported CONSISTENT WITH
+// verify-core's hardcoded fallback table by construction (the values below
+// ARE that table's entry, not a copy).
+//
+// ⚠ Q32 adjacency (open-questions registry): verify-core's per-profile
+// captureMethod vocabulary is a hardcoded fallback table pending versioned,
+// content-addressed guidance bundles. The `ai-assisted-analysis` guidance
+// bundle already lives in civic-ai-tools docs (ADR-0006/ADR-0011), which is
+// one more reason the Q32 versioned-bundle question eventually lands in this
+// package. Flagged, not solved, here — do not grow this module into a bundle
+// mechanism without resolving Q32 first.
+// Reached through @typedstandards/produce-core's 0.2.0 re-exports (the
+// harness's single declared dependency); the table itself is verify-core's.
+import { PROFILE_CAPTURE_VOCAB, } from '@typedstandards/produce-core';
+/** The profile TYPE the civic harness publishes under (the segment before the
+ *  first `/` of the compound producerProfile). */
+export const AI_ASSISTED_ANALYSIS_PROFILE_TYPE = 'ai-assisted-analysis';
+/**
+ * The captureMethod vocabulary for the `ai-assisted-analysis` profile type —
+ * verify-core's Q32 fallback-table entry, re-exported (single-sourced, so the
+ * harness cannot drift from what the verifier accepts):
+ * `chat-flow-stream` · `claude-code-jsonl-readback` ·
+ * `claude-code-self-report` (legacy, deprecated 2026-04-28).
+ */
+export const AI_ASSISTED_ANALYSIS_CAPTURE_METHODS = PROFILE_CAPTURE_VOCAB[AI_ASSISTED_ANALYSIS_PROFILE_TYPE];

package/dist/format/sources.d.ts

@@ -0,0 +1,54 @@
+import type { DataSourceEntry } from '@typedstandards/produce-core';
+/** One known data source: identity, display, and endpoint coordinates. */
+export interface CivicSourceInfo {
+    /** Human-friendly display label (evidence detail page "Data sources"). */
+    displayName: string;
+    /** PROV agent `dcterms:title`, e.g. "Socrata MCP Server". */
+    agentTitle: string;
+    /** MCP endpoint URL — the PROV agent's `civic:serverUrl`. */
+    serverUrl: string;
+    /** `dataSources[].catalogType` value for entries from this source. */
+    catalogType: string;
+    /**
+     * Portal URL for the single AGGREGATE `dataSources` entry emitted when this
+     * source's query surface is not dataset-keyed (Data Commons's knowledge
+     * graph, Boston OpenContext's CKAN DataStore). ABSENT for dataset-keyed
+     * sources (Socrata), which emit one entry per dataset instead — presence of
+     * this field is what routes a source down the aggregate path.
+     */
+    aggregatePortalUrl?: string;
+}
+/** A source registry: source id → coordinates. Insertion order is emission
+ *  order for aggregate `dataSources` entries. */
+export type CivicSourceRegistry = Record<string, CivicSourceInfo>;
+/** The civic default registry — the three demo sources. */
+export declare const CIVIC_SOURCE_REGISTRY: CivicSourceRegistry;
+/** The source id untagged/pre-M9.1 captures fall back to. Socrata was the
+ *  only source when those packages were written. */
+export declare const FALLBACK_SOURCE_ID = "socrata";
+/** Is this source dataset-keyed (one `dataSources` entry per dataset) rather
+ *  than aggregate? Unknown ids are neither — they contribute no entry. */
+export declare function isDatasetKeyedSource(sourceId: string, registry?: CivicSourceRegistry): boolean;
+/**
+ * Resolve an MCP tool name to a source id, or `undefined` when unknown.
+ * The data-source population function (capture group) takes one of these as
+ * a CALLER-SUPPLIED input; `civicToolSourceResolver` below is the civic
+ * default. An instance wiring its own MCP layer supplies its own resolver —
+ * the resolver is how the app-side MCP registry stays app-side.
+ */
+export type ToolSourceResolver = (toolName: string) => string | undefined;
+/** Civic default tool-name → source-id map (mirrors the demo app's static
+ *  MCP-layer map; used as a fallback when a trace span carries no
+ *  `mcp.source` attribute). */
+export declare const CIVIC_TOOL_SOURCE_MAP: Record<string, string>;
+/** The civic default `ToolSourceResolver`. */
+export declare const civicToolSourceResolver: ToolSourceResolver;
+/** Human-friendly display label for a `sourceId`. Unknown ids fall back to a
+ *  capitalised form of the raw id so new sources render sensibly before the
+ *  registry is updated. Missing ids coerce to the fallback source (pre-M9.3
+ *  packages have no `sourceId` on dataSources entries). */
+export declare function displayNameForSource(sourceId: string | undefined | null, registry?: CivicSourceRegistry): string;
+/** Format a `dataSources` array as a compact, de-duplicated summary string
+ *  (middle-dot separated). Returns `null` when the array is empty or missing,
+ *  letting callers render a fallback. */
+export declare function formatDataSourcesSummary(entries: DataSourceEntry[] | undefined, registry?: CivicSourceRegistry): string | null;