Tranche-1.5: align SDK to accepted D137-D141, receipt conformance, example, pydocs

Per the coordination contract (protocol packages untouched; packages/sdk
+ python only):

- Evidence types aligned to the accepted §5.5.7 schema: constraints are
  {type, status, expected, actual}, verifier gains version, payload refs
  accept wire nulls. Anchor registry constants added with the accepted
  D138 names (atrib-log, sigstore-rekor, rfc3161-tsa, opentimestamps).
- D141 receipt surface: checkAttributionReceiptConsistency (TS) and a
  full Python parity module (parse + consistency check); both run the
  spec/conformance/mcp-extension receipt cases. The record-less
  log-submission case pins the checker's conservative no-record outcome
  alongside the corpus's shape-validity flag.
- Runnable example at packages/integration/examples/client-sdk/
  (attest -> chained revise -> recall round-trip on a temp mirror,
  daemon-first routing report, pass-through degradation), verified
  end-to-end; @atrib/sdk added to @atrib/integration deps.
- Python API docs: pdoc in the [dev] extras, commands documented.

Suites: TS 120 passed + 1 skip; Python 255 passed + 6 skips; mypy strict
clean; doc-sync green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZsFiTVkgLp3BoBXQiJ3ba

Author: claude

packages/integration/examples/client-sdk/README.md

@@ -0,0 +1,39 @@
+# @atrib/sdk client example
+
+The consolidated client SDK in one runnable file: `attest()` writes signed
+context, `recall()` reads it back, and every operational failure degrades
+instead of throwing per
+[§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract).
+
+```bash
+ATRIB_PRIVATE_KEY=$(node -e 'console.log(Buffer.from(crypto.randomBytes(32)).toString("base64url"))') \
+  npx tsx packages/integration/examples/client-sdk/integration.ts
+```
+
+Run from the repo root after `pnpm install && pnpm --filter @atrib/sdk... build`.
+
+## What it shows
+
+1. **attest()** — an observation, then a revision chained to it via
+   `ref: { kind: 'revises' }`. Both records sign through `@atrib/emit`'s
+   `handleEmit` pipeline (no SDK-local signing implementation) and land in
+   the local mirror with chain continuity (`chain_root` of the second
+   record = record hash of the first).
+2. **recall()** — the history shape reading those records back, newest
+   first, with `signature_verified` on each entry.
+3. **Daemon-first routing** — the client probes the local primitives
+   runtime (`$ATRIB_PRIMITIVES_HTTP_ENDPOINT`, default
+   `http://127.0.0.1:8796/mcp`) and reports which path served each call
+   (`via: 'daemon' | 'in-process' | 'none'`). The example works with or
+   without a running daemon.
+4. **Degradation** — a client built with `key: null` and no daemon
+   returns a pass-through result with warnings instead of throwing.
+
+The example writes its mirror to a temp directory (`ATRIB_MIRROR_FILE`)
+so it never touches `~/.atrib/records/`, and points log submission at an
+unroutable localhost anchor so nothing leaves the machine. Point
+`anchors` at `https://log.atrib.dev/v1/entries` (the default when the
+option is omitted) to submit real commitments.
+
+The Python sibling (`python/`) exposes the same verbs; see
+[`python/README.md`](../../../../python/README.md).

packages/integration/examples/client-sdk/integration.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Runnable @atrib/sdk walkthrough: attest → chained revise → recall,
+ * daemon-first routing, and §5.8 degradation. See README.md for the
+ * one-line run command. Uses a temp mirror and an unroutable log anchor
+ * so nothing persists outside this process or leaves the machine.
+ */
+
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createAtribClient } from '@atrib/sdk'
+
+async function main(): Promise<void> {
+  const mirror = join(mkdtempSync(join(tmpdir(), 'atrib-sdk-example-')), 'mirror.jsonl')
+  // ATRIB_MIRROR_FILE is where attest's write path appends; ATRIB_RECORD_FILE
+  // is where the in-process recall fallback (@atrib/recall) reads. Point both
+  // at the same temp file so the example round-trips.
+  process.env.ATRIB_MIRROR_FILE = mirror
+  process.env.ATRIB_RECORD_FILE = mirror
+  const contextId = 'e'.repeat(32)
+
+  const client = createAtribClient({
+    contextId,
+    // Unroutable anchor: submission stays local. Omit `anchors` (or use
+    // https://log.atrib.dev/v1/entries) to submit real commitments.
+    anchors: ['http://127.0.0.1:9/v1/entries'],
+  })
+
+  console.log(`mirror: ${mirror}\n`)
+
+  // 1. Write an observation (the default attest kind).
+  const observed = await client.attest({
+    content: {
+      what: 'chose sqlite over postgres for the pilot store',
+      why_noted: 'single-node deployment constraint',
+    },
+  })
+  console.log('observation:', observed.via, observed.record_hash)
+  for (const warning of observed.warnings) console.log('  !', warning)
+
+  if (observed.record_hash === null) {
+    console.log('\nNo signing key resolved — pass-through mode (§5.8 rule 5).')
+    console.log('Set ATRIB_PRIVATE_KEY (see README.md) and re-run.')
+    await client.close()
+    return
+  }
+
+  // 2. Revise it: one write verb, the ref discriminator picks the kind.
+  const revised = await client.attest({
+    content: {
+      new_position: 'postgres after all',
+      reason: 'pilot converted to multi-tenant',
+    },
+    ref: { kind: 'revises', record_hash: observed.record_hash },
+  })
+  console.log('revision:   ', revised.via, revised.record_hash)
+
+  // 3. Read the chain back, newest first, signatures verified.
+  const history = await client.recall<{
+    records?: Array<{ record_hash?: string; event_type?: string; signature_verified?: boolean }>
+  }>({ shape: 'history', context_id: contextId, limit: 5 })
+  console.log(`\nrecall via ${history.via}:`)
+  for (const entry of history.data?.records ?? []) {
+    console.log(` - ${entry.event_type} ${entry.record_hash} verified=${entry.signature_verified}`)
+  }
+
+  // 4. Degradation: no key + no daemon never throws.
+  const degraded = createAtribClient({ daemon: { mode: 'off' }, key: null })
+  const passThrough = await degraded.attest({ content: { what: 'nothing signs this' } })
+  console.log(`\ndegraded attest: via=${passThrough.via} record_hash=${passThrough.record_hash}`)
+
+  await degraded.close()
+  await client.close()
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

packages/integration/package.json

@@ -90,6 +90,7 @@
     "@atrib/mcp": "workspace:*",
     "@atrib/mcp-wrap": "workspace:*",
     "@atrib/runtime-log": "workspace:*",
+    "@atrib/sdk": "workspace:*",
     "@atrib/verify": "workspace:*",
     "canonicalize": "^3.0.0"
   },

packages/sdk/src/attribution.ts

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * `dev.atrib/attribution` extension receipts (P049 draft,
- * docs/adr-draft-p049-mcp-extension.md).
+ * `dev.atrib/attribution` extension receipts (accepted as D141; extension
+ * spec at docs/extensions/dev.atrib-attribution/v0.1.md, conformance at
+ * spec/conformance/mcp-extension/).
  *
  * Behind an opt-in flag, the daemon client parses attestation receipts
  * from tool results' `_meta["dev.atrib/attribution"]`: the propagation
@@ -15,7 +16,8 @@
  * signed records and inclusion proofs, never from the receipt itself.
  */
 
-import type { AtribRecord } from '@atrib/mcp'
+import { encodeToken, normalizeEventType, type AtribRecord } from '@atrib/mcp'
+import { recordHashRef } from './hashes.js'
 
 export const ATTRIBUTION_EXTENSION_KEY = 'dev.atrib/attribution'
 
@@ -87,3 +89,81 @@ export function parseAttributionReceiptBlock(meta: unknown): AttributionReceiptB
     ? out
     : null
 }
+
+/** Outcome of checking a receipt against its attached signed record. */
+export interface AttributionReceiptConsistency {
+  /** True iff every receipt claim matches the attached record. */
+  receipt_valid: boolean
+  /** Receipt fields whose claims contradict the attached record. */
+  mismatched_fields: string[]
+  /** recordHashRef of the attached record (when a record is available). */
+  attached_record_hash?: string
+  /** The receipt's claimed record_hash (when present). */
+  claimed_record_hash?: string
+}
+
+/**
+ * Check a receipt block's claims against the signed record they name
+ * (the attached `block.record`, or a caller-retrieved record). Receipts
+ * are advisory: a mismatch NEVER invalidates the tool result — it means
+ * the receipt must not be trusted or cited (conformance:
+ * spec/conformance/mcp-extension/cases/receipt--*.json).
+ *
+ * Compared claims: `receipt.record_hash` vs the record's canonical hash,
+ * `token` vs encodeToken(record), and `creator_key` / `context_id` /
+ * `chain_root` / `event_type` (short name or URI, normalized) vs the
+ * record's fields. Absent receipt fields are not mismatches.
+ */
+export function checkAttributionReceiptConsistency(
+  block: AttributionReceiptBlock,
+  record?: AtribRecord,
+): AttributionReceiptConsistency {
+  const attached = record ?? block.record
+  const receipt = block.receipt
+  const claimed = receipt?.record_hash
+  if (!attached) {
+    return {
+      receipt_valid: false,
+      mismatched_fields: ['record'],
+      ...(claimed !== undefined ? { claimed_record_hash: claimed } : {}),
+    }
+  }
+  const mismatched: string[] = []
+  let attachedHash: string | undefined
+  let token: string | undefined
+  try {
+    attachedHash = recordHashRef(attached)
+    token = encodeToken(attached)
+  } catch {
+    // A record that cannot be canonicalized/hashed cannot back a receipt.
+    return {
+      receipt_valid: false,
+      mismatched_fields: ['record'],
+      ...(claimed !== undefined ? { claimed_record_hash: claimed } : {}),
+    }
+  }
+  if (claimed !== undefined && claimed !== attachedHash) mismatched.push('record_hash')
+  if (block.token !== undefined && block.token !== token) mismatched.push('token')
+  if (receipt?.creator_key !== undefined && receipt.creator_key !== attached.creator_key) {
+    mismatched.push('creator_key')
+  }
+  if (receipt?.context_id !== undefined && receipt.context_id !== attached.context_id) {
+    mismatched.push('context_id')
+  }
+  if (receipt?.chain_root !== undefined && receipt.chain_root !== attached.chain_root) {
+    mismatched.push('chain_root')
+  }
+  if (
+    receipt?.event_type !== undefined &&
+    normalizeEventType(receipt.event_type) !== normalizeEventType(attached.event_type)
+  ) {
+    mismatched.push('event_type')
+  }
+  return {
+    receipt_valid: mismatched.length === 0,
+    mismatched_fields: mismatched,
+    attached_record_hash: attachedHash,
+    ...(claimed !== undefined ? { claimed_record_hash: claimed } : {}),
+  }
+}
+

packages/sdk/src/config.ts

@@ -97,6 +97,19 @@ export const DEFAULT_CALL_TIMEOUT_MS = 10_000
 export const DEFAULT_RETRY_COOLDOWN_MS = 30_000
 export const DEFAULT_PRODUCER = 'atrib-sdk'
 
+/**
+ * Accepted D138 anchor_type registry (spec §2.11.9). Only 'atrib-log'
+ * (the default when absent) is submitted to today; the others activate
+ * with the multi-anchor fan-out in the protocol packages.
+ */
+export const ANCHOR_TYPES = [
+  'atrib-log',
+  'sigstore-rekor',
+  'rfc3161-tsa',
+  'opentimestamps',
+] as const
+export type AnchorType = (typeof ANCHOR_TYPES)[number]
+
 export function resolveDaemonEndpoint(config?: DaemonConfig): string {
   return (
     config?.endpoint ??

packages/sdk/src/evidence.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * Evidence envelope types (P042 draft, docs/adr-draft-p042-evidence-envelope.md).
+ * Evidence envelope types (accepted as D137; normative schema at spec §5.5.7).
  *
  * The SDK models evidence attachments on the universal envelope schema so
  * downstream shapes align before the ADR lands: one envelope, N profiles
@@ -25,14 +25,15 @@ export type EvidencePayloadRefKind =
 
 export interface EvidencePayloadRef {
   kind: EvidencePayloadRefKind
-  /** For 'archive' / 'external' payload locations. */
-  uri?: string
+  /** For 'archive' / 'external' payload locations. Wire form uses explicit
+   * null for absent (§5.5.7 example); both are accepted. */
+  uri?: string | null
   /**
    * Set when the payload is itself a signed atrib record (may accompany
    * any kind except 'inline'); payload.hash then commits to that record's
    * canonical JCS bytes.
    */
-  record_hash?: string
+  record_hash?: string | null
 }
 
 export interface EvidencePayload {
@@ -46,9 +47,11 @@ export interface EvidencePayload {
 }
 
 export interface EvidenceConstraint {
-  name: string
+  /** Profile-defined constraint discriminator (accepted §5.5.7 shape). */
+  type: string
   status: 'passed' | 'failed' | 'unresolved' | 'not_checked'
-  detail?: string
+  expected?: unknown
+  actual?: unknown
 }
 
 export interface EvidenceEnvelope {
@@ -71,6 +74,7 @@ export interface EvidenceEnvelope {
   }
   verifier?: {
     name?: string
+    version?: string
     checked_at_ms?: number
   }
 }

packages/sdk/src/index.ts

@@ -38,9 +38,11 @@ export {
 export {
   DEFAULT_DAEMON_ENDPOINT,
   DEFAULT_PRODUCER,
+  ANCHOR_TYPES,
   resolveAnchorSet,
   resolveDaemonEndpoint,
   type AnchorSpec,
+  type AnchorType,
   type AtribClientConfig,
   type DaemonConfig,
   type DaemonMode,
@@ -61,10 +63,12 @@ export {
 } from './evidence.js'
 export {
   ATTRIBUTION_EXTENSION_KEY,
+  checkAttributionReceiptConsistency,
   parseAttributionReceiptBlock,
   type AttributionLogSubmissionStatus,
   type AttributionReceipt,
   type AttributionReceiptBlock,
+  type AttributionReceiptConsistency,
 } from './attribution.js'
 
 // ── SDK hash helpers (compositions of @atrib/mcp primitives) ────────────