@oortmem/core 0.2.0 → 0.3.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) {
@@ -31,6 +38,27 @@ const principal = (s) => ({ orgId: s.orgId, customerId: s.customerId, agentId: s
 export function soleGrant(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 +87,51 @@ 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,
+ * an Orbit, a Flyby, a Constellation and a Galaxy root of an organisation, and
+ * one of the caller's own owner. A pre-level grant sees none of them.
+ */
+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' },
+    },
+    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' },
+    },
+};
 /**
  * Every `MemoryStore` method, called with a grant for `ISO_SCOPES.mine`
  * against memories (warm and cold) in each other scope: nothing is seen,
@@ -76,13 +149,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);
@@ -128,7 +211,7 @@ export async function isolationViolations(make) {
             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 }));
+            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');
             }
@@ -138,7 +221,7 @@ export async function isolationViolations(make) {
             }
             const batch = await settle(store.upsertMany(mine, [
                 isoMemory(`batch-${id}`, ISO_SCOPES.mine, 'batch'),
-                { ...v.m, scope: ISO_SCOPES.mine },
+                movedTo(v.m, ISO_SCOPES.mine),
             ]));
             if (!('err' in batch))
                 fail('a batch reaching it was not refused');
@@ -253,12 +336,53 @@ 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, multiNode) {
     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 +402,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) {
@@ -337,9 +463,13 @@ 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.
  */
-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.multiNode === true);
     const observe = async (withB) => {
         const s = await make();
         const seen = [];

package/dist/memory-store.js

@@ -1,5 +1,6 @@
 import { appendAccess } from './activation.js';
-import { assertGrant, canRead, canWrite, cursorKey, filterCovers, GrantError, sameScope, } from './grant.js';
+import { canonicalMemory } from './address.js';
+import { assertGrant, cursorKey, grantReads, grantWrites, GrantError, sameRecordAddress, } from './grant.js';
 import { isCurrent } from './model.js';
 import { tokenizeLexical as tokens } from './tokenize.js';
 function cosine(a, b) {
@@ -46,26 +47,32 @@ export function createMemoryStore(opts = {}) {
         if (m.tier !== 'cold')
             cold.delete(m.id);
     }
-    function scoped(f) {
-        return [...main.values()].filter((m) => filterCovers(f, m.scope));
+    function scoped(grant) {
+        return [...main.values()].filter((m) => grantReads(grant, m));
     }
     /** The live record if `grant` may read it; `undefined` for unknown and out-of-grant alike. */
     function readable(grant, id) {
         const m = main.get(id);
-        return m !== undefined && canRead(grant, m.scope) ? m : undefined;
+        return m !== undefined && grantReads(grant, m) ? m : undefined;
     }
     /** The live record if `grant` may change it. */
     function writable(grant, id) {
         const m = main.get(id);
-        return m !== undefined && canWrite(grant, m.scope) ? m : undefined;
+        return m !== undefined && grantWrites(grant, m) ? m : undefined;
     }
-    /** Every check `upsert` makes, before anything is written. */
-    function checkWrite(grant, m) {
-        if (!canWrite(grant, m.scope))
+    /**
+     * Every check `upsert` makes, before anything is written: a legal address
+     * that matches the scope (`RangeError` otherwise), inside `grant.write`,
+     * and the same address, author and scope as any record already under the id.
+     * Returns the record as stored.
+     */
+    function checkWrite(grant, m, existing) {
+        const c = canonicalMemory(m);
+        if (!grantWrites(grant, c))
             throw new GrantError();
-        const existing = main.get(m.id);
-        if (existing !== undefined && !sameScope(existing.scope, m.scope))
+        if (existing !== undefined && !sameRecordAddress(existing, c))
             throw new GrantError();
+        return c;
     }
     /** True while the live record still matches the snapshot a guarded write was computed from. */
     function unchanged(live, snap) {
@@ -116,8 +123,7 @@ export function createMemoryStore(opts = {}) {
             open();
             assertGrant(grant);
             const c = structuredClone(m);
-            checkWrite(grant, c);
-            put(c);
+            put(checkWrite(grant, c, main.get(c.id)));
         },
         /** Atomic trivially: checks and clones every record before writing any. */
         async upsertMany(grant, ms) {
@@ -127,15 +133,13 @@ export function createMemoryStore(opts = {}) {
             // Later entries may move an id the batch itself created: check against
             // the batch's own earlier entries as well as the store.
             const batch = new Map();
+            const checked = [];
             for (const c of cs) {
-                if (!canWrite(grant, c.scope))
-                    throw new GrantError();
-                const existing = batch.get(c.id) ?? main.get(c.id);
-                if (existing !== undefined && !sameScope(existing.scope, c.scope))
-                    throw new GrantError();
-                batch.set(c.id, c);
+                const ok = checkWrite(grant, c, batch.get(c.id) ?? main.get(c.id));
+                batch.set(c.id, ok);
+                checked.push(ok);
             }
-            for (const c of cs)
+            for (const c of checked)
                 put(c);
         },
         async get(grant, id) {
@@ -164,7 +168,7 @@ export function createMemoryStore(opts = {}) {
             if (query.size === 0)
                 return [];
             const scored = [];
-            for (const m of scoped(grant.read)) {
+            for (const m of scoped(grant)) {
                 const fields = m.tier === 'cold' ? [m.stub, ...m.entities] : [m.text, m.stub, ...m.entities];
                 const doc = new Set(tokens(fields.join(' ')));
                 let score = 0;
@@ -180,7 +184,7 @@ export function createMemoryStore(opts = {}) {
             open();
             assertGrant(grant);
             const scored = [];
-            for (const m of scoped(grant.read)) {
+            for (const m of scoped(grant)) {
                 if (m.tier === 'cold' || m.embedding === undefined)
                     continue;
                 if (m.embedding.length !== v.length) {
@@ -204,7 +208,7 @@ export function createMemoryStore(opts = {}) {
             assertGrant(grant);
             const validOnly = listOpts.validOnly ?? true;
             const now = clock();
-            return scoped(grant.read)
+            return scoped(grant)
                 .filter((m) => !validOnly || isCurrent(m, now))
                 .filter((m) => listOpts.tier === undefined || m.tier === listOpts.tier)
                 .filter((m) => listOpts.pinned !== true || m.pinned)
@@ -225,7 +229,7 @@ export function createMemoryStore(opts = {}) {
             if (readable(grant, id) === undefined)
                 return null;
             const m = cold.get(id);
-            return m === undefined || !canRead(grant, m.scope) ? null : structuredClone(m);
+            return m === undefined || !grantReads(grant, m) ? null : structuredClone(m);
         },
         async setTier(grant, id, tier, snapshot) {
             open();

package/dist/model.d.ts

@@ -1,5 +1,12 @@
+import type { Address, Author, Provenance } from './address.js';
 export type MemoryType = 'semantic' | 'episodic' | 'procedural' | 'preference';
 export type Tier = 'hot' | 'warm' | 'cold';
+/**
+ * The pre-level view of where a memory lives. For a Planet memory (every
+ * memory written before levels) it is the whole story: the Planet is
+ * (org, customer, project) and `agentId` is the author. For other levels see
+ * `scopeOf` in `address.ts`. Grants are checked against `address` and `author`.
+ */
 export interface Scope {
     orgId: string;
     customerId: string;
@@ -38,6 +45,16 @@ export interface MemorySource {
 export interface Memory {
     id: string;
     scope: Scope;
+    /**
+     * Where the memory lives. Absent: the Planet `scope` names, which is where
+     * every memory written before levels lives, so stores return it only for
+     * other levels. Read it with `addressOf(m)`.
+     */
+    address?: Address;
+    /** Who wrote it. Absent: the agent `scope.agentId` names. Read it with `authorOf(m)`. */
+    author?: Author;
+    /** Where a shared copy came from; absent (or null) on ordinary memories. */
+    provenance?: Provenance | null;
     type: MemoryType;
     text: string;
     stub: string;

package/dist/store-conformance.d.ts

@@ -1,3 +1,4 @@
+import { type Address, type Author, type NodeRef, type Provenance } from './address.js';
 import type { MemoryStore } from './adapters.js';
 import { type Grant } from './grant.js';
 import type { Memory, Scope } from './model.js';
@@ -22,3 +23,14 @@ export declare const TG: Grant;
 /** The narrowest grant that can read and write a memory at `scope`. */
 export declare function grantFor(scope: Scope): Grant;
 export declare function storeConformance(name: string, make: () => Promise<MemoryStore>): void;
+/** One memory per level (and a Planet memory by another agent), each with a distinct embedding. */
+export declare const LEVEL_CASES: {
+    name: string;
+    address: Address;
+    author: Author;
+    provenance?: Provenance;
+}[];
+/** A memory at `address` by `author` (scope filled to match). */
+export declare function memoryAt(id: string, address: Address, author: Author, overrides?: Partial<Memory>): Memory;
+/** Read and write every project of `nodes` (no author restriction). */
+export declare function nodesGrant(...nodes: NodeRef[]): Grant;