@atrib/attest 0.2.0 → 0.3.1

package/README.md

@@ -146,6 +146,12 @@ Environment variables are unchanged from the legacy emit surface:
 table with descriptions; the values and resolution order carried over
 unchanged.
 
+Programmatic callers can set `mirrorPath` and `autochainSource` in
+`EmitInProcessOptions`. `mirrorPath` selects the write target for one call.
+`autochainSource` selects its mirror-based chain inheritance source. When only
+`mirrorPath` is set, it is also the read source. Calls that omit both options
+retain the environment and per-agent default ladder above.
+
 ## Degradation and privacy
 
 atrib failures never affect the primary call ([spec §5.8](../../atrib-spec.md#58-degradation-contract)), and for the write

package/dist/attest.js

@@ -86,9 +86,8 @@ export const AttestInput = z.object({
     tool_name: z
         .string()
         .min(1)
-        .max(64)
         .optional()
-        .describe('Optional §8.2 tool_name disclosure, unchanged from the legacy emit tool.'),
+        .describe('Optional §8.2 tool_name disclosure. The 64-character cap applies only to opaque labels; hashed and verbatim forms follow §8.2.'),
     args_hash: z
         .string()
         .regex(SHA256_REF_PATTERN)

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { type LocalSubstrateCoordinatorTransport, type LocalSubstrateDegradationPolicy, type LocalSubstrateHarnessClass, type LocalSubstrateProducer, type LocalSubstrateWalJoin, type ProofBundle, type SubmissionQueue, type TryLocalSubstrateCoordinatorResult } from '@atrib/mcp';
 import { type ResolvedKey } from './keys.js';
 import { type RecordReferenceResolver } from './reference-resolution.js';
+import { resolveMirrorWritePath } from './storage.js';
 import { type AttestInputT } from './attest.js';
 declare function keyResolveRetryMs(): number;
 export declare function requiresExplicitContextId(env?: NodeJS.ProcessEnv): boolean;
@@ -175,7 +176,7 @@ declare function createServerKeyResolver(options: CreateAtribEmitServerOptions):
 interface HandleEmitInput {
     input: z.infer<typeof EmitInput>;
     key: ResolvedKey | null;
-    queue: SubmissionQueue;
+    queue?: SubmissionQueue;
     /**
      * Producer label written to the sidecar's `_local.producer` field for
      * cross-source disambiguation in mirror queries. Defaults to
@@ -185,6 +186,13 @@ interface HandleEmitInput {
      */
     producer?: string;
     logEndpoint?: string | undefined;
+    /** Explicit write target for this call. Falls back to ATRIB_MIRROR_FILE. */
+    mirrorPath?: string | undefined;
+    /**
+     * Explicit read source for mirror-based chain inheritance. When omitted,
+     * mirrorPath wins before the legacy environment and default path ladder.
+     */
+    autochainSource?: string | undefined;
     recordReferenceResolver?: RecordReferenceResolver | undefined;
     localSubstrate?: EmitLocalSubstrateShadowOptions | undefined;
     localSubstrateCommit?: EmitLocalSubstrateCommitOptions | undefined;
@@ -193,7 +201,7 @@ interface HandleEmitInput {
  * Build, sign, submit, mirror. Refused writes return `signed: false`;
  * signed degradations stay `signed: true` and surface in `warnings`.
  */
-declare function handleEmit({ input, key, queue, producer, logEndpoint, recordReferenceResolver, localSubstrate, localSubstrateCommit, }: HandleEmitInput): Promise<EmitOutput>;
+declare function handleEmit({ input, key, queue, producer, logEndpoint, mirrorPath, autochainSource, recordReferenceResolver, localSubstrate, localSubstrateCommit, }: HandleEmitInput): Promise<EmitOutput>;
 export declare function resolveEmitLocalSubstrateShadowFromEnv(options?: ResolveEmitLocalSubstrateShadowFromEnvOptions): EmitLocalSubstrateShadowOptions | undefined;
 export declare function resolveEmitLocalSubstrateCommitFromEnv(options?: ResolveEmitLocalSubstrateCommitFromEnvOptions): EmitLocalSubstrateCommitOptions | undefined;
 export interface EmitInProcessOptions {
@@ -201,6 +209,11 @@ export interface EmitInProcessOptions {
     key?: ResolvedKey;
     /** Override the log endpoint (defaults to ATRIB_LOG_ENDPOINT or @atrib/mcp default). */
     logEndpoint?: string | undefined;
+    /**
+     * Set false for local-only producers. The record is still signed and
+     * mirrored, but this process does not create a public-log queue.
+     */
+    submit?: boolean;
     /**
      * Producer label written to the sidecar's `_local.producer` field for
      * cross-source disambiguation. Defaults to `'atrib-emit'`. Callers that
@@ -210,6 +223,17 @@ export interface EmitInProcessOptions {
      * consumers can bucket records by emitter without inspecting envelopes.
      */
     producer?: string;
+    /**
+     * Explicit mirror write target for this call. When omitted,
+     * ATRIB_MIRROR_FILE and the per-agent default remain unchanged fallbacks.
+     */
+    mirrorPath?: string | undefined;
+    /**
+     * Explicit mirror read source for chain inheritance. When omitted, an
+     * explicit mirrorPath is also the read source before the environment
+     * fallback ladder.
+     */
+    autochainSource?: string | undefined;
     /**
      * Upper bound on the post-sign queue flush, in milliseconds. Default
      * 5000ms. The submission queue itself has a 30s retry budget against an
@@ -277,6 +301,8 @@ export interface HandleAttestInput {
     /** Sidecar label; defaults to 'atrib-attest'. input.producer wins. */
     producer?: string;
     logEndpoint?: string | undefined;
+    mirrorPath?: string | undefined;
+    autochainSource?: string | undefined;
     recordReferenceResolver?: RecordReferenceResolver | undefined;
     localSubstrate?: EmitLocalSubstrateShadowOptions | undefined;
     localSubstrateCommit?: EmitLocalSubstrateCommitOptions | undefined;
@@ -301,6 +327,7 @@ export declare const __test_only__: {
     keyResolveRetryMs: typeof keyResolveRetryMs;
 };
 export { handleEmit, EmitInput };
+export { resolveMirrorWritePath };
 export type { EmitOutput };
 export { resolveKey } from './keys.js';
 export type { ResolvedKey } from './keys.js';

package/dist/index.js

@@ -17,13 +17,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { randomBytes } from 'node:crypto';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { EVENT_TYPE_ANNOTATION_URI, EVENT_TYPE_REVISION_URI, LOCAL_SUBSTRATE_DEFAULT_TIMEOUT_MS, LOCAL_SUBSTRATE_REQUEST_SCHEMA, canonicalRecord, createHttpLocalSubstrateTransport, createSubmissionQueue, genesisChainRoot, hexEncode, inheritChainContext, isValidEventTypeUri, normalizeEventType, parentRecordHashFromEnv, resolveEnvContextId, SHA256_REF_PATTERN, sha256, tryLocalSubstrateCoordinator, } from '@atrib/mcp';
 import { resolveKey } from './keys.js';
 import { filterResolvableInformedBy } from './reference-resolution.js';
 import { buildAndSignEmitRecord } from './sign.js';
-import { mirrorRecord } from './storage.js';
+import { mirrorRecord, resolveMirrorWritePath } from './storage.js';
 import { AttestInput, isAttestMappingRefusal, mapAttestInput } from './attest.js';
 import { registerAnnotateTool } from './annotate.js';
 import { registerReviseTool } from './revise.js';
@@ -33,10 +31,11 @@ import { registerReviseTool } from './revise.js';
 // rarely useful as a read source, but kept for backward compatibility),
 // then to the per-agent default. Distinct from ATRIB_MIRROR_FILE which is
 // where emit's own records are persisted.
-function readMirrorPath() {
-    return (process.env['ATRIB_AUTOCHAIN_SOURCE'] ??
-        process.env['ATRIB_MIRROR_FILE'] ??
-        join(homedir(), '.atrib', 'records', `atrib-emit-${process.env['ATRIB_AGENT'] ?? 'claude-code'}.jsonl`));
+function readMirrorPath(options = {}) {
+    return (options.autochainSource ??
+        options.mirrorPath ??
+        process.env['ATRIB_AUTOCHAIN_SOURCE'] ??
+        resolveMirrorWritePath());
 }
 const HEX_32_PATTERN = /^[0-9a-f]{32}$/;
 // 16 bytes encoded as base64url with no padding = 22 chars per spec §1.2.6.
@@ -127,10 +126,11 @@ const EmitInput = z.object({
     tool_name: z
         .string()
         .min(1)
-        .max(64)
         .optional()
         .describe('Optional §8.2 tool_name disclosure. Verbatim or transformed name (verbatim, opaque, ' +
-        'or hashed per §8.2). Lets emit-signed records carry the tool name for downstream ' +
+        'or hashed per §8.2). The 64-character cap applies only to opaque-label form; ' +
+        'the hashed form is sha256:<64 lowercase hex>, and verbatim names have no ' +
+        'protocol-wide length cap. Lets emit-signed records carry the tool name for downstream ' +
         'consumers (e.g. recall_my_attribution_history filtering by tool_name). Absence ' +
         'indicates the §8.1 default posture (no disclosure).'),
     args_hash: z
@@ -339,7 +339,7 @@ function createServerKeyResolver(options) {
  * Build, sign, submit, mirror. Refused writes return `signed: false`;
  * signed degradations stay `signed: true` and surface in `warnings`.
  */
-async function handleEmit({ input, key, queue, producer, logEndpoint, recordReferenceResolver, localSubstrate, localSubstrateCommit, }) {
+async function handleEmit({ input, key, queue, producer, logEndpoint, mirrorPath, autochainSource, recordReferenceResolver, localSubstrate, localSubstrateCommit, }) {
     const warnings = [];
     const eventType = normalizeEventType(input.event_type);
     if (!isValidEventTypeUri(eventType)) {
@@ -430,10 +430,14 @@ async function handleEmit({ input, key, queue, producer, logEndpoint, recordRefe
     // is the primary case that needs preserving; pre-fix this produced isolated
     // genesis records because atrib-emit's local resolver short-circuited on
     // caller context.
+    const autochainMirrorPath = readMirrorPath({ autochainSource, mirrorPath });
     const chain = await inheritChainContext({
         callerContextId,
         callerChainRoot: input.chain_root,
-        mirrorPath: readMirrorPath(),
+        mirrorPath: autochainMirrorPath,
+        ...((mirrorPath !== undefined || autochainSource !== undefined) && {
+            mirrorScope: 'file',
+        }),
         randomContextId,
     });
     const contextId = chain.contextId;
@@ -464,6 +468,9 @@ async function handleEmit({ input, key, queue, producer, logEndpoint, recordRefe
         allowUnresolved: input.allow_unresolved_informed_by,
         resolver: recordReferenceResolver,
         logEndpoint,
+        ...((mirrorPath !== undefined || autochainSource !== undefined) && {
+            localMirrorPaths: [resolveMirrorWritePath(mirrorPath), autochainMirrorPath],
+        }),
         warnings,
     });
     const effectiveInformedBy = validParentHash
@@ -528,7 +535,7 @@ async function handleEmit({ input, key, queue, producer, logEndpoint, recordRefe
     // Submit asynchronously; the queue handles retry + degradation per §5.8.
     // Cognitive events default to normal priority, annotations/observations
     // never need to block the agent.
-    if (!localSubstrateCommitted) {
+    if (!localSubstrateCommitted && queue) {
         queue.submit(record, 'normal');
     }
     // Best-effort mirror; mirrorRecord internally swallows errors per §5.8.
@@ -539,7 +546,7 @@ async function handleEmit({ input, key, queue, producer, logEndpoint, recordRefe
     await mirrorRecord(record, getProofFor(queue, recordHash) ?? null, {
         content: input.content,
         producer: producer ?? 'atrib-emit',
-    });
+    }, mirrorPath);
     // 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.
@@ -547,7 +554,7 @@ async function handleEmit({ input, key, queue, producer, logEndpoint, recordRefe
     if (!proof && localSubstrateCommitted) {
         warnings.push('submission delegated to local substrate coordinator; proof not available in this process');
     }
-    else if (!proof) {
+    else if (!proof && queue) {
         warnings.push('submission queued; proof not yet available (poll the log later if needed)');
     }
     if (localSubstrate?.waitForAttempt && localSubstrateShadow) {
@@ -874,6 +881,8 @@ function notifyLocalSubstrateWarning(localSubstrate, message, detail) {
  * warning, even when the record had already landed on the log.
  */
 function getProofFor(queue, recordHash) {
+    if (!queue)
+        return undefined;
     return queue.getProof(recordHash.startsWith('sha256:') ? recordHash.slice('sha256:'.length) : recordHash);
 }
 const DEFAULT_FLUSH_DEADLINE_MS = 5000;
@@ -910,13 +919,15 @@ export async function emitInProcess(rawInput, options = {}) {
     const key = options.key ?? (await resolveKey());
     const logEndpoint = options.logEndpoint ?? process.env['ATRIB_LOG_ENDPOINT'];
     const flushDeadlineMs = options.flushDeadlineMs ?? DEFAULT_FLUSH_DEADLINE_MS;
-    const queue = createSubmissionQueue(logEndpoint);
+    const queue = options.submit === false ? undefined : createSubmissionQueue(logEndpoint);
     const result = await handleEmit({
         input,
         key,
-        queue,
+        ...(queue !== undefined ? { queue } : {}),
         producer: options.producer,
         logEndpoint,
+        mirrorPath: options.mirrorPath,
+        autochainSource: options.autochainSource,
         recordReferenceResolver: options.recordReferenceResolver,
         localSubstrate: resolveLocalSubstrateOption(options.localSubstrate, {
             producer: options.producer ?? 'atrib-emit',
@@ -932,7 +943,7 @@ export async function emitInProcess(rawInput, options = {}) {
             transport: 'emit-in-process',
         }),
     });
-    if (!result.signed) {
+    if (!result.signed || queue === undefined) {
         return result;
     }
     // Drain before returning, bounded by flushDeadlineMs. The typical caller
@@ -979,6 +990,8 @@ export async function handleAttest(args) {
         queue: args.queue,
         producer: args.input.producer ?? args.producer ?? 'atrib-attest',
         logEndpoint: args.logEndpoint,
+        mirrorPath: args.mirrorPath,
+        autochainSource: args.autochainSource,
         recordReferenceResolver: args.recordReferenceResolver,
         localSubstrate: args.localSubstrate,
         localSubstrateCommit: args.localSubstrateCommit,
@@ -1025,6 +1038,7 @@ export const __test_only__ = { createServerKeyResolver, handleEmit, keyResolveRe
 //
 // Stable as of @atrib/emit@0.8.0. Breaking changes here require a major bump.
 export { handleEmit, EmitInput };
+export { resolveMirrorWritePath };
 export { resolveKey } from './keys.js';
 // Session-checkpoint emission (§1.2.10 / D139): reads the ordered record
 // hashes for a context from the local mirror per §5.9 and emits the

package/dist/reference-resolution.d.ts

@@ -4,6 +4,7 @@ interface FilterResolvableInformedByOptions {
     allowUnresolved?: boolean | undefined;
     resolver?: RecordReferenceResolver | undefined;
     logEndpoint?: string | undefined;
+    localMirrorPaths?: readonly string[] | undefined;
     warnings: string[];
 }
 export declare const defaultRecordReferenceResolver: typeof sharedDefaultRecordReferenceResolver;

package/dist/reference-resolution.js

@@ -8,7 +8,9 @@ export async function filterResolvableInformedBy(refs, options) {
         return unique;
     const kept = [];
     const resolver = options.resolver ??
-        ((recordHash) => defaultRecordReferenceResolver(recordHash, options.logEndpoint));
+        ((recordHash) => defaultRecordReferenceResolver(recordHash, options.logEndpoint, {
+            localMirrorPaths: options.localMirrorPaths,
+        }));
     for (const ref of unique) {
         const resolution = await resolver(ref);
         if (resolution === 'found') {

package/dist/storage.d.ts

@@ -18,10 +18,11 @@ export interface MirrorLine {
     /** Optional local-only sidecar; absent on legacy entries. */
     _local?: LocalSidecar;
 }
+export declare function resolveMirrorWritePath(explicitPath?: string): string;
 /**
  * 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>;
+export declare function mirrorRecord(record: AtribRecord, proof: ProofBundle | null, localSidecar?: LocalSidecar, explicitPath?: string): Promise<void>;

package/dist/storage.js

@@ -30,8 +30,9 @@ import { appendFile, mkdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 let ensuredDirs = new Set();
-function mirrorPath() {
-    return (process.env['ATRIB_MIRROR_FILE'] ??
+export function resolveMirrorWritePath(explicitPath) {
+    return (explicitPath ??
+        process.env['ATRIB_MIRROR_FILE'] ??
         join(homedir(), '.atrib', 'records', `atrib-emit-${process.env['ATRIB_AGENT'] ?? 'claude-code'}.jsonl`));
 }
 /**
@@ -40,8 +41,8 @@ function mirrorPath() {
  * no-op, per §5.8 the mirror is best-effort and never blocks the
  * agent.
  */
-export async function mirrorRecord(record, proof, localSidecar) {
-    const path = mirrorPath();
+export async function mirrorRecord(record, proof, localSidecar, explicitPath) {
+    const path = resolveMirrorWritePath(explicitPath);
     const line = { record, proof, written_at: Date.now() };
     if (localSidecar) {
         line._local = localSidecar;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atrib/attest",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "MCP server for atrib's write verb. One attest tool signs observations, annotations, and revisions; the legacy emit, atrib-annotate, and atrib-revise tool names stay mounted as aliases over the same handler.",
   "keywords": [
     "atrib",
@@ -45,7 +45,7 @@
     "@noble/hashes": "^2.2.0",
     "canonicalize": "^3.0.0",
     "zod": "^3.25.76",
-    "@atrib/mcp": "0.22.0"
+    "@atrib/mcp": "0.23.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",