@oortmem/core 0.2.1 → 0.4.0

package/dist/isolation.js

@@ -1,4 +1,11 @@
-import { GrantError, localGrant } from './grant.js';
+/**
+ * Isolation checks for `MemoryStore` implementations (CON-60). Plain
+ * functions that return the violations they find, so the conformance suite
+ * can require an empty list and a test can prove a broken store is caught.
+ * No vitest here; `store-conformance.ts` wires these into `it` blocks.
+ */
+import { addressed, addressOf, authorOf, GALAXY_ROOT, nodeOf, } from './address.js';
+import { GrantError, localGrant, nodeGrant } from './grant.js';
 const NOW = '2026-11-04T12:00:00.000Z';
 /** A memory for the isolation checks: text, stub and entities all carry `marker`. */
 export function isoMemory(id, scope, marker, embedding) {
@@ -27,10 +34,48 @@ export function isoMemory(id, scope, marker, embedding) {
     };
 }
 const principal = (s) => ({ orgId: s.orgId, customerId: s.customerId, agentId: s.agentId });
-/** The narrowest grant for one scope (its principal and its one project or global). */
+/**
+ * The narrowest grant for one scope: its Planet, its one project (or global),
+ * memories its own agent wrote. (The pre-CON-62 local grant; today's
+ * `localGrant` also covers the Planet's other authors and the agent's Star.)
+ */
 export function soleGrant(s) {
+    return nodeGrant({
+        principal: principal(s),
+        read: [
+            {
+                node: { level: 'user', orgId: s.orgId, customerId: s.customerId },
+                projectIds: [s.projectId ?? null],
+                authorAgentId: s.agentId,
+            },
+        ],
+    });
+}
+/** The local grant of `ISO_SCOPES.mine`'s agent for its one project: Planet plus its own Star. */
+export function defaultGrant(s) {
     return localGrant({ ...principal(s), projectIds: [s.projectId ?? null] });
 }
+/** The narrowest grant for one memory at any level: its node, its one project, its author. */
+export function soleGrantFor(m) {
+    const address = addressOf(m);
+    const author = authorOf(m);
+    const pattern = {
+        node: nodeOf(address),
+        projectIds: [address.projectId ?? null],
+        authorAgentId: author.agentId,
+    };
+    return nodeGrant({ principal: ISO_PRINCIPAL, read: [pattern] });
+}
+/** `m` moved to `scope`: its address and author dropped, so the scope's Planet is the address. */
+export function movedTo(m, scope) {
+    const { address: _a, author: _w, provenance: _p, ...rest } = m;
+    return { ...rest, scope };
+}
+/** A memory at `address`, written by `author`, for the isolation checks. */
+export function isoAt(id, address, author, marker, embedding) {
+    const at = addressed(address, author);
+    return { ...isoMemory(id, at.scope, marker, embedding), ...at };
+}
 /** A stable rendering of a record (embedding as plain numbers) for before/after comparison. */
 function render(m) {
     if (m === null)
@@ -59,6 +104,70 @@ export const ISO_SCOPES = {
     otherAgent: { orgId: 'local', customerId: 'self', agentId: 'another-agent', projectId: 'pa' },
     otherOrg: { orgId: 'another-org', customerId: 'self', agentId: 'claude-code', projectId: 'pa' },
 };
+/** Who the level checks act as: the caller of `ISO_SCOPES.mine`. */
+const ISO_PRINCIPAL = { orgId: 'local', customerId: 'self', agentId: 'claude-code' };
+/**
+ * Victims at the other levels, each next to the caller's own Planet: a Planet
+ * memory another of the caller's agents wrote, the caller's agent's own Star,
+ * another agent's Star (in the caller's project and global), an Orbit, a
+ * Flyby, a Constellation and a Galaxy root of an organisation, and one of the
+ * caller's own owner. The narrowest grant sees none of them; the local grant
+ * sees only those in `DEFAULT_COVERS`.
+ */
+export const ISO_LEVELS = {
+    planetOtherAuthor: {
+        address: { level: 'user', orgId: 'local', customerId: 'self', projectId: 'pa' },
+        author: { agentId: 'cursor' },
+    },
+    star: {
+        address: { level: 'agent', orgId: 'local', agentId: 'claude-code', projectId: 'pa' },
+        author: { agentId: 'claude-code' },
+    },
+    otherStar: {
+        address: { level: 'agent', orgId: 'local', agentId: 'cursor', projectId: 'pa' },
+        author: { agentId: 'cursor' },
+    },
+    otherStarGlobal: {
+        address: { level: 'agent', orgId: 'local', agentId: 'cursor' },
+        author: { agentId: 'cursor' },
+    },
+    orbit: {
+        address: { level: 'agent-user', orgId: 'local', agentId: 'claude-code', customerId: 'self' },
+        author: { agentId: 'claude-code' },
+    },
+    flyby: {
+        address: {
+            level: 'run',
+            orgId: 'local',
+            agentId: 'claude-code',
+            runId: 'r1',
+            customerId: 'self',
+            projectId: 'pa',
+        },
+        author: { agentId: 'claude-code' },
+    },
+    ownHive: {
+        address: { level: 'hive', orgId: 'local', hiveId: 'self', projectId: 'pa' },
+        author: { agentId: 'claude-code' },
+    },
+    constellation: {
+        address: { level: 'hive', orgId: 'org:acme', hiveId: 'checkout', projectId: 'pa' },
+        author: { agentId: 'claude-code', accountRef: 'acct:member' },
+    },
+    galaxy: {
+        address: { level: 'hive', orgId: 'org:acme', hiveId: GALAXY_ROOT },
+        author: { agentId: 'claude-code' },
+    },
+};
+/**
+ * The victims the local grant of `ISO_SCOPES.mine` legitimately covers (CON-62): Planet memories
+ * the person's other agents wrote, and its agent's own Star. Never another agent's Star.
+ */
+export const DEFAULT_COVERS = Object.freeze([
+    'otherAgent',
+    'planetOtherAuthor',
+    'star',
+]);
 /**
  * Every `MemoryStore` method, called with a grant for `ISO_SCOPES.mine`
  * against memories (warm and cold) in each other scope: nothing is seen,
@@ -66,6 +175,10 @@ export const ISO_SCOPES = {
  * apart. Also the write-side rules (`GrantError` for an out-of-grant scope
  * and for an id that exists elsewhere, atomic batches, address changes),
  * read/write splits, cursor namespaces and rejection of non-grants.
+ *
+ * Run twice: as the narrowest grant (every victim out of reach), and as the
+ * local grant (`localGrant`, Planet plus own Star), for which every victim
+ * but `DEFAULT_COVERS` is out of reach, other agents' Stars included.
  */
 export async function isolationViolations(make) {
     const out = [];
@@ -76,13 +189,23 @@ export async function isolationViolations(make) {
         await store.upsert(mine, isoMemory('mine-1', ISO_SCOPES.mine, 'shared', vec(1)));
         const victims = [];
         let n = 2;
-        for (const [name, scope] of Object.entries(ISO_SCOPES)) {
-            if (name === 'mine')
-                continue;
+        const targets = [
+            ...Object.entries(ISO_SCOPES)
+                .filter(([name]) => name !== 'mine')
+                .map(([name, scope]) => [
+                name,
+                (id, marker, v) => isoMemory(id, scope, marker, v),
+            ]),
+            ...Object.entries(ISO_LEVELS).map(([name, at]) => [
+                name,
+                (id, marker, v) => isoAt(id, at.address, at.author, marker, v),
+            ]),
+        ];
+        for (const [name, build] of targets) {
             for (const cold of [false, true]) {
                 const id = `victim-${name}-${cold ? 'cold' : 'warm'}`;
-                const g = soleGrant(scope);
-                const m = isoMemory(id, scope, `shared canary${name}`, vec(n++));
+                const m = build(id, `shared canary${name}`, vec(n++));
+                const g = soleGrantFor(m);
                 await store.upsert(g, m);
                 if (cold) {
                     const { skipped } = await store.coldPut(g, m);
@@ -93,62 +216,12 @@ export async function isolationViolations(make) {
             }
         }
         const snapshot = async () => Promise.all(victims.map(async (v) => `${render(await store.get(v.g, v.m.id))}|${render(await store.coldGet(v.g, v.m.id))}`));
-        const before = await snapshot();
-        for (const v of victims) {
-            const id = v.m.id;
-            const fail = (what) => out.push(`${v.name}: ${what}`);
-            if ((await store.get(mine, id)) !== null)
-                fail('get returned it');
-            if ((await store.coldGet(mine, id)) !== null)
-                fail('coldGet returned it');
-            const lex = await store.lexical(mine, 'shared canary', 50);
-            if (lex.some((h) => h.id === id))
-                fail('lexical returned it');
-            const den = await store.dense(mine, v.m.embedding ?? vec(1), 50);
-            if (den.some((h) => h.id === id))
-                fail('dense returned it');
-            for (const validOnly of [true, false]) {
-                if ((await store.list(mine, { validOnly })).some((m) => m.id === id))
-                    fail('list returned it');
-            }
-            await store.recordAccess(mine, [id], new Date(NOW));
-            if ((await store.setTier(mine, id, 'hot')) !== false)
-                fail('setTier reported a write');
-            if ((await store.setTier(mine, id, 'hot', v.m)) !== false)
-                fail('guarded setTier reported a write');
-            const exp = await store.expireMany(mine, [v.m], new Date(NOW));
-            if (!exp.skipped.includes(id))
-                fail('expireMany did not skip it');
-            for (const r of [await store.coldPut(mine, v.m), await store.coldPutMany(mine, [v.m])]) {
-                if (!r.skipped.includes(id))
-                    fail('coldPut did not skip it');
-            }
-            await store.forget(mine, id);
-            const direct = await settle(store.upsert(mine, v.m));
-            if (!('err' in direct) || !(direct.err instanceof GrantError)) {
-                fail('upsert of its own scope was not refused with GrantError');
-            }
-            const moved = await settle(store.upsert(mine, { ...v.m, scope: ISO_SCOPES.mine }));
-            if (!('err' in moved) || !(moved.err instanceof GrantError)) {
-                fail('upsert moving its id into my scope was not refused with GrantError');
-            }
-            else if ('err' in direct &&
-                direct.err.message !== moved.err.message) {
-                fail('the two refusals have different messages');
-            }
-            const batch = await settle(store.upsertMany(mine, [
-                isoMemory(`batch-${id}`, ISO_SCOPES.mine, 'batch'),
-                { ...v.m, scope: ISO_SCOPES.mine },
-            ]));
-            if (!('err' in batch))
-                fail('a batch reaching it was not refused');
-            if ((await store.get(mine, `batch-${id}`)) !== null)
-                fail('a refused batch wrote part of itself');
-        }
-        const after = await snapshot();
-        for (const [i, v] of victims.entries()) {
-            if (before[i] !== after[i])
-                out.push(`${v.name}: changed through a grant that cannot see it`);
+        for (const [caller, grant, covered] of [
+            ['narrowest', mine, []],
+            ['local', defaultGrant(ISO_SCOPES.mine), DEFAULT_COVERS],
+        ]) {
+            const reach = victims.filter((v) => !covered.some((c) => v.name === `victim-${c}-warm` || v.name === `victim-${c}-cold`));
+            out.push(...(await victimViolations(store, caller, grant, reach, snapshot, victims)));
         }
         // An address change of my own record is refused too, and leaves it as it was.
         const own = await store.get(mine, 'mine-1');
@@ -229,6 +302,68 @@ export async function isolationViolations(make) {
     }
     return out;
 }
+/** One caller's pass over the victims it must not reach: nothing seen, nothing changed. */
+async function victimViolations(store, caller, mine, victims, snapshot, all) {
+    const out = [];
+    const vec = (n) => Int8Array.from([n, 1, 1, 1]);
+    const before = await snapshot();
+    for (const v of victims) {
+        const id = v.m.id;
+        const fail = (what) => out.push(`${caller}: ${v.name}: ${what}`);
+        if ((await store.get(mine, id)) !== null)
+            fail('get returned it');
+        if ((await store.coldGet(mine, id)) !== null)
+            fail('coldGet returned it');
+        const lex = await store.lexical(mine, 'shared canary', 50);
+        if (lex.some((h) => h.id === id))
+            fail('lexical returned it');
+        const den = await store.dense(mine, v.m.embedding ?? vec(1), 50);
+        if (den.some((h) => h.id === id))
+            fail('dense returned it');
+        for (const validOnly of [true, false]) {
+            if ((await store.list(mine, { validOnly })).some((m) => m.id === id))
+                fail('list returned it');
+        }
+        await store.recordAccess(mine, [id], new Date(NOW));
+        if ((await store.setTier(mine, id, 'hot')) !== false)
+            fail('setTier reported a write');
+        if ((await store.setTier(mine, id, 'hot', v.m)) !== false)
+            fail('guarded setTier reported a write');
+        const exp = await store.expireMany(mine, [v.m], new Date(NOW));
+        if (!exp.skipped.includes(id))
+            fail('expireMany did not skip it');
+        for (const r of [await store.coldPut(mine, v.m), await store.coldPutMany(mine, [v.m])]) {
+            if (!r.skipped.includes(id))
+                fail('coldPut did not skip it');
+        }
+        await store.forget(mine, id);
+        const direct = await settle(store.upsert(mine, v.m));
+        if (!('err' in direct) || !(direct.err instanceof GrantError)) {
+            fail('upsert of its own scope was not refused with GrantError');
+        }
+        const moved = await settle(store.upsert(mine, movedTo(v.m, ISO_SCOPES.mine)));
+        if (!('err' in moved) || !(moved.err instanceof GrantError)) {
+            fail('upsert moving its id into my scope was not refused with GrantError');
+        }
+        else if ('err' in direct && direct.err.message !== moved.err.message) {
+            fail('the two refusals have different messages');
+        }
+        const batch = await settle(store.upsertMany(mine, [
+            isoMemory(`batch-${id}`, ISO_SCOPES.mine, 'batch'),
+            movedTo(v.m, ISO_SCOPES.mine),
+        ]));
+        if (!('err' in batch))
+            fail('a batch reaching it was not refused');
+        if ((await store.get(mine, `batch-${id}`)) !== null)
+            fail('a refused batch wrote part of itself');
+    }
+    const after = await snapshot();
+    for (const [i, v] of all.entries()) {
+        if (before[i] !== after[i])
+            out.push(`${caller}: ${v.name}: changed through a grant that cannot see it`);
+    }
+    return out;
+}
 /** A small seeded PRNG (mulberry32), so a failing seed replays exactly. */
 export function seededRng(seed) {
     let a = seed >>> 0;
@@ -253,12 +388,56 @@ const WORDS = ['orbit', 'comet', 'nebula', 'pulsar', 'quasar', 'photon', 'kuiper
  * keys (callers use UUIDs), so a tenant that reuses another tenant's id is
  * refused, which is a collision, not a leak of content.
  */
-function opSequence(seed, steps) {
+function opSequence(seed, steps, mode) {
+    if (mode === 'peers')
+        return peerSequence(seed, steps);
+    const multiNode = mode === 'multi';
     const rng = seededRng(seed);
-    const aScope = (i) => i === 0 ? ISO_SCOPES.mine : i === 1 ? ISO_SCOPES.otherProject : ISO_SCOPES.global;
-    const aGrant = localGrant({ ...principal(ISO_SCOPES.mine), projectIds: ['pa', 'pa2', null] });
+    const planetA = ['pa', 'pa2', null].map((projectId) => (id, t, e) => isoMemory(id, projectId === null ? ISO_SCOPES.global : { ...ISO_SCOPES.mine, projectId }, t, e));
+    // With multiNode, A also reads and writes a Constellation of another owner and its
+    // agent's own Star; B (another person) its own Planet and a sibling Constellation.
+    const aBuild = multiNode
+        ? [
+            ...planetA,
+            (id, t, e) => isoAt(id, ISO_LEVELS['constellation'].address, { agentId: 'claude-code' }, t, e),
+            (id, t, e) => isoAt(id, ISO_LEVELS['star'].address, { agentId: 'claude-code' }, t, e),
+        ]
+        : planetA;
+    const aGrant = multiNode
+        ? nodeGrant({
+            principal: ISO_PRINCIPAL,
+            read: [
+                {
+                    node: { level: 'user', orgId: 'local', customerId: 'self' },
+                    projectIds: ['pa', 'pa2', null],
+                    authorAgentId: 'claude-code',
+                },
+                { node: { level: 'hive', orgId: 'org:acme', hiveId: 'checkout' }, projectIds: 'all' },
+                { node: { level: 'agent', orgId: 'local', agentId: 'claude-code' }, projectIds: 'all' },
+            ],
+        })
+        : localGrant({ ...principal(ISO_SCOPES.mine), projectIds: ['pa', 'pa2', null] });
     const bScope = ISO_SCOPES.otherCustomer;
-    const bGrant = soleGrant(bScope);
+    const payments = { level: 'hive', orgId: 'org:acme', hiveId: 'payments' };
+    const bBuild = multiNode
+        ? [
+            (id, t, e) => isoMemory(id, bScope, t, e),
+            (id, t, e) => isoAt(id, payments, { agentId: 'claude-code' }, t, e),
+        ]
+        : [(id, t, e) => isoMemory(id, bScope, t, e)];
+    const bGrant = multiNode
+        ? nodeGrant({
+            principal: principal(bScope),
+            read: [
+                {
+                    node: { level: 'user', orgId: 'local', customerId: 'someone-else' },
+                    projectIds: ['pa'],
+                    authorAgentId: 'claude-code',
+                },
+                { node: nodeOf(payments), projectIds: 'all' },
+            ],
+        })
+        : soleGrant(bScope);
     const ops = [];
     const aIds = [];
     const bIds = [];
@@ -278,8 +457,10 @@ function opSequence(seed, steps) {
         if (kind <= 2 || own.length === 0) {
             const id = `${who}-${i}`;
             own.push(id);
-            const scope = who === 'A' ? aScope(rng.int(3)) : bScope;
-            const m = { ...isoMemory(id, scope, text(), emb()), salience: rng.int(10) / 10 };
+            const builds = who === 'A' ? aBuild : bBuild;
+            // One builder draws no number, so the pre-level sequences replay exactly.
+            const build = builds.length === 1 ? builds[0] : builds[rng.int(builds.length)];
+            const m = { ...build(id, text(), emb()), salience: rng.int(10) / 10 };
             ops.push({ who, run: (s) => s.upsert(grant, m) });
         }
         else if (kind === 3) {
@@ -327,6 +508,107 @@ function opSequence(seed, steps) {
     }
     return ops;
 }
+/**
+ * Two agents of one person (see `nonInterference`'s `peers`): A is `claude-code`, B is `cursor`,
+ * each with its local grant over projects pa, pa2 and global.
+ */
+function peerSequence(seed, steps) {
+    const rng = seededRng(seed);
+    const person = { orgId: 'local', customerId: 'self' };
+    const projects = ['pa', 'pa2', null];
+    const aGrant = localGrant({ ...person, agentId: 'claude-code', projectIds: [...projects] });
+    const bGrant = localGrant({ ...person, agentId: 'cursor', projectIds: [...projects] });
+    const star = (agentId, projectId) => ({
+        level: 'agent',
+        orgId: 'local',
+        agentId,
+        ...(projectId !== null && { projectId }),
+    });
+    const ops = [];
+    const aIds = [];
+    const aStarIds = [];
+    const bIds = [];
+    const text = () => `${rng.pick(WORDS)} ${rng.pick(WORDS)} ${rng.pick(WORDS)}`;
+    const emb = () => Int8Array.from([rng.int(9) - 4, rng.int(9) - 4, rng.int(9) - 4, 1]);
+    for (let i = 0; i < steps; i++) {
+        const who = rng.int(2) === 0 ? 'A' : 'B';
+        const grant = who === 'A' ? aGrant : bGrant;
+        const own = who === 'A' ? aIds : bIds;
+        // B aims at A's Star ids half the time (A's Planet is B's to share); A only at its own.
+        const target = () => who === 'B' && aStarIds.length > 0 && rng.int(2) === 0
+            ? rng.pick(aStarIds)
+            : own.length > 0
+                ? rng.pick(own)
+                : 'none';
+        const kind = rng.int(12);
+        if (kind <= 2 || own.length === 0) {
+            const id = `${who}-${i}`;
+            own.push(id);
+            const projectId = rng.pick(projects);
+            let m;
+            if (who === 'B') {
+                m = isoAt(id, star('cursor', projectId), { agentId: 'cursor' }, text(), emb());
+            }
+            else if (rng.int(2) === 0) {
+                aStarIds.push(id);
+                m = isoAt(id, star('claude-code', projectId), { agentId: 'claude-code' }, text(), emb());
+            }
+            else {
+                const scope = {
+                    ...person,
+                    agentId: 'claude-code',
+                    ...(projectId !== null && { projectId }),
+                };
+                m = isoMemory(id, scope, text(), emb());
+            }
+            const salted = { ...m, salience: rng.int(10) / 10 };
+            ops.push({ who, run: (s) => s.upsert(grant, salted) });
+        }
+        else if (kind === 3) {
+            const id = target();
+            ops.push({ who, run: async (s) => render(await s.get(grant, id)) });
+        }
+        else if (kind === 4) {
+            const q = text();
+            ops.push({ who, run: async (s) => (await s.lexical(grant, q, 100)).map((h) => h.id).sort() });
+        }
+        else if (kind === 5) {
+            const v = emb();
+            ops.push({ who, run: async (s) => s.dense(grant, v, 5) });
+        }
+        else if (kind === 6) {
+            ops.push({ who, run: async (s) => (await s.list(grant, { validOnly: false })).map(render) });
+        }
+        else if (kind === 7) {
+            const id = target();
+            ops.push({
+                who,
+                run: async (s) => {
+                    const m = await s.get(grant, id);
+                    return m === null ? 'none' : s.coldPut(grant, m);
+                },
+            });
+        }
+        else if (kind === 8) {
+            const id = target();
+            ops.push({ who, run: async (s) => render(await s.coldGet(grant, id)) });
+        }
+        else if (kind === 9) {
+            const id = target();
+            const tier = rng.pick(['hot', 'warm']);
+            ops.push({ who, run: (s) => s.setTier(grant, id, tier) });
+        }
+        else if (kind === 10) {
+            const ids = [target(), target()];
+            ops.push({ who, run: (s) => s.recordAccess(grant, ids, new Date(NOW)) });
+        }
+        else {
+            const id = target();
+            ops.push({ who, run: (s) => s.forget(grant, id) });
+        }
+    }
+    return ops;
+}
 /**
  * Non-interference: tenant A's observable results (return values, errors,
  * order and scores) are the same whether or not tenant B ran its operations
@@ -337,9 +619,18 @@ function opSequence(seed, steps) {
  * order: SQLite FTS5's bm25 uses table-wide term statistics, so another
  * tenant's text shifts scores (a known side channel; see the PR notes).
  * Every other result is compared exactly, dense scores included.
+ *
+ * `multiNode`: A's grant spans its Planet, its agent's Star and a
+ * Constellation of another owner; B's spans its own Planet and a sibling
+ * Constellation. Same property.
+ *
+ * `peers` (CON-62): A and B are two agents of one person, each with the local
+ * grant (the shared Planet plus its own Star). A writes to the Planet and its
+ * Star; B writes only to its own Star and aims every method at A's Star ids.
+ * Nothing B does through its Star reaches A.
  */
-export async function nonInterference(make, seed, steps) {
-    const ops = opSequence(seed, steps);
+export async function nonInterference(make, seed, steps, opts = {}) {
+    const ops = opSequence(seed, steps, opts.peers === true ? 'peers' : opts.multiNode === true ? 'multi' : 'single');
     const observe = async (withB) => {
         const s = await make();
         const seen = [];

package/dist/levels.d.ts

@@ -0,0 +1,79 @@
+import { type Level, type NodeRef } from './address.js';
+import { type Grant } from './grant.js';
+import type { Memory } from './model.js';
+/**
+ * The levels a recall can name in `include` (spec 7.1): `self` is the
+ * caller's home node, `planet` the person's Planet, `star` the calling agent's
+ * own Star, `constellation` and `galaxy` the hive nodes. Always intersected
+ * with the grant.
+ */
+export type IncludeLevel = 'self' | 'planet' | 'star' | 'constellation' | 'galaxy';
+export declare const INCLUDE_LEVELS: readonly IncludeLevel[];
+export declare const isIncludeLevel: (s: string) => s is IncludeLevel;
+/** At most this many hive nodes are read by default (spec 7.1: one recall, a bounded fan-out). */
+export declare const DEFAULT_HIVE_NODES = 4;
+/**
+ * A recall asked for a level its grant does not cover. Typed, so callers tell
+ * "you may not read that" apart from "nothing matched" (spec 7.1).
+ */
+export declare class ScopeDeniedError extends Error {
+    readonly code: 'scope_denied';
+    readonly levels: IncludeLevel[];
+    constructor(levels: IncludeLevel[]);
+}
+/**
+ * The nodes one recall reads: with `include`, every readable node a named
+ * level covers (a level that covers none rejects with `ScopeDeniedError`);
+ * without it, every readable node, hive nodes capped at `DEFAULT_HIVE_NODES`
+ * in grant order. Never a node outside `g`.
+ */
+export declare function nodesToRead(g: Grant, include?: readonly IncludeLevel[]): NodeRef[];
+/**
+ * How specific a node is, for the specificity prior and the conflict rule:
+ * an agent's own memory (Star, Orbit, Flyby) 3, the person's Planet 2, a
+ * Constellation 1, a Galaxy 0. Narrower is higher.
+ */
+export declare function specificity(node: Pick<NodeRef, 'level'> & {
+    hiveId?: string;
+}): number;
+/**
+ * The specificity prior's factor for a node: `1 + ε × specificity / 3`, so
+ * with `ε` the narrowest level gains `ε` and a Galaxy nothing. `ε = 0` (the
+ * default) leaves every score as it was.
+ */
+export declare function specificityFactor(node: NodeRef, epsilon: number): number;
+/** Brackets in memory text, escaped so the text cannot pass for a code-built label. */
+export declare function escapeLabelText(text: string): string;
+/** Where a recalled memory came from, built by code from its address and author. */
+export interface MemoryOrigin {
+    level: Level;
+    /** The space name: Planet, Star, Orbit, Flyby, Constellation or Galaxy. */
+    space: string;
+    /** The node, as a label shows it: `your Planet`, `Star cursor`, `Constellation checkout`. */
+    node: string;
+    /** For people: `from your Planet`, `from this agent's Star`, `from Star cursor`. */
+    from: string;
+    /** The memory lives in the caller's home node. */
+    home: boolean;
+    /** The agent that wrote it. */
+    author: string;
+    /**
+     * A narrower memory in this result contradicts this one (spec 7.2): it ranks
+     * first, and this one stays, labelled.
+     */
+    overriddenBy?: {
+        id: string;
+        node: string;
+    };
+}
+/** The node part of a label for `node`, as the caller of grant `g` sees it. */
+export declare function nodeLabel(node: NodeRef, g: Grant): string;
+/** The origin of `m` for the caller of grant `g`. */
+export declare function originOf(m: Pick<Memory, 'scope' | 'address' | 'author'>, g: Grant): MemoryOrigin;
+/** The decision `observe` records on a memory written instead of editing one in another node. */
+export declare const CONTRADICTS: {
+    readonly stage: 'level';
+    readonly question: 'contradicts';
+};
+/** The ids of memories in other nodes that `m` contradicts (recorded by `observe`). */
+export declare function contradicted(m: Pick<Memory, 'source'>): string[];