@atrib/sdk 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +90 -85
  3. package/package.json +10 -10
package/LICENSE CHANGED
@@ -201,7 +201,7 @@
201
201
  See the License for the specific language governing permissions and
202
202
  limitations under the License.
203
203
 
204
- Copyright 2025-2026 Atrib contributors
204
+ Copyright 2025-2026 atrib contributors
205
205
 
206
206
  Licensed under the Apache License, Version 2.0 (the "License");
207
207
  you may not use this file except in compliance with the License.
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @atrib/sdk
2
2
 
3
- Consolidated atrib client SDK: two verbs over the substrate — **`attest()`**
4
- (write) and **`recall()`** (read) — plus the complete [§1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#1-attribution-record-format) record layer
5
- re-exported from `@atrib/mcp` so application code needs exactly one import.
3
+ Consolidated atrib client SDK. Two verbs over the substrate: **`attest()`**
4
+ (write) and **`recall()`** (read), plus the complete [§1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#1-attribution-record-format) record layer
5
+ re-exported from `@atrib/mcp`, so application code needs exactly one import.
6
6
 
7
7
  This package is a consolidation, not a greenfield: it adds **no new
8
8
  canonicalization, hashing, or signing implementation**. Every write
@@ -18,8 +18,8 @@ pnpm add @atrib/sdk
18
18
 
19
19
  Version 0.1.0 is first-published manually. Later releases use npm Trusted
20
20
  Publisher through `release.yml`. `@atrib/recall`, `@atrib/verify`, and
21
- `@atrib/verify-mcp` are optional peers — install them alongside for the
22
- in-process recall and verify fallbacks; without them those paths degrade to
21
+ `@atrib/verify-mcp` are optional peers. Install them alongside for the
22
+ in-process recall and verify fallbacks. Without them, those paths degrade to
23
23
  a typed unavailable outcome per the degradation contract below.
24
24
 
25
25
  Verify a local build with `pnpm --filter @atrib/sdk test`.
@@ -78,29 +78,30 @@ the calling harness/model; the SDK returns verified raw material.
78
78
 
79
79
  ## Degradation contract ([§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract))
80
80
 
81
- Operational failures never throw and never block: daemon unreachable →
82
- fallback; no signing key → pass-through result with a warning; log
83
- submission is non-blocking with bounded retry (via the existing
84
- `@atrib/mcp` submission queue). The only throw paths are contradictory
85
- inputs (programmer error), e.g. `ref.kind: 'revises'` with
81
+ Operational failures never throw and never block. If the daemon is
82
+ unreachable, the SDK falls back to in-process engines. If there is no
83
+ signing key, it returns a pass-through result with a warning. Log
84
+ submission is non-blocking with bounded retry, through the existing
85
+ `@atrib/mcp` submission queue. The only throw paths are contradictory
86
+ inputs (programmer error), such as `ref.kind: 'revises'` with
86
87
  `event_type: 'annotation'`.
87
88
 
88
89
  ## Anchors ([D138](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d138-anchor-plurality-as-the-default-trust-posture), [§2.11.7-§2.11.13](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#2117-anchors-generalizing-the-replication-target))
89
90
 
90
- `anchors` config takes a **set** of anchor descriptors — bare strings
91
+ `anchors` config takes a **set** of anchor descriptors: bare strings
91
92
  (atrib-log [§2.6.1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#261-submit-entry)
92
93
  endpoints) or `{ url | endpoint, anchor_type?, ... }` objects covering
93
94
  the [§2.11.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#2118-anchor-type-registry)
94
95
  registry (`atrib-log`, `sigstore-rekor`, `rfc3161-tsa`,
95
96
  `opentimestamps`). In-process attests fan out to **every** configured
96
97
  anchor through `@atrib/mcp`'s `createAnchorFanout` (fire-and-forget per
97
- [§5.3.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#535-log-submission));
98
- no anchor config at all resolves to `BUILT_IN_DEFAULT_ANCHOR_SET` (two
98
+ [§5.3.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#535-log-submission)).
99
+ No anchor config at all resolves to `BUILT_IN_DEFAULT_ANCHOR_SET` (two
99
100
  independent anchors, [§2.11.12](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#21112-producer-side-anchor-posture)
100
- rule 1). A sub-plurality set (< 2 anchors) warns and writes the
101
+ rule 1). A sub-plurality set (fewer than two anchors) warns and writes the
101
102
  `_local.anchor_config` sidecar degradation marker unless
102
103
  `allowSingleAnchor: true` states it is deliberate. The resolved posture
103
- surfaces as `anchor_posture` on `AttestResult`; `flushAnchors()` gives a
104
+ surfaces as `anchor_posture` on `AttestResult`, and `flushAnchors()` gives a
104
105
  bounded wait on pending legs. Anchoring never touches signed bytes and
105
106
  never blocks the write.
106
107
 
@@ -115,7 +116,7 @@ awaited proof), and optionally the full signed record for immediate
115
116
  Tier-3 re-verification. Each parsed block is run through `@atrib/mcp`'s
116
117
  `verifyAttributionReceipt` (extension spec [§6.2](https://github.com/creatornader/atrib/blob/main/docs/extensions/dev.atrib-attribution/v0.1.md#62-receipt-block) integrity check) and
117
118
  surfaces as `attribution_receipt: { block, verification }` on
118
- attest/recall results. Receipts are advisory — trust derives from
119
+ attest/recall results. Receipts are advisory. Trust derives from
119
120
  verifying signed records, never from the receipt.
120
121
 
121
122
  ## Evidence envelopes ([D137](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d137-universal-evidence-envelope-as-the-single-protocol-level-attachment-model), [§5.5.7](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#557-universal-evidence-envelope))
@@ -126,7 +127,7 @@ single attachment model for external evidence; the legacy `protocol`
126
127
  string set is frozen. The SDK ships the structural types/helpers plus
127
128
  production and validation: `buildEvidenceEnvelope` computes the payload
128
129
  commitment (JCS or raw hash rule) and `validateEvidenceEnvelope` applies
129
- the normative shape rules — both delegate to the optional peer
130
+ the normative shape rules. Both delegate to the optional peer
130
131
  `@atrib/verify` and degrade with a warning when it is not installed.
131
132
  Envelopes live outside signed bytes (mirror sidecar, archive evidence
132
133
  projection, verifier results, host-owned packets).
@@ -159,8 +160,8 @@ interface AtribClient {
159
160
  **Throw vs degrade.** Both verbs follow the
160
161
  [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract)
161
162
  degradation contract: operational failures (daemon unreachable, tool
162
- error, missing key, missing optional peer, log unreachable) never throw —
163
- they degrade into `warnings` on the result, with `via: 'none'` when
163
+ error, missing key, missing optional peer, log unreachable) never throw.
164
+ They degrade into `warnings` on the result, with `via: 'none'` when
164
165
  nothing could serve the call. The only throw paths are contradictory or
165
166
  malformed **inputs** (programmer error): a `ref.kind` that contradicts an
166
167
  explicit `event_type`, an unknown `ref.kind`, an unknown recall `shape`,
@@ -168,7 +169,7 @@ or an input shape that fails `emitInProcess`'s schema validation.
168
169
 
169
170
  **`attest(input)` semantics.** Maps `AttestInput` to the shared
170
171
  `EmitInput` argument shape via `buildEmitArgs` (exported; throws
171
- `TypeError` on contradictory input — the write verb's only throw path),
172
+ `TypeError` on contradictory input, the write verb's only throw path),
172
173
  then tries paths in order:
173
174
 
174
175
  1. **Daemon** (`daemon.mode` `'prefer'` or `'require'`): calls the `emit`
@@ -183,18 +184,18 @@ then tries paths in order:
183
184
  record back from the mirror tail and fans it out to every configured
184
185
  anchor via `createAnchorFanout`
185
186
  ([D138](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d138-anchor-plurality-as-the-default-trust-posture);
186
- fire-and-forget per [§5.3.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#535-log-submission)
187
- — the primary log receiving the record twice is idempotent-safe per
187
+ fire-and-forget per [§5.3.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#535-log-submission);
188
+ the primary log receiving the record twice is idempotent-safe per
188
189
  [§2.6.1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#261-submit-entry)
189
- step 6), stamping the resolved `anchor_posture` on the result. No key
190
- → pass-through result (`via: 'none'`, `record_hash: null`) with a
190
+ step 6), stamping the resolved `anchor_posture` on the result. Without a
191
+ key, the SDK returns a pass-through result (`via: 'none'`, `record_hash: null`) with a
191
192
  warning, per
192
193
  [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract)
193
194
  rule 5. The daemon path never consults the client's fan-out: the
194
195
  daemon owns its own anchors.
195
196
 
196
197
  Under `daemon.mode: 'require'`, a daemon failure returns the degraded
197
- `via: 'none'` result directly — it never falls back and never throws.
198
+ `via: 'none'` result directly. It never falls back and never throws.
198
199
 
199
200
  **`recall(query)` semantics.** Resolves the shape (`query.shape`, default
200
201
  `'history'`), maps it to the physical tool name via `SHAPE_TO_TOOL`
@@ -247,8 +248,8 @@ interface AttestRef {
247
248
  | `receipt_id` | `string?` | Present when the emit pipeline issued a receipt id. |
248
249
  | `via` | `'daemon' \| 'in-process' \| 'none'` | Which path produced the record. `'none'` = degraded; see `warnings`. |
249
250
  | `warnings` | `string[]` | `atrib:`-prefixed operational warnings (anchor skips, fallbacks, pass-through, flush deadline). |
250
- | `anchor_posture` | `AttestAnchorPosture?` | `{ effective_anchor_count, used_default_set, warned }` — the resolved [§2.11.12](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#21112-producer-side-anchor-posture) posture; present on in-process attests that reached the anchor fan-out. |
251
- | `attribution_receipt` | `VerifiedAttributionReceipt?` | `{ block, verification }` — the parsed `dev.atrib/attribution` receipt plus its `verifyAttributionReceipt` outcome; only when `attributionReceipts: true` and the daemon emitted one. Advisory. |
251
+ | `anchor_posture` | `AttestAnchorPosture?` | `{ effective_anchor_count, used_default_set, warned }`: the resolved [§2.11.12](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#21112-producer-side-anchor-posture) posture; present on in-process attests that reached the anchor fan-out. |
252
+ | `attribution_receipt` | `VerifiedAttributionReceipt?` | `{ block, verification }`: the parsed `dev.atrib/attribution` receipt plus its `verifyAttributionReceipt` outcome; only when `attributionReceipts: true` and the daemon emitted one. Advisory. |
252
253
 
253
254
  ### `RecallQuery` shapes
254
255
 
@@ -273,7 +274,7 @@ column says what serves the shape when no daemon is reachable.
273
274
  `verify` is Pattern 3 handoff-claim verification
274
275
  ([D105](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d105-pattern-3-handoff-claims-use-verifier-side-claim-acceptance)/[D106](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d106-verify-is-promoted-to-cognitive-primitive-7)).
275
276
  "None (degrades)" shapes return `via: 'none'`, `data: null`, and a
276
- warning naming the runtime tool — honestly, rather than via a divergent
277
+ warning naming the runtime tool to use instead, rather than a divergent
277
278
  reimplementation. When a peer-backed fallback engine itself throws, that
278
279
  too is caught and degraded.
279
280
 
@@ -318,7 +319,7 @@ themselves.
318
319
  An anchor is either a bare string (an atrib-log
319
320
  [§2.6.1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#261-submit-entry)
320
321
  endpoint, shorthand for `{ url }`) or an `AnchorDescriptor`
321
- (`{ anchor_type?, anchor_id?, url?, endpoint?, ... }` — `url` wins over
322
+ (`{ anchor_type?, anchor_id?, url?, endpoint?, ... }`: `url` wins over
322
323
  `endpoint`; an absent `anchor_type` means `'atrib-log'`; registered
323
324
  non-atrib-log types like `'opentimestamps'` need no URL).
324
325
 
@@ -328,7 +329,7 @@ non-atrib-log types like `'opentimestamps'` need no URL).
328
329
  consume, and never throws: hostile entries (non-string/non-object,
329
330
  missing/invalid endpoint where one is required) and `anchor_type` values
330
331
  outside the [§2.11.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#2118-anchor-type-registry)
331
- registry warn-and-skip — skipped entries are **excluded** from the
332
+ registry warn-and-skip. Skipped entries are **excluded** from the
332
333
  config, so they never count toward the plurality posture. `undefined`
333
334
  input returns an empty config (the built-in default set applies
334
335
  downstream). Returns `{ config: AnchorSetConfig, primaryLogEndpoint:
@@ -357,7 +358,7 @@ type DaemonCallOutcome =
357
358
  - Connection is lazy and cached; a failed call closes the transport and
358
359
  starts the `retryCooldownMs` window, during which `callTool` returns
359
360
  `{ ok: false }` immediately without re-probing.
360
- - `close()` — best-effort transport close; never throws.
361
+ - `close()`: best-effort transport close; never throws.
361
362
  - The client is semantically stateless: `context_id` and chain tokens
362
363
  travel as explicit tool arguments on every call; the MCP protocol
363
364
  session (initialize handshake + `Mcp-Session-Id`) is a transport
@@ -365,7 +366,7 @@ type DaemonCallOutcome =
365
366
 
366
367
  ### Hash helpers
367
368
 
368
- Compositions of `@atrib/mcp` primitives — no new hashing implementation.
369
+ Compositions of `@atrib/mcp` primitives, with no hashing implementation of their own.
369
370
 
370
371
  | Export | Returns | Meaning |
371
372
  | --- | --- | --- |
@@ -378,18 +379,18 @@ Compositions of `@atrib/mcp` primitives — no new hashing implementation.
378
379
  Structural types/helpers are SDK-local; envelope **production and
379
380
  validation** delegate to the optional peer `@atrib/verify` (lazy import;
380
381
  missing peer degrades to a `null` envelope with a warning naming the
381
- peer — [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract)).
382
+ peer, per [§5.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#58-degradation-contract)).
382
383
  Envelopes live outside signed bytes (mirror sidecar, archive evidence
383
384
  projection, verifier results, host-owned packets).
384
385
 
385
386
  | Export | Kind | Meaning |
386
387
  | --- | --- | --- |
387
- | `EvidenceTier` | type | `'declared' \| 'shape' \| 'attested' \| 'verified'` — what the verifier party actually did. |
388
+ | `EvidenceTier` | type | `'declared' \| 'shape' \| 'attested' \| 'verified'`: what the verifier party actually did. |
388
389
  | `EvidencePayloadRefKind` | type | `'inline' \| 'mirror' \| 'archive' \| 'external' \| 'withheld'`. |
389
- | `EvidencePayloadRef` | type | `{ kind, uri?, record_hash? }` (`uri` / `record_hash` are string-or-null) — `uri` for archive/external locations; `record_hash` when the payload is itself a signed atrib record. |
390
- | `EvidencePayload` | type | `{ hash, media_type?, ref?, inline? }` — `hash` is a `"sha256:" + hex` commitment to the raw evidence material; `inline` only when `ref.kind === 'inline'`, never public. The type is lenient; normative validation requires `ref`. |
390
+ | `EvidencePayloadRef` | type | `{ kind, uri?, record_hash? }` (`uri` and `record_hash` are string-or-null). `uri` for archive/external locations; `record_hash` when the payload is itself a signed atrib record. |
391
+ | `EvidencePayload` | type | `{ hash, media_type?, ref?, inline? }`: `hash` is a `"sha256:" + hex` commitment to the raw evidence material; `inline` only when `ref.kind === 'inline'`, never public. The type is lenient; normative validation requires `ref`. |
391
392
  | `EvidenceConstraint` | type | `{ type, status: 'passed' \| 'failed' \| 'unresolved' \| 'not_checked', expected?, actual? }`. |
392
- | `EvidenceEnvelope` | type | `{ envelope: 1, profile, profile_version, tier, payload, facts?, result?, verifier? }` — one envelope schema, N profiles identified by absolute HTTPS type URI. Normative validation requires `result`. |
393
+ | `EvidenceEnvelope` | type | `{ envelope: 1, profile, profile_version, tier, payload, facts?, result?, verifier? }`: one envelope schema, N profiles identified by absolute HTTPS type URI. Normative validation requires `result`. |
393
394
  | `evidenceEnvelopeKey(envelope)` | function | Dedup identity: `` `${profile} ${payload.hash}` ``. Multiple instances per key are permitted; consumers order by tier desc, then `checked_at_ms` desc, then verifier name. |
394
395
  | `evidenceTierRank(tier)` | function | Numeric rank, `0` (declared) … `3` (verified); unknown tiers rank `-1`. |
395
396
  | `buildEvidenceEnvelope(input)` | async function | Producer-side builder: computes `payload.hash` from `payload.material` (JCS rule) or `hash_rule: 'raw'` (UTF-8 rule), fills the default `result`, and validates via the peer. Returns `{ envelope, validation, warnings }` with `envelope: null` on rejection or missing peer; throws `TypeError` only on contradictory input (hash AND material, `hash_rule` without material, neither). |
@@ -403,14 +404,14 @@ extension document under `docs/extensions/dev.atrib-attribution/`.
403
404
 
404
405
  | Export | Kind | Meaning |
405
406
  | --- | --- | --- |
406
- | `ATTRIBUTION_EXTENSION_KEY` | const | `'dev.atrib/attribution'` — the `_meta` key. Aliases `@atrib/mcp`'s `ATTRIBUTION_EXTENSION_ID` (also re-exported). |
407
+ | `ATTRIBUTION_EXTENSION_KEY` | const | `'dev.atrib/attribution'`: the `_meta` key. Aliases `@atrib/mcp`'s `ATTRIBUTION_EXTENSION_ID` (also re-exported). |
407
408
  | `ATTRIBUTION_LOG_SUBMISSION_STATUSES` | const | The four known statuses, re-exported from `@atrib/mcp`. |
408
409
  | `AttributionLogSubmissionStatus` | type | `'queued' \| 'submitted' \| 'disabled' \| 'failed'`; unknown future values pass through as strings. A queue status, never an awaited proof ([§5.3.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#535-log-submission)). |
409
- | `AttributionReceipt` | type | `{ record_hash?, creator_key?, context_id?, event_type?, chain_root?, log_submission? }` — all optional strings. |
410
- | `AttributionReceiptBlock` | type | `{ token?, receipt?, record? }` — the [§1.5.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#152-http-transport-tracestate) propagation token, the receipt, and optionally the full signed record for immediate Tier-3 re-verification. |
411
- | `VerifiedAttributionReceipt` | type | `{ block, verification }` — what the daemon client attaches to attest/recall results: the parsed block plus the [§6.2](https://github.com/creatornader/atrib/blob/main/docs/extensions/dev.atrib-attribution/v0.1.md#62-receipt-block) integrity outcome. |
410
+ | `AttributionReceipt` | type | `{ record_hash?, creator_key?, context_id?, event_type?, chain_root?, log_submission? }`: all optional strings. |
411
+ | `AttributionReceiptBlock` | type | `{ token?, receipt?, record? }`: the [§1.5.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#152-http-transport-tracestate) propagation token, the receipt, and optionally the full signed record for immediate Tier-3 re-verification. |
412
+ | `VerifiedAttributionReceipt` | type | `{ block, verification }`: what the daemon client attaches to attest/recall results: the parsed block plus the [§6.2](https://github.com/creatornader/atrib/blob/main/docs/extensions/dev.atrib-attribution/v0.1.md#62-receipt-block) integrity outcome. |
412
413
  | `parseAttributionReceiptBlock(meta)` | function | Lenient extraction from a tool result's `_meta`: anything malformed yields `null`, never a throw; wrong-typed fields are dropped; an all-dropped receipt counts as absent. |
413
- | `verifyAttributionReceipt(block)` | function | Re-exported from `@atrib/mcp`: the extension-spec [§6.2](https://github.com/creatornader/atrib/blob/main/docs/extensions/dev.atrib-attribution/v0.1.md#62-receipt-block) consumer check over the RAW result block — structural well-formedness plus token ↔ receipt ↔ (optional) record internal consistency. Returns `AttributionReceiptVerification` `{ valid, mismatched }` (`['malformed']` for non-blocks). Internal consistency only; not a proof. |
414
+ | `verifyAttributionReceipt(block)` | function | Re-exported from `@atrib/mcp`: the extension-spec [§6.2](https://github.com/creatornader/atrib/blob/main/docs/extensions/dev.atrib-attribution/v0.1.md#62-receipt-block) consumer check over the RAW result block: structural well-formedness plus internal consistency across token, receipt, and the optional record. Returns `AttributionReceiptVerification` `{ valid, mismatched }` (`['malformed']` for non-blocks). Internal consistency only; not a proof. |
414
415
  | `checkAttributionReceiptConsistency(block, record?)` | function | Record-side consistency: checks a parsed block's claims against the signed record they name (attached or caller-retrieved). No record at all → `{ receipt_valid: false, mismatched_fields: ['record'] }` (conservative, nothing to check against). |
415
416
 
416
417
  ### Record-layer re-exports
@@ -421,74 +422,74 @@ record layer, re-exported verbatim from `@atrib/mcp` (grouped as in
421
422
 
422
423
  **Types + event vocabulary.**
423
424
 
424
- - `EVENT_TYPE_TOOL_CALL_URI`, `EVENT_TYPE_TRANSACTION_URI`, `EVENT_TYPE_OBSERVATION_URI`, `EVENT_TYPE_DIRECTORY_ANCHOR_URI`, `EVENT_TYPE_ANNOTATION_URI`, `EVENT_TYPE_REVISION_URI` — the six normative event-type URIs.
425
- - `EVENT_TYPE_SHORT_NAMES` — the six short aliases accepted by agent-facing tools.
426
- - `EVENT_TYPE_SHORT_TO_URI` — short alias → canonical URI map.
427
- - `isNormativeEventTypeUri(uri)` — membership in the normative set (informational).
428
- - `isValidEventTypeUri(value)` — [§1.4.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#145-event_type-uri-validation) syntactic URI validation (extension URIs pass).
429
- - `normalizeEventType(value)` — short alias / known typo path → canonical URI; unknown values pass through.
425
+ - `EVENT_TYPE_TOOL_CALL_URI`, `EVENT_TYPE_TRANSACTION_URI`, `EVENT_TYPE_OBSERVATION_URI`, `EVENT_TYPE_DIRECTORY_ANCHOR_URI`, `EVENT_TYPE_ANNOTATION_URI`, `EVENT_TYPE_REVISION_URI`: the six normative event-type URIs.
426
+ - `EVENT_TYPE_SHORT_NAMES`: the six short aliases accepted by agent-facing tools.
427
+ - `EVENT_TYPE_SHORT_TO_URI`: short alias → canonical URI map.
428
+ - `isNormativeEventTypeUri(uri)`: membership in the normative set (informational).
429
+ - `isValidEventTypeUri(value)`: [§1.4.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#145-event_type-uri-validation) syntactic URI validation (extension URIs pass).
430
+ - `normalizeEventType(value)`: short alias / known typo path → canonical URI; unknown values pass through.
430
431
 
431
432
  **Canonicalization ([§1.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#13-canonical-serialization)).**
432
433
 
433
- - `canonicalRecord(record)` — JCS bytes of the complete signed record (the record-hash preimage).
434
- - `canonicalSigningInput(record)` — JCS bytes with `signature` removed (the signing input).
435
- - `canonicalCrossAttestationInput(record)` — [§1.7.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#176-cross-attestation-requirement-for-transaction-records) bytes with `signers: []` and no top-level `signature`.
434
+ - `canonicalRecord(record)`: JCS bytes of the complete signed record (the record-hash preimage).
435
+ - `canonicalSigningInput(record)`: JCS bytes with `signature` removed (the signing input).
436
+ - `canonicalCrossAttestationInput(record)`: [§1.7.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#176-cross-attestation-requirement-for-transaction-records) bytes with `signers: []` and no top-level `signature`.
436
437
 
437
438
  **Signing + verification ([§1.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#14-signing-and-verification)).**
438
439
 
439
- - `getPublicKey(privateKey)` — raw 32-byte Ed25519 public key for a 32-byte seed.
440
- - `signRecord(record, privateKey)` — [§1.4.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#142-signing-procedure) signing; returns the record with `signature` set.
441
- - `signTransactionRecord(record, privateKey, counterpartySigners?)` — signs the cross-attestation bytes; creator's signer entry first.
442
- - `signTransactionAttestation(record, privateKey)` — one counterparty `SignerEntry` over an existing transaction record's bytes.
443
- - `verifyRecord(record)` — [§1.4.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#143-verification-procedure) verification, all steps.
440
+ - `getPublicKey(privateKey)`: raw 32-byte Ed25519 public key for a 32-byte seed.
441
+ - `signRecord(record, privateKey)`: [§1.4.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#142-signing-procedure) signing; returns the record with `signature` set.
442
+ - `signTransactionRecord(record, privateKey, counterpartySigners?)`: signs the cross-attestation bytes; creator's signer entry first.
443
+ - `signTransactionAttestation(record, privateKey)`: one counterparty `SignerEntry` over an existing transaction record's bytes.
444
+ - `verifyRecord(record)`: [§1.4.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#143-verification-procedure) verification, all steps.
444
445
 
445
446
  **Hashing + encoding.**
446
447
 
447
- - `sha256(bytes)` — SHA-256 digest.
448
- - `base64urlEncode` / `base64urlDecode` — base64url, no padding.
449
- - `hexEncode` / `hexDecode` — lowercase hex.
448
+ - `sha256(bytes)`: SHA-256 digest.
449
+ - `base64urlEncode` / `base64urlDecode`: base64url, no padding.
450
+ - `hexEncode` / `hexDecode`: lowercase hex.
450
451
 
451
452
  **Chain composition ([§1.2.3](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#123-chain_root-for-genesis-records) / [§1.2.3.1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#1231-multi-producer-chain-composition)).**
452
453
 
453
- - `genesisChainRoot(contextId)` — `"sha256:" + hex(SHA-256(UTF-8(context_id)))`.
454
- - `chainRoot(parentRecord)` — chain_root for a non-genesis record.
455
- - `resolveChainRoot(opts)` — the [D067](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d067-multi-producer-chain-composition-precedence-contract) precedence contract (token > autoChain tail > env var > mirror tail > synthetic genesis). Never reimplement chain selection.
454
+ - `genesisChainRoot(contextId)`: `"sha256:" + hex(SHA-256(UTF-8(context_id)))`.
455
+ - `chainRoot(parentRecord)`: chain_root for a non-genesis record.
456
+ - `resolveChainRoot(opts)`: the [D067](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d067-multi-producer-chain-composition-precedence-contract) precedence contract (token > autoChain tail > env var > mirror tail > synthetic genesis). Never reimplement chain selection.
456
457
 
457
458
  **Propagation ([§1.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#15-context-propagation)).**
458
459
 
459
- - `encodeToken(record)` / `decodeToken(token)` — the [§1.5.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#152-http-transport-tracestate) propagation token (`base64url(record_hash) + "." + base64url(creator_key)`; lenient decode returns `null`).
460
- - `extractTraceId(traceparent)` — trace-id from a W3C `traceparent` header.
461
- - `mergeTracestate(atribEntry, existing)` / `parseTracestateAtrib(tracestate)` — atrib member handling in W3C `tracestate`.
462
- - `mergeBaggageAtribSession(sessionToken, existing)` / `parseBaggageAtribSession(baggage)` — session token in W3C `baggage`.
463
- - `readInboundContext(params)` / `writeOutboundContext(...)` — MCP `params._meta` context reading/writing ([§1.5.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#154-mcp-transport-params_meta)).
460
+ - `encodeToken(record)` / `decodeToken(token)`: the [§1.5.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#152-http-transport-tracestate) propagation token (`base64url(record_hash) + "." + base64url(creator_key)`; lenient decode returns `null`).
461
+ - `extractTraceId(traceparent)`: trace-id from a W3C `traceparent` header.
462
+ - `mergeTracestate(atribEntry, existing)` / `parseTracestateAtrib(tracestate)`: atrib member handling in W3C `tracestate`.
463
+ - `mergeBaggageAtribSession(sessionToken, existing)` / `parseBaggageAtribSession(baggage)`: session token in W3C `baggage`.
464
+ - `readInboundContext(params)` / `writeOutboundContext(...)`: MCP `params._meta` context reading/writing ([§1.5.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#154-mcp-transport-params_meta)).
464
465
 
465
466
  **Content identity ([§1.2.2](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#122-content_id-derivation)).**
466
467
 
467
- - `computeContentId(serverUrl, toolName)` — `"sha256:" + hex(SHA-256(normalized + ":" + tool))`.
468
- - `normalizeServerUrl(url)` — WHATWG-semantics URL normalization feeding `content_id`.
468
+ - `computeContentId(serverUrl, toolName)`: `"sha256:" + hex(SHA-256(normalized + ":" + tool))`.
469
+ - `normalizeServerUrl(url)`: WHATWG-semantics URL normalization feeding `content_id`.
469
470
 
470
471
  **Log entry serialization ([§2.3.1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#231-entry-serialization)).**
471
472
 
472
- - `serializeEntry(input)` — the 90-byte fixed log entry.
473
- - `eventTypeUriToByte(uri)` — event_type byte mapping (extensions → `0xFF`).
473
+ - `serializeEntry(input)`: the 90-byte fixed log entry.
474
+ - `eventTypeUriToByte(uri)`: event_type byte mapping (extensions → `0xFF`).
474
475
 
475
476
  **Submission-side validation ([§2.6.1](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#261-submit-entry) client parity).**
476
477
 
477
- - `validateSubmission(record)` — client-side mirror of the log's submission validation; returns `ValidationResult`.
478
+ - `validateSubmission(record)`: client-side mirror of the log's submission validation; returns `ValidationResult`.
478
479
 
479
480
  **Mirror conventions ([§5.9](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#59-local-mirror-conventions)).**
480
481
 
481
- - `readMirrorTail(...)` — newest record on a mirror file.
482
- - `inheritChainContext(...)` — mirror-based chain inheritance for new producers.
483
- - `recordHashExistsInMirror(...)` — presence check by record hash.
482
+ - `readMirrorTail(...)`: newest record on a mirror file.
483
+ - `inheritChainContext(...)`: mirror-based chain inheritance for new producers.
484
+ - `recordHashExistsInMirror(...)`: presence check by record hash.
484
485
 
485
486
  **Context identity ([D078](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d078-mcp-servers-honor-atrib_context_id-env-as-context_id-default)/[D083](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d083-harness-session-id-discovery-extends-d078-for-cognitive-primitive-mcp-servers)).**
486
487
 
487
- - `resolveEnvContextId(env?)` — `ATRIB_CONTEXT_ID`, then the harness discovery registry (Claude Code, Codex, file fallbacks).
488
+ - `resolveEnvContextId(env?)`: `ATRIB_CONTEXT_ID`, then the harness discovery registry (Claude Code, Codex, file fallbacks).
488
489
 
489
490
  **Submission queue ([§5.3.5](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#535-log-submission)).**
490
491
 
491
- - `createSubmissionQueue(...)` — the non-blocking, bounded-retry log submitter with per-record-hash proof caching.
492
+ - `createSubmissionQueue(...)`: the non-blocking, bounded-retry log submitter with per-record-hash proof caching.
492
493
 
493
494
  **Type re-exports.** `AtribRecord`, `UnsignedAtribRecord`, `SignerEntry`,
494
495
  `ChainContext`, `DecodedToken`, `EntryInput`, `ProofBundle`,
@@ -496,26 +497,26 @@ record layer, re-exported verbatim from `@atrib/mcp` (grouped as in
496
497
 
497
498
  **Anchor plurality ([D138](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d138-anchor-plurality-as-the-default-trust-posture), [§2.11.7-§2.11.13](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#2117-anchors-generalizing-the-replication-target)), re-exported from `@atrib/mcp`.**
498
499
 
499
- - `ANCHOR_TYPES` — the [§2.11.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#2118-anchor-type-registry) v1 registry (`atrib-log`, `sigstore-rekor`, `rfc3161-tsa`, `opentimestamps`).
500
- - `BUILT_IN_DEFAULT_ANCHOR_SET` — the two-anchor zero-config default ([§2.11.12](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#21112-producer-side-anchor-posture) rule 1).
501
- - `resolveAnchorPosture(config)` / `resolveEffectiveAnchors(config)` — the pure [§2.11.12](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#21112-producer-side-anchor-posture) posture/effective-set resolution.
502
- - `createAnchorFanout(options)` / `submitToAnchors(...)` — the per-anchor transport fan-out the client uses on in-process attests; exported for hosts that anchor records themselves.
500
+ - `ANCHOR_TYPES`: the [§2.11.8](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#2118-anchor-type-registry) v1 registry (`atrib-log`, `sigstore-rekor`, `rfc3161-tsa`, `opentimestamps`).
501
+ - `BUILT_IN_DEFAULT_ANCHOR_SET`: the two-anchor zero-config default ([§2.11.12](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#21112-producer-side-anchor-posture) rule 1).
502
+ - `resolveAnchorPosture(config)` / `resolveEffectiveAnchors(config)`: the pure [§2.11.12](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#21112-producer-side-anchor-posture) posture/effective-set resolution.
503
+ - `createAnchorFanout(options)` / `submitToAnchors(...)`: the per-anchor transport fan-out the client uses on in-process attests; exported for hosts that anchor records themselves.
503
504
  - Types `AnchorType`, `AnchorDescriptor`, `AnchorSetConfig`, `AnchorPostureResolution`, `AnchorConfigSidecarMarker`, `AnchorFanout`, `AnchorFanoutTicket`, `AnchorSubmissionOutcome`, `AnchorSubmissionStatus`.
504
505
 
505
506
  **Key handling ([§5.6](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#56-key-management)), re-exported from `@atrib/emit`.**
506
507
 
507
- - `resolveKey()` — the async key ladder: `ATRIB_PRIVATE_KEY` env → `ATRIB_KEY_FILE` → macOS Keychain → 1Password; `null` (pass-through) when nothing resolves.
508
- - `emitInProcess(input, options?)` — the in-process write engine the SDK's fallback path uses; exported for hosts that want it directly.
508
+ - `resolveKey()`: the async key ladder: `ATRIB_PRIVATE_KEY` env → `ATRIB_KEY_FILE` → macOS Keychain → 1Password; `null` (pass-through) when nothing resolves.
509
+ - `emitInProcess(input, options?)`: the in-process write engine the SDK's fallback path uses; exported for hosts that want it directly.
509
510
  - Types `EmitOutput`, `ResolvedKey`.
510
511
 
511
512
  ## Conformance
512
513
 
513
- `test/` runs the shared corpora — `spec/conformance/1.4/` (signing +
514
+ `test/` runs the shared corpora: `spec/conformance/1.4/` (signing +
514
515
  adversarial), `1.2.6/` (provenance_token), `1.2.3/multi-producer/`
515
516
  (chain-root precedence), `2.6.1/` (submission validation, client-side),
516
517
  `evidence-envelope/` ([D137](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d137-universal-evidence-envelope-as-the-single-protocol-level-attachment-model) shape/build/validate), and the
517
518
  `mcp-extension/` receipt cases ([D141](https://github.com/creatornader/atrib/blob/main/DECISIONS.md#d141-devatribattribution-first-class-mcp-extension-sep-2133) `verifyAttributionReceipt` +
518
- consistency semantics) — against this package's exported surface. The
519
+ consistency semantics), against this package's exported surface. The
519
520
  corpora are fixtures, not inspiration: any failure is a spec-bug
520
521
  discovery, not something to route around.
521
522
 
@@ -523,3 +524,7 @@ discovery, not something to route around.
523
524
 
524
525
  v0.1.0, unpublished (first-publish pending; see
525
526
  `docs/publishing-new-npm-package.md` and the Changesets ignore list).
527
+
528
+ ## Part of atrib
529
+
530
+ atrib is an open protocol for verifiable agent actions. Every action becomes a signed, chain-linked record that anyone can verify against a public Merkle log, with no operator to trust. This package is one entrypoint. See the [full package family](https://github.com/creatornader/atrib#packages) and the [protocol spec](https://github.com/creatornader/atrib/blob/main/atrib-spec.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atrib/sdk",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
13
13
  "files": [
14
14
  "dist"
15
15
  ],
16
- "description": "Consolidated client SDK for Atrib's verifiable action layer. Provides attest() and recall() verbs over a daemon-first runtime with in-process signing fallback, anchor-set submission, and the full record layer re-exported from @atrib/mcp.",
16
+ "description": "Consolidated client SDK for atrib's verifiable action layer. Provides attest() and recall() verbs with a daemon-first runtime and in-process fallback.",
17
17
  "author": "atrib <hello@atrib.dev>",
18
18
  "license": "Apache-2.0",
19
19
  "homepage": "https://atrib.dev",
@@ -31,13 +31,13 @@
31
31
  ],
32
32
  "dependencies": {
33
33
  "@modelcontextprotocol/sdk": "^1.29.0",
34
- "@atrib/emit": "0.17.0",
35
- "@atrib/mcp": "0.19.0"
34
+ "@atrib/emit": "0.17.1",
35
+ "@atrib/mcp": "0.19.1"
36
36
  },
37
37
  "peerDependencies": {
38
- "@atrib/recall": "0.14.4",
39
- "@atrib/verify": "0.8.0",
40
- "@atrib/verify-mcp": "0.2.18"
38
+ "@atrib/recall": "0.14.5",
39
+ "@atrib/verify": "0.8.1",
40
+ "@atrib/verify-mcp": "0.2.19"
41
41
  },
42
42
  "peerDependenciesMeta": {
43
43
  "@atrib/recall": {
@@ -54,9 +54,9 @@
54
54
  "@types/node": "^25.9.3",
55
55
  "typescript": "^6.0.3",
56
56
  "vitest": "^4.1.8",
57
- "@atrib/recall": "0.14.4",
58
- "@atrib/verify": "0.8.0",
59
- "@atrib/verify-mcp": "0.2.18"
57
+ "@atrib/recall": "0.14.5",
58
+ "@atrib/verify": "0.8.1",
59
+ "@atrib/verify-mcp": "0.2.19"
60
60
  },
61
61
  "repository": {
62
62
  "type": "git",