@atrib/emit 0.4.1 → 0.4.3

package/README.md

@@ -112,7 +112,7 @@ Three files do the work:
 - `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.
+Per [§5.8](../../atrib-spec.md#58-degradation-contract) 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
 

package/dist/index.d.ts

@@ -14,21 +14,21 @@ declare const EmitInput: z.ZodObject<{
 }, "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;
+    annotates?: string | undefined;
     provenance_token?: string | undefined;
+    revises?: string | undefined;
+    context_id?: string | undefined;
+    chain_root?: 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;
+    annotates?: string | undefined;
     provenance_token?: string | undefined;
+    revises?: string | undefined;
+    context_id?: string | undefined;
+    chain_root?: string | undefined;
 }>;
 type EmitOutput = {
     record_hash: string;

package/dist/index.js

@@ -12,11 +12,23 @@
 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 { homedir } from 'node:os';
+import { join } from 'node:path';
+import { EVENT_TYPE_ANNOTATION_URI, EVENT_TYPE_REVISION_URI, canonicalRecord, createSubmissionQueue, genesisChainRoot, hexEncode, inheritChainContext, isValidEventTypeUri, sha256, } from '@atrib/mcp';
 import { resolveKey } from './keys.js';
 import { buildAndSignEmitRecord } from './sign.js';
 import { mirrorRecord } from './storage.js';
+// Read-side mirror inheritance: ATRIB_AUTOCHAIN_SOURCE points at the file
+// atrib-emit reads to inherit cross-producer chain state (typically the
+// wrapper's mirror). Falls back to ATRIB_MIRROR_FILE (where emit writes —
+// 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', `${process.env['ATRIB_AGENT'] ?? 'claude-code'}.jsonl`));
+}
 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.
@@ -151,23 +163,25 @@ async function handleEmit({ input, key, queue }) {
                 `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({
+    // Multi-producer chain composition per spec §1.2.3 / D067. Single source
+    // of truth in @atrib/mcp's inheritChainContext: caller-supplied verbatim
+    // when both fields supplied, else cascade through env-tail (cross-producer
+    // handoff) and mirror-file inheritance (filtered to the same context_id),
+    // falling back to genesis. When caller omits context_id entirely, the
+    // helper inherits BOTH context_id and chain_root from the mirror's most
+    // recent record. The cognitive-extractor hook spawning atrib-emit with
+    // ATRIB_CHAIN_TAIL_<context_id> + the agent's context_id is the primary
+    // load-bearing case; pre-fix this produced isolated genesis records
+    // because atrib-emit's local resolver short-circuited on caller context.
+    const chain = await inheritChainContext({
         callerContextId: input.context_id,
         callerChainRoot: input.chain_root,
-        genesisChainRoot,
+        mirrorPath: readMirrorPath(),
         randomContextId,
     });
     const contextId = chain.contextId;
     const chainRoot = chain.chainRoot;
-    if (chain.inheritedFrom === 'wrapper-mirror') {
+    if (chain.inheritedFrom === 'mirror-context-and-tail') {
         warnings.push(`inherited context_id from wrapper mirror: ${contextId}`);
     }
     let record;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atrib/emit",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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",
@@ -13,7 +13,7 @@
     "@noble/ed25519": "^2.3.0",
     "@noble/hashes": "^1.8.0",
     "zod": "^3.25.76",
-    "@atrib/mcp": "0.4.0"
+    "@atrib/mcp": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",

package/dist/auto-chain.d.ts

@@ -1,61 +0,0 @@
-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

@@ -1,135 +0,0 @@
-// 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 };