feat: interchange.grantRequirements for installer discovery

Static package.json + MEMORY_GRANT_REQUIREMENTS SSOT so host installers
can learn memory:add / memory:search without executing the package.

Author: TheGreatAxios

docs/DISTILLER.md

@@ -96,10 +96,19 @@ const { workflow, generatorAgentId } = createResidentDistiller({
 
 ## Grant manifest (process principal)
 
+Installer discovery (not live grants):
+
+- `package.json` → `interchange.grantRequirements`
+- typed SSOT: `MEMORY_GRANT_REQUIREMENTS` / `MEMORY_CAPABILITY_IDS` from
+  `@corbits/memory` (or `@corbits/memory/tools`)
+
+Minimum capabilities:
+
 - `memory:add` (claim or note writes)
 - `memory:search` (corroboration + feed if using backfill)
 
-Copy `accessTags` from the source onto claim writes — never mint broader tags.
+Deploy materializes these onto the workflow principal. Copy `accessTags` from
+the source onto claim writes — never mint broader tags.
 
 ## Out of scope
 

package.json

@@ -10,7 +10,21 @@
     "./distiller": "./src/distiller/index.ts"
   },
   "interchange": {
-    "tools": "./src/tools/index.ts"
+    "tools": "./src/tools/index.ts",
+    "grantRequirements": [
+      {
+        "resource": "memory",
+        "action": "add",
+        "source": "tenant",
+        "surfaces": ["tools", "distiller", "routes"]
+      },
+      {
+        "resource": "memory",
+        "action": "search",
+        "source": "tenant",
+        "surfaces": ["tools", "distiller", "routes"]
+      }
+    ]
   },
   "license": "LGPL-2.1-only",
   "type": "module",

src/distiller/workflow.ts

@@ -23,6 +23,7 @@ import { defineWorkflow, type WorkflowDefinition } from "@intx/workflow";
 import { memoryAdd } from "../tools/add.ts";
 import { memoryFeed } from "../tools/feed.ts";
 import { memorySearch } from "../tools/search.ts";
+import { MEMORY_CAPABILITY_IDS } from "../grant-requirements.ts";
 import {
   RESIDENT_DISTILLER_AGENT_ID,
   RESIDENT_DISTILLER_CRON_DEFAULT,
@@ -95,7 +96,8 @@ export function createResidentDistiller(
       "Resident memory distiller — feed → classify → claim write",
     systemPrompt: opts.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
     tools,
-    capabilities: ["memory:search", "memory:add"],
+    capabilities: [...MEMORY_CAPABILITY_IDS],
+
     inference: opts.inference,
     tags: {
       role: "resident-distiller",

src/grant-requirements.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  MEMORY_CAPABILITY_IDS,
+  MEMORY_GRANT_REQUIREMENTS,
+} from "./grant-requirements.ts";
+
+describe("MEMORY_GRANT_REQUIREMENTS", () => {
+  test("covers add + search on memory resource", () => {
+    expect(MEMORY_GRANT_REQUIREMENTS.map((r) => r.action).sort()).toEqual([
+      "add",
+      "search",
+    ]);
+    for (const r of MEMORY_GRANT_REQUIREMENTS) {
+      expect(r.resource).toBe("memory");
+      expect(r.source).toBe("tenant");
+      expect(r.surfaces).toContain("tools");
+      expect(r.surfaces).toContain("distiller");
+    }
+  });
+
+  test("capability ids are resource:action", () => {
+    expect([...MEMORY_CAPABILITY_IDS].sort()).toEqual([
+      "memory:add",
+      "memory:search",
+    ]);
+  });
+
+  test("package.json interchange.grantRequirements stays in lockstep", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(import.meta.dir, "..", "package.json"), "utf8"),
+    ) as {
+      interchange?: {
+        grantRequirements?: Array<{
+          resource: string;
+          action: string;
+          source: string;
+          surfaces: string[];
+        }>;
+      };
+    };
+    const fromPkg = pkg.interchange?.grantRequirements ?? [];
+    expect(fromPkg).toEqual(
+      MEMORY_GRANT_REQUIREMENTS.map((r) => ({
+        resource: r.resource,
+        action: r.action,
+        source: r.source,
+        surfaces: [...r.surfaces],
+      })),
+    );
+  });
+});

src/grant-requirements.ts

@@ -0,0 +1,49 @@
+/**
+ * Grant *requirements* for installers — not live grants.
+ *
+ * Mirrored under `package.json` → `interchange.grantRequirements` so a
+ * host installer can read npm metadata without executing code. The typed
+ * export is the in-repo SSOT; keep package.json in lockstep.
+ *
+ * Shape matches Interchange definition grant requirements
+ * (`resource` + `action` + `source`). Control plane materializes grants
+ * onto the workflow principal at deploy/launch.
+ */
+
+export type MemoryGrantSource = "tenant" | "creator" | "invoker";
+
+/** Package surfaces that need the requirement when installed. */
+export type MemoryGrantSurface = "tools" | "distiller" | "routes";
+
+export type MemoryGrantRequirement = {
+  readonly resource: string;
+  readonly action: string;
+  /** Recommended authority source; installer/deploy may override. */
+  readonly source: MemoryGrantSource;
+  readonly surfaces: readonly MemoryGrantSurface[];
+};
+
+/**
+ * Minimum capability grants for memory tools / routes / process helpers.
+ * Document-tag access (`memory.doc:…`, `memory.space:…`) is separate and
+ * minted per document — not package install requirements.
+ */
+export const MEMORY_GRANT_REQUIREMENTS = [
+  {
+    resource: "memory",
+    action: "add",
+    source: "tenant",
+    surfaces: ["tools", "distiller", "routes"],
+  },
+  {
+    resource: "memory",
+    action: "search",
+    source: "tenant",
+    surfaces: ["tools", "distiller", "routes"],
+  },
+] as const satisfies readonly MemoryGrantRequirement[];
+
+/** Compact `resource:action` form used on agent `capabilities` arrays. */
+export const MEMORY_CAPABILITY_IDS = MEMORY_GRANT_REQUIREMENTS.map(
+  (r) => `${r.resource}:${r.action}` as const,
+);

src/index.ts

@@ -62,6 +62,15 @@ export {
   LIST_LIMIT_MAX,
 } from "./memory.ts";
 
+// Installer discovery — grant *requirements* (not live grants)
+export {
+  MEMORY_CAPABILITY_IDS,
+  MEMORY_GRANT_REQUIREMENTS,
+  type MemoryGrantRequirement,
+  type MemoryGrantSource,
+  type MemoryGrantSurface,
+} from "./grant-requirements.ts";
+
 // Ports — pluggable storage and live sources
 export type {
   DocumentStore,

src/tools/index.ts

@@ -18,3 +18,12 @@ export {
   type MemoryToolEnv,
 } from "./client.ts";
 
+/** Re-export installer grant requirements (same as package root). */
+export {
+  MEMORY_CAPABILITY_IDS,
+  MEMORY_GRANT_REQUIREMENTS,
+  type MemoryGrantRequirement,
+  type MemoryGrantSource,
+  type MemoryGrantSurface,
+} from "../grant-requirements.ts";
+