@oortmem/core 0.3.0 → 0.4.0

package/dist/isolation.js

@@ -34,8 +34,25 @@ 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. */
@@ -92,8 +109,10 @@ const ISO_PRINCIPAL = { orgId: 'local', customerId: 'self', agentId: 'claude-cod
 /**
  * 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.
+ * 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: {
@@ -104,6 +123,14 @@ export const ISO_LEVELS = {
         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' },
@@ -132,6 +159,15 @@ export const ISO_LEVELS = {
         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,
@@ -139,6 +175,10 @@ export const ISO_LEVELS = {
  * 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 = [];
@@ -176,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, 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 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');
@@ -312,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;
@@ -336,7 +388,10 @@ 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, multiNode) {
+function opSequence(seed, steps, mode) {
+    if (mode === 'peers')
+        return peerSequence(seed, steps);
+    const multiNode = mode === 'multi';
     const rng = seededRng(seed);
     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
@@ -453,6 +508,107 @@ function opSequence(seed, steps, multiNode) {
     }
     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
@@ -467,9 +623,14 @@ function opSequence(seed, steps, multiNode) {
  * `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, opts = {}) {
-    const ops = opSequence(seed, steps, opts.multiNode === true);
+    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[];

package/dist/levels.js

@@ -0,0 +1,140 @@
+import { addressOf, authorOf, GALAXY_ROOT, nodeKey, nodeOf, spaceName, } from './address.js';
+import { readableNodes } from './grant.js';
+export const INCLUDE_LEVELS = Object.freeze([
+    'self',
+    'planet',
+    'star',
+    'constellation',
+    'galaxy',
+]);
+export const isIncludeLevel = (s) => INCLUDE_LEVELS.includes(s);
+/** At most this many hive nodes are read by default (spec 7.1: one recall, a bounded fan-out). */
+export 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 class ScopeDeniedError extends Error {
+    code = 'scope_denied';
+    levels;
+    constructor(levels) {
+        super(`scope_denied: this grant cannot read ${levels.join(', ')}`);
+        this.name = 'ScopeDeniedError';
+        this.levels = levels;
+    }
+}
+/** True when `node` is what `level` names for a caller whose grant is `g`. */
+function names(level, node, g) {
+    switch (level) {
+        case 'self':
+            return nodeKey(node) === nodeKey(g.home);
+        case 'planet':
+            return node.level === 'user';
+        case 'star':
+            return (node.level === 'agent' &&
+                node.orgId === g.principal.orgId &&
+                node.agentId === g.principal.agentId);
+        case 'constellation':
+            return node.level === 'hive' && node.hiveId !== GALAXY_ROOT;
+        case 'galaxy':
+            return node.level === 'hive' && node.hiveId === GALAXY_ROOT;
+    }
+}
+/**
+ * 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 function nodesToRead(g, include) {
+    const readable = readableNodes(g);
+    if (include === undefined || include.length === 0) {
+        let hives = 0;
+        return readable.filter((n) => n.level !== 'hive' || ++hives <= DEFAULT_HIVE_NODES);
+    }
+    for (const l of include) {
+        if (!isIncludeLevel(l))
+            throw new RangeError(`unknown level ${JSON.stringify(l)}`);
+    }
+    const denied = [...new Set(include)].filter((l) => !readable.some((n) => names(l, n, g)));
+    if (denied.length > 0)
+        throw new ScopeDeniedError(denied);
+    return readable.filter((n) => include.some((l) => names(l, n, g)));
+}
+/**
+ * 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 function specificity(node) {
+    switch (node.level) {
+        case 'agent':
+        case 'agent-user':
+        case 'run':
+            return 3;
+        case 'user':
+            return 2;
+        case 'hive':
+            return node.hiveId === GALAXY_ROOT ? 0 : 1;
+    }
+}
+/**
+ * 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 function specificityFactor(node, epsilon) {
+    return 1 + (epsilon * specificity(node)) / 3;
+}
+/** Brackets in memory text, escaped so the text cannot pass for a code-built label. */
+export function escapeLabelText(text) {
+    return text.replace(/[[\]]/g, (c) => `\\${c}`);
+}
+/** An id shown inside a label: control characters dropped, brackets escaped, clipped. */
+function labelId(id) {
+    // oxlint-disable-next-line no-control-regex
+    const clean = escapeLabelText(id.replace(/[\u0000-\u001f\u007f]/g, ''));
+    return clean.length > 40 ? `${clean.slice(0, 39)}…` : clean;
+}
+/** The node part of a label for `node`, as the caller of grant `g` sees it. */
+export function nodeLabel(node, g) {
+    switch (node.level) {
+        case 'user':
+            return node.orgId === g.principal.orgId && node.customerId === g.principal.customerId
+                ? 'your Planet'
+                : 'a Planet';
+        case 'agent':
+            return `Star ${labelId(node.agentId)}`;
+        case 'agent-user':
+            return `Orbit ${labelId(node.agentId)}`;
+        case 'run':
+            return `Flyby ${labelId(node.runId)}`;
+        case 'hive':
+            return node.hiveId === GALAXY_ROOT ? 'Galaxy' : `Constellation ${labelId(node.hiveId)}`;
+    }
+}
+/** The origin of `m` for the caller of grant `g`. */
+export function originOf(m, g) {
+    const node = nodeOf(addressOf(m));
+    const label = nodeLabel(node, g);
+    const ownStar = node.level === 'agent' &&
+        node.orgId === g.principal.orgId &&
+        node.agentId === g.principal.agentId;
+    return {
+        level: node.level,
+        space: spaceName(node),
+        node: label,
+        from: ownStar ? "from this agent's Star" : `from ${label}`,
+        home: nodeKey(node) === nodeKey(g.home),
+        author: authorOf(m).agentId,
+    };
+}
+/** The decision `observe` records on a memory written instead of editing one in another node. */
+export const CONTRADICTS = { stage: 'level', question: 'contradicts' };
+/** The ids of memories in other nodes that `m` contradicts (recorded by `observe`). */
+export function contradicted(m) {
+    return m.source.decisions
+        .filter((d) => d.stage === CONTRADICTS.stage && d.question === CONTRADICTS.question)
+        .map((d) => d.answer);
+}
+//# sourceMappingURL=levels.js.map

package/dist/observe.d.ts

@@ -1,5 +1,6 @@
 import type { DecisionController, Embedder, MemoryStore, MemoryWriter, Observation } from './adapters.js';
 import type { ResolvedConfig } from './config.js';
+import { type Home } from './grant.js';
 import type { Decision, Scope } from './model.js';
 export type MemoryOutcomeKind = 'skipped' | 'reinforced' | 'added' | 'updated' | 'superseded' | 'corrected';
 /** What happened to one memory the turn produced. */
@@ -29,6 +30,14 @@ export interface ObserveDeps {
     now?: Date;
     /** Recorded on `source.harness`; defaults to "unknown". */
     harness?: string;
+    /**
+     * Where new memories land (spec 5.1): the person's Planet (default) or, for an agent configured
+     * as a Star, `scope.agentId`'s own Star. Candidates come from both. A memory is only ever
+     * superseded, corrected or refined in the home node, and an agent whose home is its Star never
+     * writes the Planet at all: a Planet memory it re-observes gets an access record (activation),
+     * never a confirmation or an edit.
+     */
+    home?: Home;
 }
 /**
  * Gate-stage reinforcement match floor. When the gate says "do not store", a

package/dist/observe.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { localGrant } from './grant.js';
+import { addressed, addressOf, nodeKey, nodeOf } from './address.js';
+import { grantWrites, homeAddress, localGrant } from './grant.js';
+import { CONTRADICTS } from './levels.js';
 import { capObservation } from './cap.js';
 import { scrubObservation } from './scrub.js';
 import { checkWriterDate, factInterval, utcOffset } from './temporal.js';
@@ -125,11 +127,30 @@ async function apply(a) {
         if (target === undefined)
             return { outcome: 'skipped' };
         await store.recordAccess(grant, [target.id], now);
-        await confirm(store, grant, target.id, now.toISOString());
+        // Confirming writes the memory: only where this agent may write (a Star agent reinforces a
+        // Planet memory's activation but never edits it).
+        if (grantWrites(grant, target))
+            await confirm(store, grant, target.id, now.toISOString());
         return { outcome: 'reinforced', memoryId: target.id };
     }
     let action = best.action === 'UPDATE' ? 'REFINE' : best.action;
     let prior = action === 'ADD' ? undefined : candidates.find((c) => c.id === best.candidateId);
+    if (prior !== undefined && nodeKey(nodeOf(addressOf(prior))) !== nodeKey(grant.home)) {
+        // The prior lives in another node (the Planet, for an agent writing to its Star, or the
+        // reverse). A write never edits a memory outside its home node: the observation becomes a
+        // memory of its own there. A contradiction is recorded, so recall can rank the narrower of the
+        // two first and label the other (spec 7.2). Reinforcing it (above) stays allowed.
+        decisions.push({
+            stage: 'level',
+            question: 'other-node',
+            answer: 'add-instead',
+            probability: 1,
+        });
+        if (action === 'SUPERSEDE' || action === 'CORRECT') {
+            decisions.push({ ...CONTRADICTS, answer: prior.id, probability: best.probability });
+        }
+        prior = undefined;
+    }
     if (prior !== undefined && (prior.scope.projectId ?? null) !== (scope.projectId ?? null)) {
         // Candidates include global memories. A project's observation must not end or
         // rewrite a fact another scope (every project, for a global one) relies on, so it
@@ -235,6 +256,9 @@ async function apply(a) {
     const base = {
         id,
         scope,
+        // A memory at another level than the Planet carries its address and author.
+        ...(grant.home.level !== 'user' &&
+            addressed(homeAddress(grant, scope.projectId), { agentId: scope.agentId })),
         type: w.type,
         text: w.text,
         stub: w.stub,
@@ -418,7 +442,7 @@ export async function observe(raw, scope, deps) {
     const obs = capObservation(scrubbed.obs);
     const { store, embed, decide, write } = deps;
     const now = deps.now ?? new Date();
-    const grant = localGrant(filterFor(scope));
+    const grant = localGrant(filterFor(scope), deps.home === undefined ? {} : { home: deps.home });
     const g = await decide.gate(obs);
     const text = `${obs.userText}\n${obs.assistantText}`;
     if (g.shouldStore < GATE_THRESHOLD) {