@atrib/attest 0.0.0

package/LICENSE

@@ -0,0 +1,216 @@
+
+                                 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, whether in Source or
+      Object form, 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 any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to 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 individual or Legal Entity
+      on behalf of whom a Contribution has been received by 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, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, 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 copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in 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 redistributing 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 consequential 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 any and 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. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.
+
+   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,187 @@
+# `@atrib/attest`
+
+atrib's write-verb home. One `attest` tool signs observations, annotations,
+and revisions under the agent's own atrib identity. The legacy `emit`,
+`atrib-annotate`, and `atrib-revise` tool names stay mounted as permanent
+aliases over the same handler, so records are byte-identical in canonical
+form regardless of which name signed them. This is the attest/recall rename
+([D164](../../DECISIONS.md#d164-attestrecall-verb-rename-and-primitive-surface-collapse)).
+
+## Install
+
+```bash
+pnpm add @atrib/attest
+```
+
+Verify a local build with `pnpm --filter @atrib/attest test`.
+
+## 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 cognitive
+work that doesn't go through MCP: reasoning steps, decisions, annotations
+against prior records, and revisions of a prior position all live in the
+agent's prose, not in a tool invocation. `attest` is the explicit signing
+tool the agent calls when it wants on-chain provenance for one of these.
+
+## The `attest` tool
+
+One handler, one `ref` argument decides the record shape:
+
+```typescript
+attest({
+  // Required. Free-form semantic content; committed through the default
+  // args_hash per D099. For annotations: { importance, summary, topics? }.
+  // For revisions: { prior_position, new_position }.
+  content: Record<string, unknown>,
+
+  // Optional: the declared relationship decides the signed record shape.
+  // There is no event_type argument; absent ref signs an observation.
+  ref?: {
+    kind: "annotates",
+    target: string,               // sha256:<64-hex> record_hash to annotate
+  } | {
+    kind: "revises",
+    target: string,               // sha256:<64-hex> record_hash to revise
+    reason: string,               // REQUIRED for a revision; composed into content
+  },
+
+  // Optional, same as the legacy emit tool
+  context_id?: string,
+  informed_by?: string[],
+  allow_unresolved_informed_by?: boolean,
+  chain_root?: string,
+  provenance_token?: string,
+  tool_name?: string,
+  args_hash?: string,
+  result_hash?: string,
+  producer?: string,              // sidecar label override; defaults to 'atrib-attest'
+})
+```
+
+### Ref mapping
+
+| `ref` argument | Signed record | Signed field carried |
+| --- | --- | --- |
+| absent | observation | none |
+| `{ kind: "annotates", target, ... }` | annotation | signed `annotates` field |
+| `{ kind: "revises", target, reason, ... }` (`reason` required) | revision | signed `revises` field |
+
+The three shapes route through the same `handleEmit` funnel used by the
+legacy tools. There is no separate signing path for `attest`: the ref
+argument decides which event_type byte and which signed field get attached
+before the record goes through the shared sign-and-mirror pipeline.
+
+## Legacy write tools stay mounted
+
+`emit`, `atrib-annotate`, and `atrib-revise` remain mounted as permanent
+aliases during the alias window described in the attest/recall rename
+([D164](../../DECISIONS.md#d164-attestrecall-verb-rename-and-primitive-surface-collapse)).
+Calling `atrib-annotate` and calling `attest` with `ref.kind: "annotates"`
+against the same target produce byte-identical annotation records: same key,
+same chain state, same `handleEmit` funnel. Only the `_local.producer`
+sidecar label differs between the two call paths.
+
+## Byte-identity
+
+A verifier cannot distinguish a record signed through `attest` from one
+signed through the legacy `emit`/`atrib-annotate`/`atrib-revise` names. Same
+signing key, same canonical form, same chain composition. The only
+observable difference is the `_local.producer` sidecar label, which is
+metadata for local mirror consumers, not signed protocol bytes.
+
+## Bins
+
+- **`atrib-attest`**: the MCP server. Long-lived stdio child. Serves the
+  four-tool write union: `attest` plus the three legacy write tool names
+  (`emit`, `atrib-annotate`, `atrib-revise`).
+- **`atrib-attest-cli`**: an in-process CLI, same wire contract as
+  `atrib-emit-cli`. Reads one JSON envelope on stdin, signs the record
+  in-process, writes the output JSON to stdout. Default producer label is
+  derived from the invoked bin name (`atrib-attest-cli` for this bin,
+  `atrib-emit-cli` when invoked under that name).
+
+The legacy bins `atrib-emit`, `atrib-emit-cli`, `atrib-local-substrate`,
+`atrib-annotate`, and `atrib-revise` still forward to this package's
+handlers through the `@atrib/emit`, `@atrib/annotate`, and `@atrib/revise`
+re-export shims.
+
+## Programmatic surface
+
+```typescript
+import {
+  createAtribAttestServer,       // mounts the four-tool write union
+  createAtribEmitServer,          // legacy factory; also mounts attest
+  createAtribAnnotateServer,      // legacy factory; also mounts attest
+  createAtribReviseServer,        // legacy factory; also mounts attest
+  handleAttest,
+  attestInProcess,
+
+  // Re-exported legacy emit surface
+  handleEmit,
+  emitInProcess,
+  EmitInput,
+  resolveKey,
+  emitSessionCheckpoint,
+} from "@atrib/attest";
+```
+
+Each legacy factory (`createAtribEmitServer`, `createAtribAnnotateServer`,
+`createAtribReviseServer`) mounts `attest` alongside its own named tool, so
+any MCP host wired to a legacy factory still gets the two-verb surface.
+
+## Configuration
+
+Environment variables are unchanged from the legacy emit surface:
+`ATRIB_PRIVATE_KEY`, `ATRIB_KEY_FILE`, `ATRIB_MIRROR_FILE`,
+`ATRIB_LOG_ENDPOINT`, `ATRIB_CONTEXT_ID`, `ATRIB_AUTOCHAIN_SOURCE`,
+`ATRIB_AGENT`, `ATRIB_KEYCHAIN_ACCOUNT`, `ATRIB_KEY_RESOLVE_RETRY_MS`,
+`ATRIB_REQUIRE_EXPLICIT_CONTEXT_ID`, `CLAUDE_CODE_SESSION_ID`,
+`CODEX_THREAD_ID`, `ATRIB_PARENT_RECORD_HASH`,
+`ATRIB_LOCAL_SUBSTRATE_ENDPOINT`, `ATRIB_LOCAL_SUBSTRATE_MODE`,
+`ATRIB_LOCAL_SUBSTRATE_TIMEOUT_MS`. See
+[`services/atrib-emit/README.md`](../atrib-emit/README.md) for the full
+table with descriptions; the values and resolution order carried over
+unchanged.
+
+## Degradation and privacy
+
+atrib failures never affect the primary call ([spec §5.8](../../atrib-spec.md#58-degradation-contract)), and for the write
+verb that contract is the most important thing to know:
+
+- **Log endpoint unreachable.** `attest` still returns `signed: true` with
+  the `record_hash`, the mirror write to `~/.atrib/records/` lands before
+  the tool returns, and log submission is queued and retried silently in
+  the background. The `warnings` array names the degradation (for example
+  "submission queued; proof not yet available"). Nothing throws; nothing
+  blocks.
+- **What stays local vs what reaches the public log.** The full `content`
+  body stays in the local mirror's `_local` sidecar; the signed record
+  carries only the replay-checkable `args_hash` commitment over it. The
+  public log stores the 90-byte commitment entry (record hash, creator key,
+  context_id, timestamp, event_type byte), never the content.
+- **Refused writes are loud, not silent.** A malformed call (unknown
+  `ref.kind`, missing revises reason, a `ref`/content contradiction, a
+  provenance_token off genesis, or no resolvable signing key) returns
+  `signed: false` with a `refusals` array over the MCP error surface and
+  signs nothing. The CLI exits 3 on refusal and still prints the structured
+  JSON, so hook callers can absorb the exit code without losing the reason.
+- **No key, no crash.** With no resolvable signing key the server stays up
+  and every write refuses with the key-resolution hint; pass-through per
+  [§5.8](../../atrib-spec.md#58-degradation-contract).
+
+## Conformance
+
+The attest/recall byte-identity, ref-mapping, and alias-window guarantees
+are pinned by the shared corpus at
+[`spec/conformance/attest-recall/`](../../spec/conformance/attest-recall/):
+byte-identity, ref-mapping, read-equivalence, alias-window,
+persisted-labels, and frozen-constants.
+
+## Part of atrib
+
+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](../../atrib-spec.md).

package/dist/annotate.d.ts

@@ -0,0 +1,56 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { type EmitLocalSubstrateShadowOptions, type WriteToolDeps } from './index.js';
+import { type ResolvedKey } from './keys.js';
+export declare const Importance: z.ZodEnum<{
+    high: "high";
+    critical: "critical";
+    medium: "medium";
+    low: "low";
+    noise: "noise";
+}>;
+export declare const AnnotateInput: z.ZodObject<{
+    annotates: z.ZodString;
+    importance: z.ZodEnum<{
+        high: "high";
+        critical: "critical";
+        medium: "medium";
+        low: "low";
+        noise: "noise";
+    }>;
+    summary: z.ZodString;
+    topics: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    context_id: z.ZodOptional<z.ZodString>;
+    informed_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export interface AtribAnnotateServer {
+    /** Underlying McpServer; expose for testing or composition. */
+    mcp: McpServer;
+    /** Drain pending submissions (for tests/shutdown). */
+    flush(): Promise<void>;
+}
+export interface CreateAtribAnnotateServerOptions {
+    /** Override the resolved key (primarily for testing). */
+    key?: ResolvedKey | null | undefined;
+    /** Override the log endpoint (defaults to env or @atrib/mcp default). */
+    logEndpoint?: string | undefined;
+    /**
+     * Optional long-lived-agent local substrate shadow probe. `undefined` reads
+     * opt-in env config; `false` disables env config for this server.
+     */
+    localSubstrate?: EmitLocalSubstrateShadowOptions | false | undefined;
+}
+/**
+ * Register the legacy `atrib-annotate` tool. The handler call shape is
+ * unchanged from the standalone @atrib/annotate server (no logEndpoint or
+ * reference-resolver threading), so historical behavior is preserved
+ * exactly; only the mounting surface moved.
+ */
+export declare function registerAnnotateTool(mcp: McpServer, deps: WriteToolDeps): void;
+/**
+ * Wire up the legacy atrib-annotate MCP server. Mounts `atrib-annotate`
+ * plus `attest` (alias-window rule W1). The underlying signing pipeline is
+ * shared via handleEmit so annotation records are byte-identical regardless
+ * of which tool produced them.
+ */
+export declare function createAtribAnnotateServer(options?: CreateAtribAnnotateServerOptions): Promise<AtribAnnotateServer>;

package/dist/annotate.js

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: Apache-2.0
+// The legacy `atrib-annotate` tool: cognitive primitive #2 of D079, kept as
+// a permanent alias over the attest write funnel. Narrows the schema to the
+// annotation event_type (spec §1.2.7 / D058) with the annotation-specific
+// required fields (annotates + importance + summary). The signing + chain
+// composition path is byte-identical to `attest` with ref.kind='annotates';
+// a verifier MUST NOT distinguish annotation records by the tool name that
+// signed them.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSubmissionQueue, EVENT_TYPE_ANNOTATION_URI } from '@atrib/mcp';
+import { handleEmit, registerAttestTool, resolveEmitLocalSubstrateShadowFromEnv, } from './index.js';
+import { resolveKey } from './keys.js';
+const SHA256_REF_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const HEX_32_PATTERN = /^[0-9a-f]{32}$/;
+export const Importance = z.enum(['critical', 'high', 'medium', 'low', 'noise']);
+export const AnnotateInput = z.object({
+    annotates: z.string().regex(SHA256_REF_PATTERN).describe("'sha256:<64-hex>' record_hash this annotation describes per spec §1.2.7 / D058. " +
+        'REQUIRED. The target record can be any prior record (yours or another agent\'s).'),
+    importance: Importance.describe('Felt importance for future-self recall ranking. ' +
+        "'critical' (decisions that shape future recall, identity claims), " +
+        "'high' (worth surfacing in default recall), " +
+        "'medium' (general signal), " +
+        "'low' (background noting), " +
+        "'noise' (deliberately deprioritized for recall)."),
+    summary: z.string().min(1).max(2048).describe('One-line semantic gist of the annotation. The recall pipeline reads this verbatim ' +
+        'for snippet display; keep it under ~120 chars when possible. ' +
+        'Distinct from the annotated record\'s own content, this summary captures what ' +
+        'future-you should know about why this record matters.'),
+    topics: z.array(z.string().min(1).max(128)).max(16).optional().describe('Optional topic tags. Used by recall\'s topics filter. ' +
+        'Lowercase-hyphenated convention (e.g. "bug-fix", "design-decision").'),
+    context_id: z.string().regex(HEX_32_PATTERN).optional().describe('32-hex context_id. Defaults to process.env.ATRIB_CONTEXT_ID per D078 when omitted; ' +
+        'falls back to a fresh genesis context_id if neither is set.'),
+    informed_by: z.array(z.string().regex(SHA256_REF_PATTERN)).optional().describe("Array of 'sha256:<64-hex>' record_hashes that informed this annotation. " +
+        'Sorted lexicographically before signing per §1.2.5. The `annotates` reference ' +
+        'is separate from `informed_by` and need not be duplicated here.'),
+});
+/**
+ * Register the legacy `atrib-annotate` tool. The handler call shape is
+ * unchanged from the standalone @atrib/annotate server (no logEndpoint or
+ * reference-resolver threading), so historical behavior is preserved
+ * exactly; only the mounting surface moved.
+ */
+export function registerAnnotateTool(mcp, deps) {
+    const localSubstrate = deps.options.localSubstrate === false
+        ? undefined
+        : (deps.options.localSubstrate ??
+            resolveEmitLocalSubstrateShadowFromEnv({
+                producer: 'atrib-annotate',
+                transport: 'stdio-mcp-server',
+            }));
+    mcp.registerTool('atrib-annotate', {
+        description: 'Mark a past record\'s importance and meaning without superseding it. ' +
+            'Produces a signed annotation event (spec §1.2.7 / D058) that adds an ' +
+            'ANNOTATES graph edge to the target. Use when you want future-self or ' +
+            'other agents to read back this past record with weighted importance and ' +
+            'a one-line gist. Legacy alias: new callers should prefer `attest` with ' +
+            'ref.kind="annotates"; records are byte-identical either way.',
+        inputSchema: AnnotateInput.shape,
+    }, async (rawInput) => {
+        const input = AnnotateInput.parse(rawInput);
+        const result = await handleEmit({
+            input: {
+                event_type: EVENT_TYPE_ANNOTATION_URI,
+                content: {
+                    annotates: input.annotates,
+                    importance: input.importance,
+                    summary: input.summary,
+                    ...(input.topics ? { topics: input.topics } : {}),
+                },
+                annotates: input.annotates,
+                ...(input.context_id ? { context_id: input.context_id } : {}),
+                ...(input.informed_by ? { informed_by: input.informed_by } : {}),
+            },
+            key: await deps.resolveServerKey(),
+            queue: deps.queue,
+            producer: 'atrib-annotate',
+            ...(localSubstrate ? { localSubstrate } : {}),
+        });
+        if (!result.signed) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: result.refusals.join('\n') }],
+            };
+        }
+        const out = {
+            signed: true,
+            record_hash: result.record_hash,
+            log_index: result.log_index,
+            inclusion_proof: result.inclusion_proof,
+            context_id: result.context_id,
+            warnings: result.warnings,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+        };
+    });
+}
+/**
+ * Wire up the legacy atrib-annotate MCP server. Mounts `atrib-annotate`
+ * plus `attest` (alias-window rule W1). The underlying signing pipeline is
+ * shared via handleEmit so annotation records are byte-identical regardless
+ * of which tool produced them.
+ */
+export async function createAtribAnnotateServer(options = {}) {
+    const deps = buildAnnotateWriteToolDeps(options);
+    const mcp = new McpServer({ name: 'atrib-annotate', version: '0.1.0' });
+    registerAnnotateTool(mcp, deps);
+    registerAttestTool(mcp, deps);
+    return {
+        mcp,
+        flush: () => deps.queue.flush(),
+    };
+}
+function buildAnnotateWriteToolDeps(options) {
+    const logEndpoint = options.logEndpoint ?? process.env['ATRIB_LOG_ENDPOINT'];
+    const queue = createSubmissionQueue(logEndpoint);
+    return {
+        resolveServerKey: createServerKeyResolver(options),
+        queue,
+        logEndpoint,
+        options,
+    };
+}
+function createServerKeyResolver(options) {
+    if (Object.prototype.hasOwnProperty.call(options, 'key')) {
+        const fixed = options.key ?? null;
+        return async () => fixed;
+    }
+    let resolved = null;
+    return async () => {
+        resolved ??= resolveKey();
+        return resolved;
+    };
+}

package/dist/attest.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+export declare const AttestRef: z.ZodObject<{
+    kind: z.ZodEnum<{
+        annotates: "annotates";
+        revises: "revises";
+    }>;
+    target: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AttestInput: z.ZodObject<{
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    ref: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            annotates: "annotates";
+            revises: "revises";
+        }>;
+        target: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    context_id: z.ZodOptional<z.ZodString>;
+    informed_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allow_unresolved_informed_by: z.ZodOptional<z.ZodBoolean>;
+    chain_root: z.ZodOptional<z.ZodString>;
+    provenance_token: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    args_hash: z.ZodOptional<z.ZodString>;
+    result_hash: z.ZodOptional<z.ZodString>;
+    producer: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AttestInputT = z.infer<typeof AttestInput>;
+/**
+ * The EmitInput-shaped object handleEmit accepts, plus the resolved
+ * event_type so callers can surface it in the attest result.
+ */
+export interface MappedAttestInput {
+    event_type: string;
+    emitInput: {
+        event_type: string;
+        content: Record<string, unknown>;
+        context_id?: string;
+        informed_by?: string[];
+        allow_unresolved_informed_by?: boolean;
+        chain_root?: string;
+        provenance_token?: string;
+        annotates?: string;
+        revises?: string;
+        tool_name?: string;
+        args_hash?: string;
+        result_hash?: string;
+    };
+}
+export interface AttestMappingRefusal {
+    refusals: string[];
+}
+/**
+ * Map an AttestInput onto the legacy EmitInput shape. Pure; no signing.
+ * Returns refusals instead of throwing so the tool surface can return the
+ * same isError shape the legacy write names use (§5.8: refuse loudly,
+ * never sign a malformed record).
+ *
+ * Content composition matches the legacy specialized writers exactly so
+ * the D099 default args_hash is byte-identical:
+ *   annotates: content := { annotates: target, ...content }
+ *   revises:   content := { revises: target, ...content, reason }
+ * A caller-supplied content.annotates / content.revises / content.reason
+ * that contradicts `ref` is a refusal, not a silent overwrite.
+ */
+export declare function mapAttestInput(input: AttestInputT): MappedAttestInput | AttestMappingRefusal;
+export declare function isAttestMappingRefusal(mapped: MappedAttestInput | AttestMappingRefusal): mapped is AttestMappingRefusal;