@atrib/recall 0.14.6 → 1.0.0

package/README.md

@@ -2,7 +2,41 @@
 
 MCP server for atrib's verifiable action layer. Lets agents query their own provable past from the local signed-record mirror with per-record signature verification.
 
-The consumer-side counterpart to `@atrib/emit`: emit produces signed records, recall reads them back and exposes them to the agent through eight MCP tools. Each returned record carries a `signature_verified` boolean so a poorly-written agent treats tampered records as such.
+The consumer-side counterpart to `@atrib/attest`: attest produces signed records, recall reads them back and exposes them to the agent. Each returned record carries a `signature_verified` boolean so a poorly-written agent treats tampered records as such.
+
+## The `recall` verb and the absorb (attest/recall rename, [D164](../../DECISIONS.md#d164-attestrecall-verb-rename-and-primitive-surface-collapse))
+
+`@atrib/recall` now exposes a `recall` tool that absorbs the eight legacy
+`recall_*` tools under a `shape` argument, absorbs `trace`/`trace_forward`
+as `shape: "walk"` with a `direction`, and absorbs `atrib-verify` as a
+`verification` parameter. Results are JSON-identical to the legacy tools:
+this is the read-equivalence conformance family in
+[`spec/conformance/attest-recall/`](../../spec/conformance/attest-recall/).
+
+| `shape` | Legacy tool | Notes |
+| --- | --- | --- |
+| `history` | `recall_my_attribution_history` | base filter-rank-page query |
+| `walk` | `recall_walk` | when `direction` omitted or `"backward"`; also absorbs `trace` |
+| `walk` + `direction: "forward"` | `trace_forward` | forward walk over the same graph |
+| `content` | `recall_by_content` | BM25 free-form retrieval |
+| `chain` | `recall_session_chain` | ordered chronological session walk |
+| `annotations` | `recall_annotations` | aggregated annotation summary for a target |
+| `revisions` | `recall_revisions` | forward revision chain for a target |
+| `orphans` | `recall_orphans` | records not cited by any other record |
+| `by_signer` | `recall_by_signer` | per-creator aggregation |
+
+The `verification` parameter absorbs `atrib-verify`: pass the same
+`packet`/`records`/`claims` evidence shapes as `@atrib/verify` and the
+`recall` result carries a verification block instead of a separate tool
+call. `@atrib/verify` (the verifier library) is an OPTIONAL peer
+dependency, lazily imported. When it is absent, `verification` returns a
+typed `{ status: "verifier_unavailable" }` block and the read still
+succeeds; the degradation is explicit and typed, not a silent drop.
+
+`createAtribRecallServer` now mounts the full twelve-tool read union:
+`recall` plus the eight `recall_*` tools plus `trace`, `trace_forward`,
+and `atrib-verify`. All twelve tool names stay mounted as permanent
+aliases during the alias window.
 
 ## Install
 
@@ -14,7 +48,9 @@ Verify a local build with `pnpm --filter @atrib/recall test`.
 
 ## Tool surface
 
-Eight MCP tools cover the cognitive surface of the local mirror.
+The eight legacy `recall_*` tools below cover the cognitive surface of the
+local mirror. They stay mounted as permanent aliases; see the absorb
+section above for the `recall` verb that unifies them under one tool.
 
 ### `recall_my_attribution_history`
 
@@ -187,8 +223,8 @@ Or run via `npx`:
 ## What this does NOT do
 
 - **No log-inclusion verification.** Local signature verification ≠ log commitment proof. Use the log API for inclusion proofs.
-- **No graph derivation.** Returns records, not the [§3.2.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#324-edge-derivation-rules) graph. For declared-relationship walks, use `@atrib/trace`; for graph projections, query graph-node directly.
-- **No write surface.** Read-only. Use `@atrib/emit` to sign new records.
+- **No graph derivation.** Returns records, not the [§3.2.4](https://github.com/creatornader/atrib/blob/main/atrib-spec.md#324-edge-derivation-rules) graph. For declared-relationship walks, use `recall` with `shape: "walk"` (the legacy `trace`/`trace_forward` tool names still work); for graph projections, query graph-node directly.
+- **No write surface.** Read-only. Use `@atrib/attest` to sign new records.
 
 ## Part of atrib
 

package/dist/event-type-filter.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const EventTypeFilterSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    tool_call: "tool_call";
+    transaction: "transaction";
+    observation: "observation";
+    directory_anchor: "directory_anchor";
+    annotation: "annotation";
+    revision: "revision";
+}>, z.ZodString]>;

package/dist/event-type-filter.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+// Leaf module: the event_type filter schema shared by index.ts and
+// recall-verb.ts. Lives outside index.ts so the recall-verb module can
+// evaluate its own top-level zod schemas during the index <-> recall-verb
+// import cycle (function-level cycles are safe; const usage at module
+// init is not).
+import { z } from 'zod';
+import { EVENT_TYPE_SHORT_NAMES, isValidEventTypeUri } from '@atrib/mcp';
+export const EventTypeFilterSchema = z.union([
+    z.enum(EVENT_TYPE_SHORT_NAMES),
+    z.string().refine((value) => isValidEventTypeUri(value), {
+        message: 'event_type must be an atrib shorthand alias or a syntactically valid absolute URI',
+    }),
+]);
+//# sourceMappingURL=event-type-filter.js.map

package/dist/event-type-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-type-filter.js","sourceRoot":"","sources":["../src/event-type-filter.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC,mEAAmE;AACnE,uEAAuE;AACvE,0EAA0E;AAC1E,sEAAsE;AACtE,gBAAgB;AAEhB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAExE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC;IAC3C,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC;IAC9B,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE;QACvD,OAAO,EAAE,mFAAmF;KAC7F,CAAC;CACH,CAAC,CAAA"}

package/dist/index.d.ts

@@ -32,6 +32,8 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AtribRecord, EventTypeShortName } from '@atrib/mcp';
+import { EventTypeFilterSchema } from './event-type-filter.js';
+export { EventTypeFilterSchema };
 export type ImportanceLabel = 'critical' | 'high' | 'medium' | 'low' | 'noise';
 export declare const IMPORTANCE_NUMERIC: Record<ImportanceLabel, number>;
 export declare const ATRIB_RECALL_ALPHA: number;
@@ -41,6 +43,8 @@ export declare const ATRIB_RECALL_TAU_DAYS: number;
 export declare const ATRIB_RECALL_NOISE_FLOOR: number;
 export declare const ATRIB_RECALL_CONTENT_MAX_RECORDS: number;
 import type { AnnotationSummary as AggAnnotationSummary } from './aggregations.js';
+import { extractRecordHashFieldsFromMcpResult } from './trace-tools.js';
+import type { EdgeType } from './graph.js';
 export declare function getAtribRecallRuntimeContract(): Record<string, unknown>;
 export declare function clearRecallMirrorCache(): void;
 export declare function loadRecords(path: string): AtribRecord[];
@@ -61,7 +65,7 @@ export declare function loadRecordsFromDir(dir: string): {
     files: string[];
 };
 type ContextScope = 'all' | 'env';
-interface RecallArgs {
+export interface RecallArgs {
     context_id?: string;
     /**
      * Controls whether omitted context_id means cross-context recall or the
@@ -324,6 +328,59 @@ export declare function recall(args: RecallArgs, recordFile?: string): Promise<R
 export interface AtribRecallServer {
     mcp: McpServer;
 }
+/** Args for the local derived-graph walk (legacy recall_walk). */
+export interface RecallWalkArgs {
+    from_record_hash: string;
+    edge_types?: EdgeType[] | undefined;
+    depth?: number | undefined;
+}
+export declare function runRecallWalk(args: RecallWalkArgs): Promise<Record<string, unknown>>;
+export declare function runRecallAnnotations(args: {
+    record_hash: string;
+}): Promise<Record<string, unknown>>;
+export declare function runRecallRevisions(args: {
+    record_hash: string;
+}): Promise<Record<string, unknown>>;
+/** Args for BM25 content retrieval (legacy recall_by_content). */
+export interface RecallByContentArgs {
+    query: string;
+    k?: number | undefined;
+    max_records?: number | undefined;
+    evidence_mode?: 'bounded' | 'require_complete' | undefined;
+    include_tool_call_args?: boolean | undefined;
+}
+export declare function runRecallByContent(args: RecallByContentArgs): Promise<Record<string, unknown>>;
+/** Args for the chronological session chain (legacy recall_session_chain). */
+export interface RecallSessionChainArgs {
+    context_id?: string | undefined;
+    limit?: number | undefined;
+    include_content?: boolean | undefined;
+}
+export declare function runRecallSessionChain(args: RecallSessionChainArgs): Promise<Record<string, unknown>>;
+/** Args for loose-end discovery (legacy recall_orphans). */
+export interface RecallOrphansArgs {
+    context_id?: string | undefined;
+    event_type?: string | undefined;
+    creator_key?: string | undefined;
+    limit?: number | undefined;
+}
+export declare function runRecallOrphans(args: RecallOrphansArgs): Promise<Record<string, unknown>>;
+export declare function runRecallBySigner(args: {
+    min_records?: number | undefined;
+}): Promise<Record<string, unknown>>;
 export declare function registerAtribRecallTools(server: McpServer): void;
+export { compactVisited, createAtribTraceServer, registerTraceTools, runTraceWalk, summarizeSidecar, TraceInput, } from './trace-tools.js';
+export { extractRecordHashFieldsFromMcpResult };
+export type { AtribTraceServer, TraceInputT } from './trace-tools.js';
+export { createAtribVerifyServer, handleAtribVerify, loadVerifyModule, registerVerifyTool, tryHandleAtribVerify, VerifyInput, } from './verification.js';
+export type { AtribVerifyInput, AtribVerifyOutput, AtribVerifyServer, RecallVerificationBlock, } from './verification.js';
+export { registerRecallVerbTool, RecallVerbInput, RECALL_SHAPES, runRecallVerb } from './recall-verb.js';
+export type { RecallShape, RecallVerbInputT } from './recall-verb.js';
+/**
+ * Register the full read union on one server: the `recall` verb plus every
+ * legacy read tool name it absorbs (8 recall_* tools, trace, trace_forward,
+ * atrib-verify). This is what the `atrib-recall` binary serves and what the
+ * primitive runtime / daemon mount for reads (alias-window rule W1).
+ */
+export declare function registerAtribReadTools(server: McpServer): void;
 export declare function createAtribRecallServer(): AtribRecallServer;
-export {};