@atrib/emit 0.4.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or a Contribution
+      incorporated within the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this License
+      for that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the attribution
+          notices contained within such NOTICE file, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, modify, or distribute
+      those modifications in accordance with this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in question. Also, an optional
+      "Statement of Purpose" appears after the copyright notice.
+
+   Copyright 2025-2026 Atrib contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,140 @@
+# `@atrib/atrib-emit`
+
+MCP server exposing the explicit `emit` tool — the producer-side cognitive primitive that lets an agent sign observations, annotations, and revisions under its own atrib identity, beyond what `@atrib/mcp` auto-signs.
+
+## Why this exists
+
+`@atrib/mcp` middleware auto-signs every MCP tool call as it passes through. That captures the *mechanical* record-of-tool-call. But agents do plenty of cognitive work that doesn't go through MCP:
+- Built-in tool calls (Read, Edit, Bash) don't pass through any MCP server.
+- Reasoning steps, decisions, and revisions live in the agent's prose, not in a tool invocation.
+- Annotations against prior records ("this one mattered, future-self should weight it heavy") have no auto-emit hook.
+
+`atrib-emit` is the explicit signing tool the agent calls when it wants on-chain provenance for one of these. It complements `@atrib/mcp` rather than replacing it: the wrapper handles the mechanical capture; `atrib-emit` handles the explicit cognitive emit.
+
+## Tool surface
+
+```typescript
+mcp__atrib-emit__emit({
+  // Required
+  event_type: string,           // URI per spec §1.2.4. Common normative values:
+                                // 'https://atrib.dev/v1/types/observation', '...annotation', '...revision'.
+                                // Extension URIs in any namespace are also valid.
+  content: Record<string, unknown>,  // Semantic content of the event. Stored in the local mirror,
+                                     // committed on-chain via content_id derived from event_type leaf.
+
+  // Optional
+  context_id?: string,          // 32-hex. If omitted, atrib-emit auto-chains: it reads the
+                                // wrapper's local mirror and inherits the most-recent record's
+                                // context_id (or generates a fresh genesis if no mirror).
+  informed_by?: string[],       // sha256:<64-hex> record_hashes that informed this event.
+                                // Sorted lexicographically before signing per §1.2.5.
+  chain_root?: string,          // sha256:<64-hex>. Caller-managed chain_root, the hash of the
+                                // immediately preceding record under this context_id. Required
+                                // when caller threads chain state across emits (e.g. multi-record
+                                // watcher pipelines that emit a sequence under one context_id).
+                                // When omitted with context_id present, atrib-emit synthesizes
+                                // the genesis chain_root per spec §1.2.3. Without context_id,
+                                // chain_root is meaningless and returns warnings.
+  provenance_token?: string,    // 22-char base64url cross-session causal anchor per spec §1.2.6
+                                // / D044. Genesis-record-only: atrib-emit refuses to sign when
+                                // chain_root is non-genesis, returning warnings rather than
+                                // emitting a malformed record (§5.8 graceful-degradation).
+})
+```
+
+Returns:
+
+```typescript
+{
+  record_hash: string,             // sha256:<64-hex> of the signed canonical form
+  log_index: number | null,        // Position in the log if submission succeeded synchronously
+  inclusion_proof: object | null,  // Proof bundle if available; null if queued
+  context_id: string,              // The context_id the record was signed under
+  warnings: string[],              // E.g., 'submission queued, log unreachable'
+}
+```
+
+## Key resolution
+
+Same chain as the wrapper for the first three sources, plus a 1Password fallback for recovery:
+
+1. `ATRIB_PRIVATE_KEY` env var (legacy / dev path)
+2. `ATRIB_KEY_FILE` env var → file path containing the base64url-encoded 32-byte seed
+3. macOS Keychain — services tried in order:
+   - `atrib-creator-<ATRIB_AGENT>` (agent-scoped; matches wrapper, defaults `ATRIB_AGENT=claude-code`)
+   - `atrib-creator` (generic fallback)
+4. 1Password CLI recovery (off by default) — set `ATRIB_OP_REFERENCE=op://<vault>/<item>/<field>` to enable. Optional `ATRIB_OP_ACCOUNT=<email-or-uuid>` pins a specific account for multi-account operators. Activated only when Keychain has nothing; designed to recover from a wiped Keychain. The operator must be signed in (`op signin`) and the read may prompt for biometric/master-password approval.
+
+`atrib-emit` signs records under the **agent's** identity — the same key as the wrapper. There's no separate "emit identity"; skills don't have identities, the agent always signs as itself.
+
+If a 1Password item stores the seed with a `ATRIB_PRIVATE_KEY=<value>` label prefix (the convention used by the existing `Atrib key (current — haoZK4D1AXmy)` item), the prefix is stripped before decoding so both shapes work.
+
+## Configuration
+
+| Env var | Required | Purpose |
+|---|---|---|
+| `ATRIB_PRIVATE_KEY` | one of these | base64url Ed25519 seed (32 bytes) |
+| `ATRIB_KEY_FILE` | three | path to a 0600 file containing the seed |
+| (Keychain) | | macOS only; falls back here last |
+| `ATRIB_LOG_ENDPOINT` | optional | log submission endpoint; defaults to `https://log.atrib.dev/v1/entries` |
+| `ATRIB_MIRROR_FILE` | optional | JSONL path emit WRITES its own envelope mirror to; if unset, mirroring is skipped |
+| `ATRIB_AUTOCHAIN_SOURCE` | optional | JSONL path emit READS to inherit the wrapper's session context_id; defaults to the wrapper's local mirror under `~/.atrib/records/`. Splitting read/write paths lets emit write its own envelope mirror while still inheriting the wrapper's chain |
+| `ATRIB_AGENT` | optional | agent name for the agent-scoped Keychain service `atrib-creator-<agent>`; defaults to `claude-code` |
+| `ATRIB_KEYCHAIN_ACCOUNT` | optional | Keychain account; defaults to `userInfo().username` |
+
+## Installation in an MCP host
+
+For Claude Code or Claude Desktop, add to the MCP config:
+
+```jsonc
+{
+  "mcpServers": {
+    "atrib-emit": {
+      "command": "node",
+      "args": ["/abs/path/to/atrib/services/atrib-emit/dist/main.js"],
+      "env": {
+        "ATRIB_LOG_ENDPOINT": "https://log.atrib.dev/v1/entries",
+        "ATRIB_MIRROR_FILE": "/abs/path/to/.atrib/mirror.jsonl"
+      }
+    }
+  }
+}
+```
+
+Key resolution falls through to Keychain on macOS, so `ATRIB_PRIVATE_KEY` doesn't need to be in the env block (and shouldn't be, in production).
+
+## Architecture
+
+Three files do the work:
+
+- `src/index.ts` — McpServer registration; the `emit` tool calls `handleEmit` which orchestrates sign + submit + mirror.
+- `src/sign.ts` — Builds and signs the AtribRecord. Pure aside from the signing primitive itself; reuses `@atrib/mcp`'s `signRecord`, `computeContentId`, `getPublicKey`. Records produced by emit are byte-identical in canonical form to wrapper-signed records (verifier MUST NOT distinguish them).
+- `src/submit.ts` — wraps `@atrib/mcp`'s `createSubmissionQueue`. Same priority semantics as the wrapper (cognitive events use 'normal' priority).
+- `src/storage.ts` — Best-effort JSONL mirror of full record + proof, for local recall.
+
+Per §5.8 degradation contract: nothing in `atrib-emit` throws to the agent. Missing key → warning in the response. Sign failure → warning. Network failure → submission queued for retry.
+
+## autoChain inheritance from the wrapper
+
+When `context_id` is omitted, atrib-emit reads the wrapper's local mirror under `~/.atrib/records/` (override with `ATRIB_AUTOCHAIN_SOURCE`) and inherits the most-recent record's `context_id`, chaining its own emit on top of that record's hash. This is the cognitive-feedback-loop convention: explicit observations, annotations, and revisions chain seamlessly with the agent's mechanical tool calls in the same session, and a verifier sees one coherent chain per `context_id`.
+
+Resolution order:
+When the caller supplies both `context_id` and `chain_root`, atrib-emit uses both verbatim. This path is used by consumers that manage chain state themselves, such as nightly observation pipelines emitting a sequence of records under one context_id with explicit chain_root threading.
+
+When the caller supplies only `context_id`, atrib-emit synthesizes a genesis `chain_root` for that context_id, initiating a fresh chain.
+
+When no `context_id` is supplied but a wrapper mirror is present, atrib-emit inherits the most recent record's `context_id` and chains on top.
+
+When neither `context_id` nor a wrapper mirror is present, atrib-emit generates a fresh genesis with a random 16-byte context_id.
+
+Both line shapes are accepted at read time: bare `AtribRecord` (the wrapper's convention) and `{record, proof, written_at}` envelope (atrib-emit's storage convention). When inheritance fires, the response's `warnings` array carries `inherited context_id from wrapper mirror: <id>` so the agent can confirm the session it landed in.
+
+## What v1 does NOT do
+
+- **No semantic validation of `content`.** Caller passes any shape; the verifier eventually derives edges based on the spec for normative event types. v2 could add per-event-type schemas.
+- **No annotation-specific tool.** v1 has one `emit` tool that handles all event types. v2 will add `atrib-annotate` with annotation-specific affordances (importance picker, automatic `annotates` linkage to most recent action).
+- **No batch mode.** One emit per call. v2 if a high-volume producer needs it.
+
+## Test strategy
+
+`test/setup.ts` installs a fetch guard that refuses any submission to a production atrib endpoint (log/graph/directory/explore.atrib.dev). Same pattern as `@atrib/mcp` and `@atrib/agent`.

package/dist/auto-chain.d.ts

@@ -0,0 +1,61 @@
+import { type AtribRecord } from '@atrib/mcp';
+export interface ChainContext {
+    contextId: string;
+    chainRoot: string;
+    inheritedFrom: 'caller-supplied' | 'wrapper-mirror' | 'fresh';
+}
+/**
+ * Decide what context_id + chain_root the next emit record should use.
+ *
+ * When the caller supplies both context_id and chain_root, atrib-emit
+ * uses them verbatim (inheritedFrom: 'caller-supplied'). This path is
+ * used by consumers that manage chain state themselves, such as nightly
+ * observation pipelines emitting a sequence of records under one
+ * context_id with explicit chain_root threading.
+ *
+ * When the caller supplies only context_id, atrib-emit generates a
+ * genesis record for that context_id (chain_root = genesisChainRoot(
+ * context_id), inheritedFrom: 'fresh').
+ *
+ * When the caller supplies neither, atrib-emit inherits both fields
+ * from the most recent record in the wrapper's mirror file. If no
+ * mirror is available, it falls back to a fresh genesis context_id.
+ *
+ * Caller passes a chainRootForCallerContext callback that knows how to
+ * compute the genesis chain_root for a given context_id (we accept it as
+ * a parameter rather than depending on @atrib/mcp's genesisChainRoot
+ * directly, so this module stays trivially testable without pulling in
+ * the rest of the signing surface).
+ */
+export declare function resolveChainContext(opts: {
+    callerContextId?: string | undefined;
+    /**
+     * Caller-managed chain_root. Only honored when callerContextId is also
+     * supplied; chain_root without a context_id is meaningless and is treated
+     * as undefined here (the index.ts handler validates this case earlier and
+     * returns a warnings-only response).
+     */
+    callerChainRoot?: string | undefined;
+    /** Path override. Defaults to ATRIB_MIRROR_FILE env, then the wrapper's default. */
+    mirrorPath?: string | undefined;
+    /** Function returning genesis chain_root for a given context_id (spec §1.2.3). */
+    genesisChainRoot: (contextId: string) => string;
+    /** Random context_id generator (16 bytes hex). Injected for determinism in tests. */
+    randomContextId: () => string;
+}): Promise<ChainContext>;
+/**
+ * Read the JSONL mirror's last line and parse it as an AtribRecord.
+ * Returns null on any failure (missing file, empty file, malformed JSON,
+ * line missing required fields). Per §5.8 degradation: never throws.
+ *
+ * Implementation note: we read the whole file rather than seeking to the
+ * end. Mirror files are bounded (one entry per tool call within a session
+ * lifetime, single-digit MB at worst). If volume grows enough that this
+ * matters, switch to a tail read. Until then, simplicity wins.
+ */
+declare function readMostRecentRecord(path: string): Promise<AtribRecord | null>;
+export declare const __test_only__: {
+    readMostRecentRecord: typeof readMostRecentRecord;
+    DEFAULT_MIRROR: string;
+};
+export {};

package/dist/auto-chain.js

@@ -0,0 +1,135 @@
+// autoChain inheritance from the wrapper's local JSONL mirror.
+//
+// The wrapper service persists every signed record to a JSONL file under
+// ~/.atrib/records/. Each line is a bare AtribRecord, newest at EOF. When
+// atrib-emit runs in the same agent process, it can inherit the wrapper's
+// active context_id by reading the most-recent line and chain its emit on
+// top of that record (chain_root = sha256:<that record's hash>).
+//
+// This is the cognitive-feedback-loop convention: explicit observations
+// chain seamlessly with the agent's mechanical tool calls in the same
+// session, so the verifier sees one coherent chain per context_id.
+//
+// Per the scope doc design-question #2: same file as wrapper. Default path
+// is the wrapper's default; override with ATRIB_MIRROR_FILE.
+//
+// Failure mode: never throws. Missing file → no inheritance → genesis
+// record. Malformed last line → no inheritance → genesis record. The
+// wrapper's autoChain across restarts uses the same file with the same
+// silent-degradation contract.
+import { readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { canonicalRecord, hexEncode, sha256 } from '@atrib/mcp';
+// Default path is parameterized by ATRIB_AGENT so each agent gets its own
+// mirror file under ~/.atrib/records/. Wrappers that follow the same
+// convention will write to the same file and atrib-emit's autoChain picks
+// up inheritance for free. Wrappers that use a different filename should
+// have the operator set ATRIB_AUTOCHAIN_SOURCE explicitly.
+const DEFAULT_MIRROR = join(homedir(), '.atrib', 'records', `${process.env.ATRIB_AGENT ?? 'claude-code'}.jsonl`);
+/**
+ * Decide what context_id + chain_root the next emit record should use.
+ *
+ * When the caller supplies both context_id and chain_root, atrib-emit
+ * uses them verbatim (inheritedFrom: 'caller-supplied'). This path is
+ * used by consumers that manage chain state themselves, such as nightly
+ * observation pipelines emitting a sequence of records under one
+ * context_id with explicit chain_root threading.
+ *
+ * When the caller supplies only context_id, atrib-emit generates a
+ * genesis record for that context_id (chain_root = genesisChainRoot(
+ * context_id), inheritedFrom: 'fresh').
+ *
+ * When the caller supplies neither, atrib-emit inherits both fields
+ * from the most recent record in the wrapper's mirror file. If no
+ * mirror is available, it falls back to a fresh genesis context_id.
+ *
+ * Caller passes a chainRootForCallerContext callback that knows how to
+ * compute the genesis chain_root for a given context_id (we accept it as
+ * a parameter rather than depending on @atrib/mcp's genesisChainRoot
+ * directly, so this module stays trivially testable without pulling in
+ * the rest of the signing surface).
+ */
+export async function resolveChainContext(opts) {
+    if (opts.callerContextId) {
+        if (opts.callerChainRoot) {
+            return {
+                contextId: opts.callerContextId,
+                chainRoot: opts.callerChainRoot,
+                inheritedFrom: 'caller-supplied',
+            };
+        }
+        return {
+            contextId: opts.callerContextId,
+            chainRoot: opts.genesisChainRoot(opts.callerContextId),
+            inheritedFrom: 'fresh',
+        };
+    }
+    // Reads from ATRIB_AUTOCHAIN_SOURCE first, falling back to the wrapper's
+    // mirror path (NOT emit's own mirror — they serve different concerns).
+    // ATRIB_MIRROR_FILE controls where emit writes; ATRIB_AUTOCHAIN_SOURCE
+    // controls what emit reads to inherit context. In a typical setup they
+    // point at different files: emit writes its own mirror, but inherits the
+    // wrapper's session context.
+    const path = opts.mirrorPath ??
+        process.env['ATRIB_AUTOCHAIN_SOURCE'] ??
+        process.env['ATRIB_MIRROR_FILE'] ??
+        DEFAULT_MIRROR;
+    const inherited = await readMostRecentRecord(path);
+    if (inherited) {
+        const recordHashHex = hexEncode(sha256(canonicalRecord(inherited)));
+        return {
+            contextId: inherited.context_id,
+            chainRoot: `sha256:${recordHashHex}`,
+            inheritedFrom: 'wrapper-mirror',
+        };
+    }
+    const fresh = opts.randomContextId();
+    return {
+        contextId: fresh,
+        chainRoot: opts.genesisChainRoot(fresh),
+        inheritedFrom: 'fresh',
+    };
+}
+/**
+ * Read the JSONL mirror's last line and parse it as an AtribRecord.
+ * Returns null on any failure (missing file, empty file, malformed JSON,
+ * line missing required fields). Per §5.8 degradation: never throws.
+ *
+ * Implementation note: we read the whole file rather than seeking to the
+ * end. Mirror files are bounded (one entry per tool call within a session
+ * lifetime, single-digit MB at worst). If volume grows enough that this
+ * matters, switch to a tail read. Until then, simplicity wins.
+ */
+async function readMostRecentRecord(path) {
+    try {
+        const stats = await stat(path).catch(() => null);
+        if (!stats || stats.size === 0)
+            return null;
+        const contents = await readFile(path, 'utf-8');
+        const lines = contents.split('\n').filter((l) => l.trim().length > 0);
+        if (lines.length === 0)
+            return null;
+        const last = lines[lines.length - 1];
+        // Accept BOTH conventions:
+        //   (a) bare AtribRecord — the wrapper service's mirror writes one
+        //       record per line.
+        //   (b) envelope { record, proof?, written_at? } — atrib-emit's own
+        //       mirror writes this shape so it can preserve proof + timestamp
+        //       metadata for local recall. autoChain inheritance only needs the
+        //       record itself.
+        // Each line could come from either producer in a session that uses both.
+        const parsed = JSON.parse(last);
+        const candidate = 'record' in parsed && parsed.record ? parsed.record : parsed;
+        if (typeof candidate.context_id !== 'string' ||
+            typeof candidate.creator_key !== 'string' ||
+            typeof candidate.signature !== 'string') {
+            return null;
+        }
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+}
+export const __test_only__ = { readMostRecentRecord, DEFAULT_MIRROR };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { type ProofBundle, type SubmissionQueue } from '@atrib/mcp';
+import { type ResolvedKey } from './keys.js';
+declare const EmitInput: z.ZodObject<{
+    event_type: z.ZodString;
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    context_id: z.ZodOptional<z.ZodString>;
+    informed_by: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    chain_root: z.ZodOptional<z.ZodString>;
+    provenance_token: z.ZodOptional<z.ZodString>;
+    annotates: z.ZodOptional<z.ZodString>;
+    revises: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    event_type: string;
+    content: Record<string, unknown>;
+    chain_root?: string | undefined;
+    context_id?: string | undefined;
+    annotates?: string | undefined;
+    revises?: string | undefined;
+    informed_by?: string[] | undefined;
+    provenance_token?: string | undefined;
+}, {
+    event_type: string;
+    content: Record<string, unknown>;
+    chain_root?: string | undefined;
+    context_id?: string | undefined;
+    annotates?: string | undefined;
+    revises?: string | undefined;
+    informed_by?: string[] | undefined;
+    provenance_token?: string | undefined;
+}>;
+type EmitOutput = {
+    record_hash: string;
+    log_index: number | null;
+    inclusion_proof: ProofBundle['inclusion_proof'] | null;
+    context_id: string;
+    warnings: string[];
+};
+export interface AtribEmitServer {
+    /** Underlying McpServer; expose for testing or composition. */
+    mcp: McpServer;
+    /** Drain pending submissions (for tests/shutdown). */
+    flush(): Promise<void>;
+}
+export interface CreateAtribEmitServerOptions {
+    /** Override the resolved key (primarily for testing). */
+    key?: ResolvedKey;
+    /** Override the log endpoint (defaults to env or @atrib/mcp default). */
+    logEndpoint?: string | undefined;
+}
+/**
+ * Wire up the atrib-emit MCP server with one `emit` tool.
+ * Returns an AtribEmitServer handle whose `.mcp` is ready to attach to a
+ * transport (StdioServerTransport for the standalone binary; in-process
+ * transport for tests).
+ */
+export declare function createAtribEmitServer(options?: CreateAtribEmitServerOptions): Promise<AtribEmitServer>;
+interface HandleEmitInput {
+    input: z.infer<typeof EmitInput>;
+    key: ResolvedKey | null;
+    queue: SubmissionQueue;
+}
+/**
+ * Build, sign, submit, mirror. Returns the EmitOutput shape promised in the
+ * scope doc. Per §5.8 degradation: never throws to the agent; surfaces all
+ * partial-failure conditions in `warnings`.
+ */
+declare function handleEmit({ input, key, queue }: HandleEmitInput): Promise<EmitOutput>;
+export declare const __test_only__: {
+    handleEmit: typeof handleEmit;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,240 @@
+// atrib-emit MCP server: registers the explicit `emit` tool that lets an
+// agent sign arbitrary cognitive events (observations, annotations,
+// revisions) under its own identity. Reuses @atrib/mcp's signing and
+// submission primitives so emit-signed records are byte-identical to
+// wrapper-signed ones.
+//
+// Scope:
+//   - One tool: emit
+//   - One key per process (the agent's wrapper key)
+//   - Reuses @atrib/mcp signing + submission queue
+//   - Persists to the same JSONL convention as the wrapper
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { randomBytes } from 'node:crypto';
+import { EVENT_TYPE_ANNOTATION_URI, EVENT_TYPE_REVISION_URI, canonicalRecord, createSubmissionQueue, genesisChainRoot, hexEncode, isValidEventTypeUri, sha256, } from '@atrib/mcp';
+import { resolveChainContext } from './auto-chain.js';
+import { resolveKey } from './keys.js';
+import { buildAndSignEmitRecord } from './sign.js';
+import { mirrorRecord } from './storage.js';
+const SHA256_REF_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const HEX_32_PATTERN = /^[0-9a-f]{32}$/;
+// 16 bytes encoded as base64url with no padding = 22 chars per spec §1.2.6.
+const PROVENANCE_TOKEN_PATTERN = /^[A-Za-z0-9_-]{22}$/;
+const EmitInput = z.object({
+    event_type: z.string().min(1).max(256).describe("Event type URI per spec §1.2.4. Common normative values: " +
+        "'https://atrib.dev/v1/types/observation', '...annotation', '...revision'. " +
+        'Extension URIs in any namespace OK.'),
+    content: z.record(z.unknown()).describe('Semantic content of the cognitive event. Shape varies per event_type. ' +
+        "For observation: { what: string, why_noted?: string, topics?: string[] }. " +
+        "For annotation: { annotates: 'sha256:...', importance: 'critical'|'high'|'medium'|'low'|'noise', summary: string, topics?: string[] }. " +
+        "For revision: { revises: 'sha256:...', prior_position: string, new_position: string, reason: string }."),
+    context_id: z.string().regex(HEX_32_PATTERN).optional().describe('32-hex context_id. If omitted, a fresh genesis context_id is generated and the record is treated as a new chain.'),
+    informed_by: z.array(z.string().regex(SHA256_REF_PATTERN)).optional().describe("Array of 'sha256:<64-hex>' record_hashes that informed this event. " +
+        'Sorted lexicographically before signing per §1.2.5.'),
+    chain_root: z.string().regex(SHA256_REF_PATTERN).optional().describe("Caller-managed chain_root, the 'sha256:<64-hex>' hash of the immediately " +
+        'preceding record in this context_id. When supplied alongside context_id, ' +
+        'atrib-emit uses both verbatim instead of treating context_id as a fresh ' +
+        'genesis. Required when caller manages chain state across multiple emits ' +
+        "under one context_id (e.g. multi-record watcher pipelines). When omitted " +
+        'with context_id present, atrib-emit synthesizes the genesis chain_root ' +
+        'per spec §1.2.3. Without context_id, this field is meaningless and ' +
+        'returns a warnings-only response.'),
+    provenance_token: z.string().regex(PROVENANCE_TOKEN_PATTERN).optional().describe('22-char base64url cross-session causal anchor per spec §1.2.6 / D044. ' +
+        'Genesis-record-only: atrib-emit refuses to sign a record that carries ' +
+        'this field if its chain_root is not the genesis chain_root for the ' +
+        'context_id (per §5.8 graceful-degradation, this returns a warnings-only ' +
+        'response rather than a malformed record).'),
+    annotates: z.string().regex(SHA256_REF_PATTERN).optional().describe("'sha256:<64-hex>' record_hash this annotation describes per spec §1.2.7 / D058. " +
+        'REQUIRED when event_type is the annotation URI; FORBIDDEN on any other event_type. ' +
+        'atrib-emit enforces the require/forbid invariant per §1.2.7 (validators MUST reject ' +
+        'violations) and returns a warnings-only response rather than signing a malformed record.'),
+    revises: z.string().regex(SHA256_REF_PATTERN).optional().describe("'sha256:<64-hex>' record_hash this revision supersedes per spec §1.2.9 / D059. " +
+        'REQUIRED when event_type is the revision URI; FORBIDDEN on any other event_type. ' +
+        'atrib-emit enforces the require/forbid invariant per §1.2.9 (validators MUST reject ' +
+        'violations) and returns a warnings-only response rather than signing a malformed record.'),
+});
+/**
+ * Wire up the atrib-emit MCP server with one `emit` tool.
+ * Returns an AtribEmitServer handle whose `.mcp` is ready to attach to a
+ * transport (StdioServerTransport for the standalone binary; in-process
+ * transport for tests).
+ */
+export async function createAtribEmitServer(options = {}) {
+    const key = options.key ?? (await resolveKey());
+    const logEndpoint = options.logEndpoint ?? process.env['ATRIB_LOG_ENDPOINT'];
+    const queue = createSubmissionQueue(logEndpoint);
+    const mcp = new McpServer({ name: 'atrib-emit', version: '0.1.0' });
+    mcp.registerTool('emit', {
+        description: 'Sign and submit an explicit cognitive event (observation, annotation, revision, etc.) under your atrib identity. Emits a record that chains with your wrapper-signed tool calls when context_id is shared.',
+        inputSchema: EmitInput.shape,
+    }, async (rawInput) => {
+        const input = EmitInput.parse(rawInput);
+        const result = await handleEmit({ input, key, queue });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    return {
+        mcp,
+        flush: () => queue.flush(),
+    };
+}
+/**
+ * Build, sign, submit, mirror. Returns the EmitOutput shape promised in the
+ * scope doc. Per §5.8 degradation: never throws to the agent; surfaces all
+ * partial-failure conditions in `warnings`.
+ */
+async function handleEmit({ input, key, queue }) {
+    const warnings = [];
+    if (!isValidEventTypeUri(input.event_type)) {
+        return emptyOutput(input.context_id ?? randomContextId(), [
+            `event_type is not a valid absolute URI per §1.4.5: ${input.event_type}`,
+        ]);
+    }
+    if (!key) {
+        return emptyOutput(input.context_id ?? randomContextId(), [
+            'no signing key resolved (set ATRIB_PRIVATE_KEY, ATRIB_KEY_FILE, or store seed in macOS Keychain as service "atrib-creator")',
+        ]);
+    }
+    // chain_root without context_id is malformed: chain_root is meaningless
+    // outside the context it chains within. Surface a warning instead of
+    // synthesizing one of the two halves.
+    if (input.chain_root && !input.context_id) {
+        return emptyOutput(input.context_id ?? randomContextId(), [
+            'chain_root requires context_id (chain_root has no meaning without a context to chain within)',
+        ]);
+    }
+    // provenance_token is genesis-record-only per spec §1.2.6. If the caller
+    // also supplied chain_root, that chain_root must equal the genesis
+    // chain_root for the context_id. Middleware refuses to sign malformed
+    // records per §5.8 rather than emit something the validator + verifier
+    // would reject.
+    if (input.provenance_token && input.chain_root && input.context_id) {
+        const genesisRoot = genesisChainRoot(input.context_id);
+        if (input.chain_root !== genesisRoot) {
+            return emptyOutput(input.context_id, [
+                'provenance_token is genesis-record-only per §1.2.6; ' +
+                    'chain_root must equal genesisChainRoot(context_id) when provenance_token is supplied',
+            ]);
+        }
+    }
+    // annotates require/forbid invariant per spec §1.2.7 / D058. Validators MUST
+    // reject violations; we surface as warnings-only per §5.8 so callers see why
+    // we refused to sign rather than getting back a malformed record. Use the
+    // @atrib/mcp normative constant so the URI string lives in one place.
+    if (input.event_type === EVENT_TYPE_ANNOTATION_URI && !input.annotates) {
+        return emptyOutput(input.context_id ?? randomContextId(), [
+            'annotation event_type requires annotates per §1.2.7 (D058); ' +
+                'omitted records would fail validator admission',
+        ]);
+    }
+    if (input.annotates && input.event_type !== EVENT_TYPE_ANNOTATION_URI) {
+        return emptyOutput(input.context_id ?? randomContextId(), [
+            'annotates is FORBIDDEN on non-annotation event_types per §1.2.7 (D058); ' +
+                `received event_type=${input.event_type}`,
+        ]);
+    }
+    // revises require/forbid invariant per spec §1.2.9 / D059. Same shape as
+    // the annotates invariant above. Validators MUST reject violations; we
+    // surface as warnings-only per §5.8 so callers see why we refused to sign
+    // rather than getting back a malformed record.
+    if (input.event_type === EVENT_TYPE_REVISION_URI && !input.revises) {
+        return emptyOutput(input.context_id ?? randomContextId(), [
+            'revision event_type requires revises per §1.2.9 (D059); ' +
+                'omitted records would fail validator admission',
+        ]);
+    }
+    if (input.revises && input.event_type !== EVENT_TYPE_REVISION_URI) {
+        return emptyOutput(input.context_id ?? randomContextId(), [
+            'revises is FORBIDDEN on non-revision event_types per §1.2.9 (D059); ' +
+                `received event_type=${input.event_type}`,
+        ]);
+    }
+    // autoChain inheritance: when the caller omits context_id, read the
+    // wrapper's local mirror and inherit its most-recent record's context_id
+    // (chaining on top of that record's hash). Falls back to a fresh genesis
+    // when no mirror is present. The inheritance source is surfaced to the
+    // caller in the warnings array so the agent knows which session this
+    // emit landed in. When the caller supplies BOTH context_id and chain_root,
+    // resolveChainContext uses them verbatim — the path needed by consumers
+    // that thread chain state themselves.
+    const chain = await resolveChainContext({
+        callerContextId: input.context_id,
+        callerChainRoot: input.chain_root,
+        genesisChainRoot,
+        randomContextId,
+    });
+    const contextId = chain.contextId;
+    const chainRoot = chain.chainRoot;
+    if (chain.inheritedFrom === 'wrapper-mirror') {
+        warnings.push(`inherited context_id from wrapper mirror: ${contextId}`);
+    }
+    let record;
+    try {
+        record = await buildAndSignEmitRecord({
+            privateKey: key.privateKey,
+            eventType: input.event_type,
+            contextId,
+            chainRoot,
+            content: input.content,
+            informedBy: input.informed_by,
+            provenanceToken: input.provenance_token,
+            annotates: input.annotates,
+            revises: input.revises,
+        });
+    }
+    catch (e) {
+        return emptyOutput(contextId, [
+            `signing failed: ${e instanceof Error ? e.message : String(e)}`,
+        ]);
+    }
+    const recordHash = record.signature ? hashRecord(record) : null;
+    // Submit asynchronously; the queue handles retry + degradation per §5.8.
+    // Cognitive events default to normal priority — annotations/observations
+    // never need to block the agent.
+    queue.submit(record, 'normal');
+    // Best-effort mirror; mirrorRecord internally swallows errors per §5.8.
+    // Persist the pre-sign `content` payload as a `_local` sidecar so
+    // consumers (recall, trace, summarize) can surface semantic context
+    // alongside the cryptographic evidence. The sidecar lives at the
+    // envelope level — the signed record bytes are unchanged.
+    await mirrorRecord(record, queue.getProof(recordHash ?? '') ?? null, {
+        content: input.content,
+        producer: 'atrib-emit',
+    });
+    // Try to read a proof if the queue submitted synchronously and the log
+    // returned one within the same tick. Most submissions return null here
+    // and the proof shows up on a later poll via getProof.
+    const proof = recordHash ? queue.getProof(recordHash) ?? null : null;
+    if (!proof) {
+        warnings.push('submission queued; proof not yet available (poll the log later if needed)');
+    }
+    return {
+        record_hash: recordHash ?? 'sha256:unknown',
+        log_index: proof?.log_index ?? null,
+        inclusion_proof: proof?.inclusion_proof ?? null,
+        context_id: contextId,
+        warnings,
+    };
+}
+function emptyOutput(contextId, warnings) {
+    return {
+        record_hash: 'sha256:unknown',
+        log_index: null,
+        inclusion_proof: null,
+        context_id: contextId,
+        warnings,
+    };
+}
+function randomContextId() {
+    // 16 random bytes → 32 hex chars; matches the spec's context_id format.
+    return randomBytes(16).toString('hex');
+}
+function hashRecord(record) {
+    return `sha256:${hexEncode(sha256(canonicalRecord(record)))}`;
+}
+// Test-only export of handleEmit. Mirrors the `__test_only__` pattern
+// used in sign.ts; lets unit tests assert on the validation paths
+// without going through the McpServer transport surface.
+export const __test_only__ = { handleEmit };

package/dist/keys.d.ts

@@ -0,0 +1,21 @@
+export interface ResolvedKey {
+    privateKey: Uint8Array;
+    /** Source the key came from. Surfaced in startup logs so operators can confirm key provenance. */
+    source: 'env' | 'file' | 'keychain' | 'op';
+    /** Which Keychain service yielded the key, when source === 'keychain'. */
+    keychainService?: string;
+    /** The `op://` reference that yielded the key, when source === 'op'. */
+    opReference?: string;
+}
+/**
+ * Resolve the agent's signing key. Returns null when no key is available;
+ * callers run in pass-through mode (per §5.8 degradation) and the emit
+ * tool returns a warning rather than crashing.
+ *
+ * The agent name (defaults to 'claude-code', override with ATRIB_AGENT)
+ * picks the agent-scoped Keychain service first, falling back to the
+ * generic 'atrib-creator' service. This matches the wrapper exactly: a
+ * Keychain entry created via `atrib keygen --keychain --service
+ * atrib-creator-claude-code` resolves identically here and in the wrapper.
+ */
+export declare function resolveKey(): Promise<ResolvedKey | null>;

package/dist/keys.js

@@ -0,0 +1,104 @@
+// Key resolution chain for atrib-emit. MUST mirror the agent's wrapper
+// service resolution order exactly for the first three sources — emit
+// signs records under the same identity as the wrapper, so a divergence
+// here means the two producers would sign as different identities in the
+// same session, breaking the chain assumption and creating mystery keys
+// in the log.
+//
+// Resolution order (first hit wins):
+//   1. ATRIB_PRIVATE_KEY env var (legacy / dev path)
+//   2. ATRIB_KEY_FILE env var → 0600 file
+//   3. macOS Keychain, account = current user, services tried in order:
+//        - atrib-creator-<ATRIB_AGENT>  (agent-scoped; matches wrapper)
+//        - atrib-creator                (generic fallback)
+//   4. 1Password CLI (`op read`) — recovery path when Keychain is wiped.
+//      Off by default; enable by setting ATRIB_OP_REFERENCE to a valid
+//      `op://<vault>/<item>/<field>` reference. Requires the operator
+//      to be signed in (`op signin`) and willing to approve the read.
+//
+// The `op` fallback is deliberately last so that, in a healthy machine,
+// the seed never leaves Keychain. It only fires when Keychain is empty —
+// e.g., after a Keychain reset, fresh machine, or a corruption event.
+// In that case the seed flows through `op read` stdout into our process
+// memory; never touches argv (the reference contains no secret).
+//
+// Wrapper source of truth lives in the operator's internal repo; this
+// resolution chain must be kept in lockstep with that wrapper.
+import { readFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { userInfo } from 'node:os';
+import { base64urlDecode } from '@atrib/mcp';
+/**
+ * Resolve the agent's signing key. Returns null when no key is available;
+ * callers run in pass-through mode (per §5.8 degradation) and the emit
+ * tool returns a warning rather than crashing.
+ *
+ * The agent name (defaults to 'claude-code', override with ATRIB_AGENT)
+ * picks the agent-scoped Keychain service first, falling back to the
+ * generic 'atrib-creator' service. This matches the wrapper exactly: a
+ * Keychain entry created via `atrib keygen --keychain --service
+ * atrib-creator-claude-code` resolves identically here and in the wrapper.
+ */
+export async function resolveKey() {
+    const envSeed = process.env['ATRIB_PRIVATE_KEY'];
+    if (envSeed) {
+        return { privateKey: decodeSeed(envSeed), source: 'env' };
+    }
+    const filePath = process.env['ATRIB_KEY_FILE'];
+    if (filePath) {
+        const contents = (await readFile(filePath, 'utf-8')).trim();
+        return { privateKey: decodeSeed(contents), source: 'file' };
+    }
+    if (process.platform === 'darwin') {
+        const account = process.env['ATRIB_KEYCHAIN_ACCOUNT'] ?? userInfo().username;
+        const agent = process.env['ATRIB_AGENT'] ?? 'claude-code';
+        const services = [`atrib-creator-${agent}`, 'atrib-creator'];
+        for (const service of services) {
+            const result = spawnSync('security', ['find-generic-password', '-a', account, '-s', service, '-w'], { encoding: 'utf-8' });
+            if (result.status === 0) {
+                const seed = result.stdout.trim();
+                if (seed.length > 0) {
+                    return { privateKey: decodeSeed(seed), source: 'keychain', keychainService: service };
+                }
+            }
+        }
+    }
+    // 1Password recovery path (last resort). Activated only when
+    // ATRIB_OP_REFERENCE is set; the reference itself is non-secret.
+    // ATRIB_OP_ACCOUNT optionally pins which 1Password account, useful for
+    // operators with multiple accounts (e.g. personal + work).
+    const opReference = process.env['ATRIB_OP_REFERENCE'];
+    if (opReference) {
+        const args = ['read'];
+        const opAccount = process.env['ATRIB_OP_ACCOUNT'];
+        if (opAccount)
+            args.push('--account', opAccount);
+        args.push(opReference);
+        const result = spawnSync('op', args, { encoding: 'utf-8' });
+        if (result.status === 0) {
+            // 1Password items often store seeds with a label prefix like
+            // "ATRIB_PRIVATE_KEY=<seed>" so the operator can tell which field
+            // is which in the UI. Strip an optional `ATRIB_PRIVATE_KEY=` prefix
+            // before decoding so both shapes work.
+            const raw = result.stdout.trim();
+            const seed = raw.startsWith('ATRIB_PRIVATE_KEY=')
+                ? raw.slice('ATRIB_PRIVATE_KEY='.length).trim()
+                : raw;
+            if (seed.length > 0) {
+                return { privateKey: decodeSeed(seed), source: 'op', opReference };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Decode a base64url-encoded 32-byte Ed25519 seed. Throws if length wrong.
+ * Per spec §1.4.1: atrib uses 32-byte seeds, not the 64-byte NaCl format.
+ */
+function decodeSeed(b64url) {
+    const bytes = base64urlDecode(b64url.trim());
+    if (bytes.length !== 32) {
+        throw new Error(`atrib-emit: expected 32-byte Ed25519 seed, got ${bytes.length} bytes from key source`);
+    }
+    return bytes;
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// atrib-emit standalone binary. Wires the McpServer to a stdio transport
+// so it can be launched as a subprocess by an MCP host (Claude Code,
+// Claude Desktop, etc.).
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createAtribEmitServer } from './index.js';
+async function main() {
+    const { mcp } = await createAtribEmitServer();
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+    // Stays alive on the stdio transport until the host closes it.
+}
+main().catch((e) => {
+    console.error('atrib-emit: fatal', e instanceof Error ? e.stack ?? e.message : String(e));
+    process.exit(1);
+});

package/dist/sign.d.ts

@@ -0,0 +1,45 @@
+import { type AtribRecord } from '@atrib/mcp';
+export interface BuildEmitRecordInput {
+    privateKey: Uint8Array;
+    eventType: string;
+    contextId: string;
+    chainRoot: string;
+    /** Cognitive content. Used only for content_id derivation context; full content lives in the mirror. */
+    content: Record<string, unknown>;
+    informedBy?: string[] | undefined;
+    /**
+     * Optional cross-session causal anchor (spec §1.2.6 / D044). Caller is
+     * responsible for ensuring the genesis-record-only invariant holds; the
+     * index.ts handler validates this before reaching here.
+     */
+    provenanceToken?: string | undefined;
+    /**
+     * Optional annotates target per spec §1.2.7 / D058. Required when
+     * eventType is the annotation URI; FORBIDDEN on any other event_type.
+     * The index.ts handler enforces the require/forbid invariant before
+     * reaching here. Format: "sha256:" + 64 lowercase hex.
+     */
+    annotates?: string | undefined;
+    /**
+     * Optional revises target per spec §1.2.9 / D059. Required when
+     * eventType is the revision URI; FORBIDDEN on any other event_type.
+     * The index.ts handler enforces the require/forbid invariant before
+     * reaching here. Format: "sha256:" + 64 lowercase hex.
+     */
+    revises?: string | undefined;
+}
+/**
+ * Build, sign, and return a complete AtribRecord ready for submission.
+ * Pure aside from the signing primitive itself; no network I/O here.
+ */
+export declare function buildAndSignEmitRecord(input: BuildEmitRecordInput): Promise<AtribRecord>;
+/**
+ * Best-effort URI leaf extraction. For atrib-namespace URIs returns the
+ * trailing path segment (e.g. 'observation', 'annotation'); for extension
+ * URIs returns the URI itself.
+ */
+declare function leafOfEventTypeUri(uri: string): string;
+export declare const __test_only__: {
+    leafOfEventTypeUri: typeof leafOfEventTypeUri;
+};
+export {};

package/dist/sign.js

@@ -0,0 +1,60 @@
+// Build + sign an attribution record for the agent's emit call. Reuses
+// @atrib/mcp's signing primitives so emit-signed records are byte-identical
+// in canonical form to wrapper-signed records — a verifier MUST NOT be
+// able to distinguish "wrapper signed this" from "emit signed this."
+//
+// Per spec §1.2.2: content_id is a stable identifier for the *kind* of
+// action, not the specific invocation. The wrapper derives it from
+// server_url + tool_name; we use the synthetic pair (`mcp://atrib-emit` +
+// leaf of event_type URI), so all observations share content_id, all
+// annotations share content_id, etc. Per-emit distinctness comes from
+// (creator_key, context_id, timestamp) — same as the wrapper.
+//
+// The `content` argument never lands on-chain; the log stores commitments
+// only per spec §2.10. Full content lives in the local JSONL mirror for
+// the agent's own recall.
+import { computeContentId, getPublicKey, signRecord, base64urlEncode, } from '@atrib/mcp';
+const SYNTHETIC_SERVER_URL = 'mcp://atrib-emit';
+/**
+ * Build, sign, and return a complete AtribRecord ready for submission.
+ * Pure aside from the signing primitive itself; no network I/O here.
+ */
+export async function buildAndSignEmitRecord(input) {
+    const publicKey = base64urlEncode(await getPublicKey(input.privateKey));
+    const toolName = leafOfEventTypeUri(input.eventType);
+    const contentId = computeContentId(SYNTHETIC_SERVER_URL, toolName);
+    // informed_by must be sorted lexicographically per §1.2.5 to keep the
+    // canonical form stable across emitters. Omitted entirely (not null,
+    // not empty) when no references are given — presence affects JCS.
+    const informedBySorted = input.informedBy && input.informedBy.length > 0
+        ? [...input.informedBy].sort()
+        : undefined;
+    const record = {
+        spec_version: 'atrib/1.0',
+        content_id: contentId,
+        creator_key: publicKey,
+        chain_root: input.chainRoot,
+        event_type: input.eventType,
+        context_id: input.contextId,
+        timestamp: Date.now(),
+        signature: '',
+        ...(informedBySorted ? { informed_by: informedBySorted } : {}),
+        ...(input.annotates ? { annotates: input.annotates } : {}),
+        ...(input.provenanceToken ? { provenance_token: input.provenanceToken } : {}),
+        ...(input.revises ? { revises: input.revises } : {}),
+    };
+    return signRecord(record, input.privateKey);
+}
+/**
+ * Best-effort URI leaf extraction. For atrib-namespace URIs returns the
+ * trailing path segment (e.g. 'observation', 'annotation'); for extension
+ * URIs returns the URI itself.
+ */
+function leafOfEventTypeUri(uri) {
+    const slashIdx = uri.lastIndexOf('/');
+    if (slashIdx === -1)
+        return uri;
+    const leaf = uri.slice(slashIdx + 1);
+    return leaf.length > 0 ? leaf : uri;
+}
+export const __test_only__ = { leafOfEventTypeUri };

package/dist/storage.d.ts

@@ -0,0 +1,27 @@
+import type { AtribRecord } from '@atrib/mcp';
+import type { ProofBundle } from '@atrib/mcp';
+/**
+ * Pre-sign payload preserved locally. For atrib-emit, this is the original
+ * `content: { what, why_noted, topics, ... }` object the caller passed.
+ * Free-form per event_type (the same way `content` is on the input schema).
+ */
+export type LocalSidecar = {
+    /** Original pre-sign content payload as supplied by the caller. */
+    content?: Record<string, unknown>;
+    /** Producer that emitted this record, for cross-source disambiguation. */
+    producer?: string;
+};
+export interface MirrorLine {
+    record: AtribRecord;
+    proof: ProofBundle | null;
+    written_at: number;
+    /** Optional local-only sidecar; absent on legacy entries. */
+    _local?: LocalSidecar;
+}
+/**
+ * Append one record + optional proof + optional local sidecar to the
+ * mirror file. Failures log with the atrib-emit prefix and otherwise
+ * no-op — per §5.8 the mirror is best-effort and never blocks the
+ * agent.
+ */
+export declare function mirrorRecord(record: AtribRecord, proof: ProofBundle | null, localSidecar?: LocalSidecar): Promise<void>;

package/dist/storage.js

@@ -0,0 +1,56 @@
+// Local JSONL mirror — same convention as the wrapper, so atrib-recall
+// surfaces emit-signed records identically to wrapper-signed ones. Each
+// line is one envelope around a signed AtribRecord plus optional proof
+// and an OPTIONAL `_local` sidecar carrying pre-sign payload content.
+//
+// The `_local` sidecar is the local-only complement to the public log.
+// Public log gets only the signed AtribRecord (with content_id as the
+// commitment to the original content). Local mirror additionally keeps
+// the pre-sign content so consumers (recall, trace, summarize) can
+// surface semantic context — `topics`, `what`, `why_noted` — alongside
+// the cryptographic evidence. Without the sidecar, mirror readers see
+// only event_type + hashes and must guess at semantics.
+//
+// Sidecar shape rules:
+//   - Lives at the ENVELOPE level (not inside `record`). Never affects
+//     the signature — the signed bytes only ever contain the canonical
+//     AtribRecord fields.
+//   - Marked with underscore prefix (`_local`) per Python/etc. convention
+//     for "private to this layer".
+//   - Stripped at submission time by construction: the submission queue
+//     only ever sees the bare AtribRecord, so the sidecar can never
+//     leak to the public log.
+//   - Backward-compatible: existing mirror entries with no `_local`
+//     parse identically; readers must tolerate its absence.
+//
+// v1 keeps this minimal: append-only, no rotation, no compression. Path
+// defaults to ATRIB_MIRROR_FILE; if unset, mirroring is skipped (the
+// in-log record is still authoritative).
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+let ensuredDirs = new Set();
+/**
+ * Append one record + optional proof + optional local sidecar to the
+ * mirror file. Failures log with the atrib-emit prefix and otherwise
+ * no-op — per §5.8 the mirror is best-effort and never blocks the
+ * agent.
+ */
+export async function mirrorRecord(record, proof, localSidecar) {
+    const path = process.env['ATRIB_MIRROR_FILE'];
+    if (!path)
+        return;
+    const line = { record, proof, written_at: Date.now() };
+    if (localSidecar) {
+        line._local = localSidecar;
+    }
+    try {
+        if (!ensuredDirs.has(path)) {
+            await mkdir(dirname(path), { recursive: true });
+            ensuredDirs.add(path);
+        }
+        await appendFile(path, JSON.stringify(line) + '\n', 'utf-8');
+    }
+    catch (e) {
+        console.warn('atrib-emit: mirror append failed', e instanceof Error ? e.message : String(e));
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@atrib/emit",
+  "version": "0.4.0",
+  "description": "MCP server for atrib. The producer-side cognitive primitive: lets agents sign explicit observations, annotations, and revisions beyond what middleware auto-signs.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "atrib-emit": "./dist/main.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@noble/ed25519": "^2.3.0",
+    "@noble/hashes": "^1.8.0",
+    "zod": "^3.25.76",
+    "@atrib/mcp": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "start": "node dist/main.js",
+    "dev": "tsx src/main.ts",
+    "test": "vitest run"
+  }
+}