@oortmem/core 0.2.1 → 0.4.0

package/dist/grant.js

@@ -1,40 +1,156 @@
+import { addressOf, assertNode, authorOf, nodeKey, nodeOf, planetOf, sameAddress, sameAuthor, } from './address.js';
+/**
+ * The agent id of a caller that named no agent (an MCP entry written before agents existed, a
+ * terminal without `--agent`). It reads and writes the person's Planet only: it has no Star, so
+ * it can neither see nor create one. No configured agent may use this id.
+ */
+export const ANONYMOUS_AGENT = 'anonymous';
 /**
  * The permission every `MemoryStore` method takes. Opaque: built only by
- * `localGrant` or `principalGrant`, frozen, and nominal, so a raw
+ * `localGrant`, `principalGrant` or `nodeGrant`, frozen, and nominal, so a raw
  * `ScopeFilter` (or any look-alike object) is rejected by the type checker
  * and, for JavaScript callers, by `assertGrant` inside every store.
  *
- * `read` bounds what can be seen (`get`, `lexical`, `dense`, `list`,
- * `coldGet`, `recordAccess`); `write` bounds what can change (`upsert`,
- * `forget`, `setTier`, `expireMany`, `coldPut`). Cursors belong to the
- * principal. Anything outside a grant behaves exactly like something that
+ * `readNodes` bounds what can be seen (`get`, `lexical`, `dense`, `list`,
+ * `coldGet`, `recordAccess`); `writeNodes` bounds what can change (`upsert`,
+ * `forget`, `setTier`, `expireMany`, `coldPut`). A memory is covered when
+ * any pattern of the side covers its address and author. Cursors belong to
+ * the principal. Anything outside a grant behaves exactly like something that
  * does not exist.
  */
 export class Grant {
     #issued = true;
     principal;
+    /** @deprecated The pre-level view of `readNodes`; see `GrantFilter`. */
     read;
+    /** @deprecated The pre-level view of `writeNodes`; see `GrantFilter`. */
     write;
-    constructor(principal, read, write) {
+    readNodes;
+    writeNodes;
+    /**
+     * The node new memories are written to (the home node): the principal's
+     * Planet unless the agent keeps a Star. Engine code that creates a memory
+     * (observe, remember) addresses it here; edits of existing memories keep
+     * their own address. Covered by `writeNodes` whenever they are not empty.
+     */
+    home;
+    constructor(principal, readNodes, writeNodes, home) {
         this.principal = Object.freeze({ ...principal });
-        this.read = Object.freeze({ ...principal, projectIds: freezeProjects(read) });
-        this.write = Object.freeze({ ...principal, projectIds: freezeProjects(write) });
+        this.readNodes = Object.freeze(readNodes.map(freezePattern));
+        this.writeNodes = Object.freeze(writeNodes.map(freezePattern));
+        this.home = Object.freeze(homeNode(principal, this.writeNodes, home));
+        this.read = Object.freeze({
+            ...principal,
+            projectIds: legacyProjects(principal, this.readNodes),
+        });
+        this.write = Object.freeze({
+            ...principal,
+            projectIds: legacyProjects(principal, this.writeNodes),
+        });
         Object.freeze(this);
     }
     /** @internal Use `localGrant` or `principalGrant`. */
-    static issue(principal, read, write) {
-        for (const k of ['orgId', 'customerId', 'agentId']) {
-            if (typeof principal[k] !== 'string' || principal[k] === '') {
-                throw new RangeError(`grant: ${k} must be a non-empty string`);
-            }
-        }
-        return new Grant(principal, read, write);
+    static issue(principal, read, write, home = 'planet') {
+        checkPrincipal(principal);
+        const anonymous = principal.agentId === ANONYMOUS_AGENT;
+        if (anonymous && home === 'star')
+            throw new RangeError('grant: an anonymous agent has no Star');
+        const readSide = anonymous
+            ? [ownPlanet(principal, read)]
+            : [ownPlanet(principal, read), ownStar(principal, read)];
+        // An agent whose home is its Star may read the shared Planet but never change it: its writes
+        // (new memories, forget, pin, tiers, confirmations) stay in its Star.
+        const writeSide = home === 'star'
+            ? [ownStar(principal, write)]
+            : anonymous
+                ? [ownPlanet(principal, write)]
+                : [ownPlanet(principal, write), ownStar(principal, write)];
+        return new Grant(principal, readSide, writeSide, home === 'star' ? starNode(principal) : planetNode(principal));
+    }
+    /** @internal Use `nodeGrant` or `narrowGrant`. */
+    static issueNodes(principal, read, write, home) {
+        checkPrincipal(principal);
+        return new Grant(principal, read, write, home);
     }
     /** True for a real grant (not a copy, not a look-alike). */
     static is(x) {
         return typeof x === 'object' && x !== null && #issued in x;
     }
 }
+function checkPrincipal(principal) {
+    for (const k of ['orgId', 'customerId', 'agentId']) {
+        if (typeof principal[k] !== 'string' || principal[k] === '') {
+            throw new RangeError(`grant: ${k} must be a non-empty string`);
+        }
+    }
+}
+/**
+ * The local grant side's Planet: the principal's own Planet, whichever of the
+ * person's agents wrote the memory (CON-62; before it, the pattern was
+ * restricted to the principal's own agent).
+ */
+function ownPlanet(p, projectIds) {
+    return { node: planetNode(p), projectIds };
+}
+/** The principal's agent's own Star: private to that agent, never another's. */
+function ownStar(p, projectIds) {
+    return { node: starNode(p), projectIds };
+}
+/** The Star of a principal's agent (owned by the principal's owner). */
+export function starNode(p) {
+    return { level: 'agent', orgId: p.orgId, agentId: p.agentId };
+}
+/**
+ * `home` checked against the write side, or the default: the principal's
+ * Planet when the write side names it, else the first node written, else the
+ * Planet (a read-only grant writes nothing anyway).
+ */
+function homeNode(p, write, home) {
+    if (home !== undefined) {
+        assertNode(home);
+        const { level: _l, ...rest } = home;
+        const node = { level: home.level, ...rest };
+        if (write.length > 0 && !write.some((w) => nodeKey(w.node) === nodeKey(node))) {
+            throw new RangeError('grant: home must be a node the grant writes');
+        }
+        return node;
+    }
+    const planet = planetNode(p);
+    if (write.length === 0 || write.some((w) => nodeKey(w.node) === nodeKey(planet)))
+        return planet;
+    return write[0].node;
+}
+function freezePattern(p) {
+    if (typeof p !== 'object' || p === null)
+        throw new TypeError('grant: a node pattern must be an object');
+    assertNode(p.node);
+    const { level: _l, ...rest } = p.node;
+    const node = Object.freeze({ level: p.node.level, ...rest });
+    if (p.authorAgentId !== undefined &&
+        (typeof p.authorAgentId !== 'string' || p.authorAgentId === '')) {
+        throw new RangeError('grant: authorAgentId must be a non-empty string');
+    }
+    return Object.freeze({
+        node,
+        projectIds: freezeProjects(p.projectIds),
+        ...(p.authorAgentId !== undefined && { authorAgentId: p.authorAgentId }),
+    });
+}
+/**
+ * The projects of `patterns` that a pre-level reader may assume: those of
+ * patterns naming exactly the principal's Planet and covering its agent's
+ * writing (no author restriction, or that agent). Never wider than the
+ * patterns themselves.
+ */
+function legacyProjects(p, patterns) {
+    const own = nodeKey({ level: 'user', orgId: p.orgId, customerId: p.customerId });
+    const mine = patterns.filter((x) => (x.authorAgentId === undefined || x.authorAgentId === p.agentId) && nodeKey(x.node) === own);
+    if (mine.some((x) => x.projectIds === 'all'))
+        return 'all';
+    return Object.freeze([
+        ...new Set(mine.flatMap((x) => x.projectIds)),
+    ]);
+}
 function freezeProjects(p) {
     if (p === 'all')
         return 'all';
@@ -51,9 +167,17 @@ function samePrincipal(a, b) {
     return a.orgId === b.orgId && a.customerId === b.customerId && a.agentId === b.agentId;
 }
 /**
- * The grant for today's single-principal callers: read exactly what `read`
- * names (a one-node grant), and write the same unless `opts.write` narrows it.
- * `write` must name the same principal as `read`.
+ * The grant for one agent of one person (CON-62): read and write the
+ * person's Planet (memories any of their agents wrote) and this agent's own
+ * Star, in the projects `read` names; `opts.write` may narrow the write side.
+ * Another agent's Star is never covered. `opts.home` picks where new memories
+ * land: the Planet (default) or the agent's Star; with `star` the Planet is
+ * read-only (the agent writes only its Star). `ANONYMOUS_AGENT` gets the
+ * Planet alone. `write` must name the same principal as `read`.
+ *
+ * Before CON-62 the Planet side was restricted to memories the principal's
+ * own agent wrote. Every local memory so far was written as `claude-code`,
+ * so a local store sees exactly what it saw; nothing is rewritten.
  */
 export function localGrant(read, opts = {}) {
     const write = opts.write ?? read;
@@ -64,27 +188,110 @@ export function localGrant(read, opts = {}) {
     if (!samePrincipal(read, write)) {
         throw new RangeError('localGrant: read and write must name the same org, customer and agent');
     }
-    return Grant.issue(read, read.projectIds, write.projectIds);
+    return Grant.issue({ orgId: read.orgId, customerId: read.customerId, agentId: read.agentId }, read.projectIds, write.projectIds, opts.home);
+}
+/**
+ * Every project of `p` (and its global memories), for read and write:
+ * maintenance such as export. Covers the same nodes as `localGrant`: the
+ * person's Planet and this agent's own Star.
+ */
+export function principalGrant(p, opts = {}) {
+    return Grant.issue({ orgId: p.orgId, customerId: p.customerId, agentId: p.agentId }, 'all', 'all', opts.home);
+}
+/**
+ * A grant over explicit node patterns, possibly across owners and levels:
+ * `read` bounds what is seen, `write` (default: `read`) what may change.
+ * Trusted: whoever builds one has already decided the principal may use
+ * every node it names (local configuration, or membership checked by a
+ * control plane). Nothing in the engine builds one for its own callers yet:
+ * the CLI, hooks and MCP server keep the pre-level grants.
+ */
+export function nodeGrant(opts) {
+    if (!Array.isArray(opts.read) || (opts.write !== undefined && !Array.isArray(opts.write))) {
+        throw new TypeError('nodeGrant: read and write must be arrays of node patterns');
+    }
+    return Grant.issueNodes(opts.principal, opts.read, opts.write ?? opts.read, opts.home);
+}
+/**
+ * `g` narrowed to the nodes `keep` names (by `nodeKey`), on both sides: the
+ * grant recall uses for one node's first stage. Never wider than `g`. The
+ * home stays when it is kept, else the default for what remains.
+ */
+export function narrowGrant(g, keep) {
+    assertGrant(g);
+    const keys = new Set(keep.map((n) => nodeKey(n)));
+    const read = g.readNodes.filter((p) => keys.has(nodeKey(p.node)));
+    const write = g.writeNodes.filter((p) => keys.has(nodeKey(p.node)));
+    const home = write.some((p) => nodeKey(p.node) === nodeKey(g.home)) ? g.home : undefined;
+    return Grant.issueNodes(g.principal, read, write, home);
+}
+/** The distinct nodes `g` reads, in the order its patterns name them. */
+export function readableNodes(g) {
+    assertGrant(g);
+    const seen = new Map();
+    for (const p of g.readNodes)
+        if (!seen.has(nodeKey(p.node)))
+            seen.set(nodeKey(p.node), p.node);
+    return [...seen.values()];
 }
-/** Every project of `p` (and its global memories), for read and write: maintenance such as export. */
-export function principalGrant(p) {
-    return Grant.issue(p, 'all', 'all');
+/** The address a new memory gets under `g`: its home node, bound to `projectId` when given. */
+export function homeAddress(g, projectId) {
+    assertGrant(g);
+    return {
+        ...g.home,
+        ...(projectId !== undefined && { projectId }),
+    };
 }
 /** Rejects anything that is not a real `Grant`; every store calls it first. */
 export function assertGrant(g) {
     if (!Grant.is(g)) {
-        throw new TypeError('MemoryStore methods take a Grant (localGrant or principalGrant)');
+        throw new TypeError('MemoryStore methods take a Grant (localGrant, principalGrant or nodeGrant)');
     }
 }
-/** True iff a memory with `scope` lies inside `f`. Extra scope fields do not widen or narrow it. */
+/**
+ * True iff a memory with `scope` lies inside `f`. Extra scope fields do not widen or narrow it.
+ * @deprecated Use `grantReads` / `grantWrites`.
+ */
 export function filterCovers(f, scope) {
     return (scope.orgId === f.orgId &&
         scope.customerId === f.customerId &&
         scope.agentId === f.agentId &&
         (f.projectIds === 'all' || f.projectIds.includes(scope.projectId ?? null)));
 }
-export const canRead = (g, scope) => filterCovers(g.read, scope);
-export const canWrite = (g, scope) => filterCovers(g.write, scope);
+/** True iff `p` covers a memory at `address` written by `author`. */
+export function patternCovers(p, address, author) {
+    return (nodeKey(nodeOf(address)) === nodeKey(p.node) &&
+        (p.projectIds === 'all' || p.projectIds.includes(address.projectId ?? null)) &&
+        (p.authorAgentId === undefined || p.authorAgentId === author.agentId));
+}
+function covers(patterns, m) {
+    const address = addressOf(m);
+    const author = authorOf(m);
+    return patterns.some((p) => patternCovers(p, address, author));
+}
+/** True iff `g` may read `m` (by its address and author). */
+export const grantReads = (g, m) => covers(g.readNodes, m);
+/** True iff `g` may change `m` (by its address and author). */
+export const grantWrites = (g, m) => covers(g.writeNodes, m);
+/** True iff `g` may read a Planet memory with `scope` (`scope.agentId` as its author). */
+export const canRead = (g, scope) => grantReads(g, { scope });
+/** True iff `g` may change a Planet memory with `scope` (`scope.agentId` as its author). */
+export const canWrite = (g, scope) => grantWrites(g, { scope });
+/**
+ * Two records occupy the same place: the same address, the same author and
+ * the same scope (extra scope fields included). A write that would change any
+ * of them for an existing id is refused.
+ */
+export function sameRecordAddress(a, b) {
+    return (sameAddress(addressOf(a), addressOf(b)) &&
+        sameAuthor(authorOf(a), authorOf(b)) &&
+        sameScope(a.scope, b.scope));
+}
+/** The Planet node of a principal: what pre-level grants cover. */
+export function planetNode(p) {
+    const { projectId: _p, ...node } = planetOf({ ...p, agentId: '-' });
+    return node;
+}
 /**
  * The key a store keeps a cursor under. The local principal (the CLI's own,
  * `local`/`self`/`claude-code`) keeps the bare key, so cursors written before

package/dist/index.d.ts

@@ -1,11 +1,15 @@
-export declare const VERSION = "0.2.1";
+export declare const VERSION = "0.4.0";
 export * from './model.js';
+export * from './address.js';
+export * from './export-format.js';
 export * from './scope.js';
 export * from './config.js';
 export * from './activation.js';
 export * from './adapters.js';
 export * from './embed-cache.js';
 export * from './grant.js';
+export * from './levels.js';
+export * from './agents.js';
 export * from './fusion.js';
 export * from './memory-store.js';
 export * from './tokenize.js';
@@ -14,6 +18,7 @@ export * from './recall.js';
 export * from './relevance.js';
 export * from './observe.js';
 export * from './temporal.js';
+export { chronoLoaded, mayHaveDateCue, preloadChrono } from './date-cue.js';
 export * from './volatile.js';
 export * from './scrub.js';
 export * from './cap.js';

package/dist/index.js

@@ -1,11 +1,15 @@
-export const VERSION = '0.2.1';
+export const VERSION = '0.4.0';
 export * from './model.js';
+export * from './address.js';
+export * from './export-format.js';
 export * from './scope.js';
 export * from './config.js';
 export * from './activation.js';
 export * from './adapters.js';
 export * from './embed-cache.js';
 export * from './grant.js';
+export * from './levels.js';
+export * from './agents.js';
 export * from './fusion.js';
 export * from './memory-store.js';
 export * from './tokenize.js';
@@ -14,6 +18,7 @@ export * from './recall.js';
 export * from './relevance.js';
 export * from './observe.js';
 export * from './temporal.js';
+export { chronoLoaded, mayHaveDateCue, preloadChrono } from './date-cue.js';
 export * from './volatile.js';
 export * from './scrub.js';
 export * from './cap.js';

package/dist/isolation.d.ts

@@ -4,13 +4,26 @@
  * 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 { type Address, type Author } from './address.js';
 import type { MemoryStore } from './adapters.js';
 import { type Grant } from './grant.js';
 import type { Memory, Scope } from './model.js';
 /** A memory for the isolation checks: text, stub and entities all carry `marker`. */
 export declare function isoMemory(id: string, scope: Scope, marker: string, embedding?: Int8Array): Memory;
-/** 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 declare function soleGrant(s: Scope): Grant;
+/** The local grant of `ISO_SCOPES.mine`'s agent for its one project: Planet plus its own Star. */
+export declare function defaultGrant(s: Scope): Grant;
+/** The narrowest grant for one memory at any level: its node, its one project, its author. */
+export declare function soleGrantFor(m: Pick<Memory, 'scope' | 'address' | 'author'>): Grant;
+/** `m` moved to `scope`: its address and author dropped, so the scope's Planet is the address. */
+export declare function movedTo(m: Memory, scope: Scope): Memory;
+/** A memory at `address`, written by `author`, for the isolation checks. */
+export declare function isoAt(id: string, address: Address, author: Author, marker: string, embedding?: Int8Array): Memory;
 /** The scopes the checks use: the caller, and victims that differ from it in one coordinate each. */
 export declare const ISO_SCOPES: {
     mine: {
@@ -49,6 +62,23 @@ export declare const ISO_SCOPES: {
         projectId: string;
     };
 };
+/**
+ * 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 declare const ISO_LEVELS: Record<string, {
+    address: Address;
+    author: Author;
+}>;
+/**
+ * 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 declare const DEFAULT_COVERS: readonly string[];
 /**
  * Every `MemoryStore` method, called with a grant for `ISO_SCOPES.mine`
  * against memories (warm and cold) in each other scope: nothing is seen,
@@ -56,6 +86,10 @@ export declare 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 declare function isolationViolations(make: () => Promise<MemoryStore>): Promise<string[]>;
 /** A small seeded PRNG (mulberry32), so a failing seed replays exactly. */
@@ -73,5 +107,17 @@ export declare function seededRng(seed: number): {
  * 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 declare function nonInterference(make: () => Promise<MemoryStore>, seed: number, steps: number): Promise<string | null>;
+export declare function nonInterference(make: () => Promise<MemoryStore>, seed: number, steps: number, opts?: {
+    multiNode?: boolean;
+    peers?: boolean;
+}): Promise<string | null>;