@oortmem/core 0.2.1 → 0.4.0

package/dist/date-cue.js

@@ -0,0 +1,70 @@
+const WEEKDAYS = 'monday|tuesday|wednesday|thursday|friday|saturday|sunday|mon|tues?|wed|thu|thurs?|fri|sat|sun|weekdays?|weekends?';
+const MONTHS = 'january|february|march|april|june|july|august|september|october|november|december|jan|feb|mar|apr|jun|jul|aug|sept?|oct|nov|dec';
+const CASUAL = 'today|tonight|tomorrow|tmrw?|yesterday|overmorrow|noon|midday|midnight|mornings?|afternoons?|evenings?|nights?|ago';
+/** Time units, chrono's abbreviations included ("2h", "a few mins", "this am"). */
+const UNITS = 'sec(?:ond)?s?|min(?:ute)?s?|h(?:ou)?rs?|hours?|days?|w(?:ee)?ks?|fortnights?|months?|mos?|quarters?|qtrs?|y(?:ea)?rs?|years?|decades?|[smhdwy]|a\\.?m|p\\.?m';
+const ORDINAL = '(?:(?:twenty|thirty)[\\s-]?)?(?:first|second|third|fourth|fifth|sixth|seventh|eighth|ninth|tenth|eleventh|twelfth|thirteenth|fourteenth|fifteenth|sixteenth|seventeenth|eighteenth|nineteenth|twentieth|thirtieth)|twenty|thirty';
+/**
+ * "May" the month, not the verb: chrono reads it with a day or ordinal near it, after "in",
+ * before a comma or "of", or at the end of the text.
+ */
+const MAY = `in\\s+may|may\\s+(?:until|till|to|through)\\s+may|may\\s*(?:,|\\.\\s*\\d|of\\b|$|\\d|${ORDINAL})|(?:\\d|${ORDINAL})[\\s,]*(?:[a-z]+[\\s,]+)?may`;
+const QUANTITY = 'a|an|the|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|few|several|couple|half|this|last|next|past|coming|previous|upcoming|within|in|for';
+/** Words that make a following "now" a validity bound ("from now on", "until now"). */
+const NOW_CUE = 'until|till|through|thru|expires?|expiring|ends?|since|from|starting|starts|as\\s+of|effective|beginning|begins';
+const CUES = [
+    // Day and month names, also run into digits as chrono reads them ("17may", "sept11").
+    `(?<![a-z])(?:${WEEKDAYS}|${MONTHS}|${CASUAL}|${MAY})(?![a-z])`,
+    // "a week", "3 days", "a couple of days", "half an hour", "the end of the month".
+    `\\b(?:\\d+|${QUANTITY})\\s+(?:[a-z]+\\s+){0,2}?(?:${UNITS})\\b`,
+    // Times and dates: 17:30, 1/2, 2026-11-20, 12.5.2026, and "2026 11 3".
+    '\\d\\s*[:/.?\\-]\\s*\\d',
+    '\\d[\\s,]+\\d{1,2}[\\s,]+\\d',
+    // Ranges, read as times: "6 to 8".
+    '\\d\\s+to\\s+\\d',
+    // Suffixed numbers: 5pm, 5 a, 24h, 30m, 1d, 3rd, 1990s, 5 o'clock, 5 a.m., 21 utc.
+    `\\d\\s*(?:${UNITS}|a|st|nd|rd|th|o['’]?\\s*clock|utc|gmt)\\b`,
+    // A bare number a preposition makes a time: "at 5", "from 9 to 5".
+    '\\b(?:at|by|from|until|till|through|before|after|since|on|around|about|between)\\s*\\d',
+    '\\bhalf\\s+a',
+    `\\b(?:${NOW_CUE})\\s+(?:on\\s+)?(?:right\\s+)?now\\b`,
+    // Quarters and halves: Q1, H2.
+    '\\b[qh][1-4]\\b',
+];
+const CUE = new RegExp(CUES.join('|'), 'i');
+/** A time with a zone abbreviation ("21 PST", "9 CEST"); upper case only, as zones are written. */
+const ZONED = /\d\s*[A-Z]{1,4}T\b/;
+/**
+ * Whether `text` may hold a date or time expression chrono-node would read. False means
+ * chrono reads none that the temporal functions act on (a bare "now" is the present, and
+ * only counts after a bound word such as "from" or "until"). True may be a false alarm: that
+ * only costs loading chrono.
+ */
+export function mayHaveDateCue(text) {
+    return CUE.test(text) || ZONED.test(text);
+}
+let chrono;
+/** Whether chrono-node has been loaded in this process. */
+export function chronoLoaded() {
+    return chrono !== undefined;
+}
+/**
+ * Loads chrono-node ahead of need. Node never has to: the temporal functions load it
+ * synchronously on first use. A bundled runtime without `require` (a Worker) awaits this once
+ * at startup.
+ */
+export async function preloadChrono() {
+    chrono ??= await import('chrono-node');
+}
+/** chrono-node, loaded synchronously on first call. */
+export function loadChrono() {
+    if (chrono !== undefined)
+        return chrono;
+    const mod = globalThis.process?.getBuiltinModule?.('node:module');
+    if (mod === undefined) {
+        throw new Error('chrono-node is not loaded: await preloadChrono() at startup');
+    }
+    chrono = mod.createRequire(import.meta.url)('chrono-node');
+    return chrono;
+}
+//# sourceMappingURL=date-cue.js.map

package/dist/export-format.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The Oort export format (docs/export-format.md): JSON Lines, a manifest line,
+ * then one memory per line. Version 2 (written by default) adds `address`,
+ * `author` and `provenance` to every line and keeps `scope` on Planet
+ * memories; version 1 has `scope` only and can hold Planet memories only.
+ * Readers accept both, version 1 forever.
+ */
+import { type Address } from './address.js';
+import type { Memory, Scope } from './model.js';
+/** The version `oort export` writes. */
+export declare const EXPORT_FORMAT_VERSION = 2;
+export type ExportVersion = 1 | 2;
+export interface ExportManifestV1 {
+    oort: 'export';
+    version: 1;
+    exportedAt: string;
+    memories: number;
+    /** The distinct scopes of the exported memories. */
+    scopes: Scope[];
+}
+export interface ExportManifestV2 {
+    oort: 'export';
+    version: 2;
+    exportedAt: string;
+    memories: number;
+    /** The distinct scopes of the exported Planet memories. */
+    scopes: Scope[];
+    /** The distinct addresses of every exported memory. */
+    addresses: Address[];
+}
+export type ExportManifest = ExportManifestV1 | ExportManifestV2;
+/** Output-only flags a line may carry (see the format's Limitations). */
+export interface HiddenLinkFlags {
+    supersedesHidden?: true;
+    supersededByHidden?: true;
+}
+/** Raised for a memory a format version cannot hold, or a file that is not a readable export. */
+export declare class ExportFormatError extends Error {
+    constructor(message: string);
+}
+/** True when version 1 can hold `m`: a Planet memory whose author is its scope's agent. */
+export declare function fitsVersion1(m: Memory): boolean;
+/**
+ * One memory as an export line of `version`: the embedding as base64 of its
+ * int8 bytes. Version 2 always writes `address`, `author` and `provenance`
+ * (null when none), and `scope` for Planet memories only.
+ */
+export declare function exportLine(m: Memory & HiddenLinkFlags, version: ExportVersion): Record<string, unknown>;
+/** The manifest for `memories` written as `version`. */
+export declare function exportManifest(memories: Memory[], version: ExportVersion, exportedAt?: Date): ExportManifest;
+/** A whole export: the manifest line, then one line per memory, each ending in `\n`. */
+export declare function formatExport(memories: (Memory & HiddenLinkFlags)[], version?: ExportVersion, exportedAt?: Date): string;
+export interface ParsedExport {
+    version: ExportVersion;
+    manifest: ExportManifest;
+    /** In the shape stores return (see `canonicalMemory`), embeddings decoded. */
+    memories: Memory[];
+}
+export interface ParseExportOptions {
+    /**
+     * The importing person's account: Planet memories move to this owner and
+     * customer (agent, project and everything else kept), the way an import
+     * into another account rewrites the principal. Other levels keep their
+     * addresses. Unset: addresses are kept as written.
+     */
+    planet?: {
+        orgId: string;
+        customerId: string;
+    };
+}
+/**
+ * Reads an export of version 1 or 2. A version 1 line's `scope` names the
+ * memory's Planet and its agent the author. Throws `ExportFormatError` for an
+ * unknown version, a count that does not match, or a line that is not a
+ * memory (with its line number, never its content).
+ */
+export declare function parseExport(text: string, opts?: ParseExportOptions): ParsedExport;

package/dist/export-format.js

@@ -0,0 +1,168 @@
+/**
+ * The Oort export format (docs/export-format.md): JSON Lines, a manifest line,
+ * then one memory per line. Version 2 (written by default) adds `address`,
+ * `author` and `provenance` to every line and keeps `scope` on Planet
+ * memories; version 1 has `scope` only and can hold Planet memories only.
+ * Readers accept both, version 1 forever.
+ */
+import { addressOf, authorOf, canonicalMemory, planetOf, resolveAddressing, scopeOf, } from './address.js';
+/** The version `oort export` writes. */
+export const EXPORT_FORMAT_VERSION = 2;
+/** Raised for a memory a format version cannot hold, or a file that is not a readable export. */
+export class ExportFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExportFormatError';
+    }
+}
+const base64 = (v) => Buffer.from(v.buffer, v.byteOffset, v.byteLength).toString('base64');
+/** True when version 1 can hold `m`: a Planet memory whose author is its scope's agent. */
+export function fitsVersion1(m) {
+    const author = authorOf(m);
+    return (addressOf(m).level === 'user' &&
+        author.accountRef === undefined &&
+        author.agentId === m.scope.agentId &&
+        (m.provenance === undefined || m.provenance === null));
+}
+/**
+ * One memory as an export line of `version`: the embedding as base64 of its
+ * int8 bytes. Version 2 always writes `address`, `author` and `provenance`
+ * (null when none), and `scope` for Planet memories only.
+ */
+export function exportLine(m, version) {
+    const { embedding, address: _a, author: _w, provenance, scope, id, ...rest } = m;
+    const tail = embedding === undefined ? {} : { embedding: base64(embedding) };
+    if (version === 1) {
+        if (!fitsVersion1(m)) {
+            throw new ExportFormatError(`memory ${id} is not a Planet memory; version 1 cannot hold it`);
+        }
+        return { id, scope, ...rest, ...tail };
+    }
+    const address = addressOf(m);
+    return {
+        id,
+        ...(address.level === 'user' && { scope }),
+        address,
+        author: authorOf(m),
+        provenance: provenance ?? null,
+        ...rest,
+        ...tail,
+    };
+}
+const keyOf = (x) => JSON.stringify(Object.entries(x).sort());
+/** The manifest for `memories` written as `version`. */
+export function exportManifest(memories, version, exportedAt = new Date()) {
+    const scopes = new Map();
+    const addresses = new Map();
+    for (const m of memories) {
+        const a = addressOf(m);
+        if (a.level === 'user')
+            scopes.set(keyOf(m.scope), m.scope);
+        addresses.set(keyOf(a), a);
+    }
+    const base = {
+        oort: 'export',
+        exportedAt: exportedAt.toISOString(),
+        memories: memories.length,
+        scopes: [...scopes.values()],
+    };
+    return version === 1
+        ? { ...base, version: 1 }
+        : { ...base, version: 2, addresses: [...addresses.values()] };
+}
+/** A whole export: the manifest line, then one line per memory, each ending in `\n`. */
+export function formatExport(memories, version = EXPORT_FORMAT_VERSION, exportedAt = new Date()) {
+    return [
+        exportManifest(memories, version, exportedAt),
+        ...memories.map((m) => exportLine(m, version)),
+    ]
+        .map((x) => `${JSON.stringify(x)}\n`)
+        .join('');
+}
+/**
+ * Reads an export of version 1 or 2. A version 1 line's `scope` names the
+ * memory's Planet and its agent the author. Throws `ExportFormatError` for an
+ * unknown version, a count that does not match, or a line that is not a
+ * memory (with its line number, never its content).
+ */
+export function parseExport(text, opts = {}) {
+    const lines = text.split('\n').filter((l) => l.trim() !== '');
+    const head = parseJson(lines[0], 1);
+    if (head?.oort !== 'export')
+        throw new ExportFormatError('line 1 is not an Oort export manifest');
+    if (head.version !== 1 && head.version !== 2) {
+        throw new ExportFormatError(`export version ${String(head.version)} is not supported`);
+    }
+    const version = head.version;
+    if (head.memories !== lines.length - 1) {
+        throw new ExportFormatError(`the manifest counts ${String(head.memories)} memories, the file has ${lines.length - 1}`);
+    }
+    const memories = lines.slice(1).map((l, i) => {
+        const n = i + 2;
+        const raw = parseJson(l, n);
+        if (typeof raw !== 'object' || raw === null || typeof raw['id'] !== 'string') {
+            throw new ExportFormatError(`line ${n} is not a memory`);
+        }
+        try {
+            return readLine(raw, version, opts);
+        }
+        catch (e) {
+            if (e instanceof RangeError || e instanceof TypeError) {
+                throw new ExportFormatError(`line ${n}: ${e.message}`);
+            }
+            throw e;
+        }
+    });
+    return { version, manifest: head, memories };
+}
+function parseJson(line, n) {
+    try {
+        return JSON.parse(line ?? '');
+    }
+    catch {
+        throw new ExportFormatError(`line ${n} is not JSON`);
+    }
+}
+function readLine(raw, version, opts) {
+    const { embedding, address: rawAddress, author: rawAuthor, provenance, scope: rawScope, supersedesHidden: _sh, supersededByHidden: _bh, ...rest } = raw;
+    let address;
+    let author;
+    if (version === 1) {
+        const scope = rawScope;
+        if (typeof scope !== 'object' || scope === null)
+            throw new RangeError('a version 1 line needs scope');
+        address = planetOf(scope);
+        author = { agentId: scope.agentId };
+    }
+    else {
+        ({ address, author } = checked(rawAddress, rawAuthor, rawScope));
+    }
+    if (opts.planet !== undefined && address.level === 'user') {
+        address = { ...address, orgId: opts.planet.orgId, customerId: opts.planet.customerId };
+    }
+    const m = {
+        ...rest,
+        scope: scopeOf(address, author),
+        address,
+        author,
+        ...(provenance !== undefined && provenance !== null && { provenance }),
+        ...(typeof embedding === 'string' && {
+            embedding: Int8Array.from(Buffer.from(embedding, 'base64')),
+        }),
+    };
+    return canonicalMemory(m);
+}
+/** A version 2 line's address and author, checked, with its scope (when present) matching them. */
+function checked(rawAddress, rawAuthor, rawScope) {
+    if (rawAddress === undefined || rawAuthor === undefined) {
+        throw new RangeError('a version 2 line needs address and author');
+    }
+    const probe = { address: rawAddress, author: rawAuthor };
+    const want = scopeOf(probe.address, probe.author);
+    const { address, author } = resolveAddressing({
+        ...probe,
+        scope: rawScope === undefined ? want : rawScope,
+    });
+    return { address, author };
+}
+//# sourceMappingURL=export-format.js.map

package/dist/grant.d.ts

@@ -1,6 +1,10 @@
+import { type Address, type Author, type NodeRef } from './address.js';
 import type { ScopeFilter } from './adapters.js';
-import type { Scope } from './model.js';
-/** Who a grant acts for: one (org, customer, agent). Grants never span principals. */
+import type { Memory, Scope } from './model.js';
+/**
+ * Who a grant acts for: an account (`orgId`, `customerId`) and the agent
+ * acting for it. Cursors belong to the principal.
+ */
 export interface Principal {
     orgId: string;
     customerId: string;
@@ -11,49 +15,152 @@ export interface Principal {
  * no project) or `'all'`, every project of the principal plus global.
  */
 export type GrantProjects = readonly (string | null)[] | 'all';
-/** One side (read or write) of a grant, as stores apply it. */
+/**
+ * One side (read or write) of a pre-level grant: the principal's Planet,
+ * written by the principal's agent, in `projectIds`.
+ * @deprecated Stores read `Grant.readNodes` and `Grant.writeNodes`.
+ */
 export interface GrantFilter extends Readonly<Principal> {
     readonly projectIds: GrantProjects;
 }
+/**
+ * One node a grant covers (CON-61): the node, the project bindings inside it,
+ * and optionally one author. Matching is structural and exact on every field
+ * (never a prefix). `authorAgentId` restricts the pattern to memories that
+ * agent wrote. The local constructors (`localGrant`, `principalGrant`) name
+ * the principal's Planet with no author restriction (a person's agents share
+ * their Planet, CON-62) and the principal's agent's own Star.
+ */
+export interface NodePattern {
+    readonly node: NodeRef;
+    readonly projectIds: GrantProjects;
+    readonly authorAgentId?: string;
+}
+/**
+ * Where an agent's new memories land by default (its home node, spec 5.1):
+ * the person's Planet, or the agent's own Star when it is configured as one.
+ */
+export type Home = 'planet' | 'star';
+/**
+ * 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 declare 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 declare class Grant {
     #private;
     readonly principal: Readonly<Principal>;
+    /** @deprecated The pre-level view of `readNodes`; see `GrantFilter`. */
     readonly read: GrantFilter;
+    /** @deprecated The pre-level view of `writeNodes`; see `GrantFilter`. */
     readonly write: GrantFilter;
+    readonly readNodes: readonly NodePattern[];
+    readonly writeNodes: readonly NodePattern[];
+    /**
+     * 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.
+     */
+    readonly home: NodeRef;
     private constructor();
     /** @internal Use `localGrant` or `principalGrant`. */
-    static issue(principal: Principal, read: GrantProjects, write: GrantProjects): Grant;
+    static issue(principal: Principal, read: GrantProjects, write: GrantProjects, home?: Home): Grant;
+    /** @internal Use `nodeGrant` or `narrowGrant`. */
+    static issueNodes(principal: Principal, read: readonly NodePattern[], write: readonly NodePattern[], home?: NodeRef): Grant;
     /** True for a real grant (not a copy, not a look-alike). */
     static is(x: unknown): x is Grant;
 }
+/** The Star of a principal's agent (owned by the principal's owner). */
+export declare function starNode(p: Pick<Principal, 'orgId' | 'agentId'>): NodeRef;
 /**
- * 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 declare function localGrant(read: ScopeFilter, opts?: {
     write?: ScopeFilter;
+    home?: Home;
 }): Grant;
-/** Every project of `p` (and its global memories), for read and write: maintenance such as export. */
-export declare function principalGrant(p: Principal): Grant;
+/**
+ * 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 declare function principalGrant(p: Principal, opts?: {
+    home?: Home;
+}): Grant;
+/**
+ * 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 declare function nodeGrant(opts: {
+    principal: Principal;
+    read: readonly NodePattern[];
+    write?: readonly NodePattern[];
+    /** Where new memories land (default: the principal's Planet if written, else the first node written). */
+    home?: NodeRef;
+}): Grant;
+/**
+ * `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 declare function narrowGrant(g: Grant, keep: readonly NodeRef[]): Grant;
+/** The distinct nodes `g` reads, in the order its patterns name them. */
+export declare function readableNodes(g: Grant): NodeRef[];
+/** The address a new memory gets under `g`: its home node, bound to `projectId` when given. */
+export declare function homeAddress(g: Grant, projectId?: string): Address;
 /** Rejects anything that is not a real `Grant`; every store calls it first. */
 export declare function assertGrant(g: unknown): asserts g is Grant;
-/** 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 declare function filterCovers(f: GrantFilter, scope: Scope): boolean;
+/** True iff `p` covers a memory at `address` written by `author`. */
+export declare function patternCovers(p: NodePattern, address: Address, author: Author): boolean;
+/** True iff `g` may read `m` (by its address and author). */
+export declare const grantReads: (g: Grant, m: Pick<Memory, 'scope' | 'address' | 'author'>) => boolean;
+/** True iff `g` may change `m` (by its address and author). */
+export declare const grantWrites: (g: Grant, m: Pick<Memory, 'scope' | 'address' | 'author'>) => boolean;
+/** True iff `g` may read a Planet memory with `scope` (`scope.agentId` as its author). */
 export declare const canRead: (g: Grant, scope: Scope) => boolean;
+/** True iff `g` may change a Planet memory with `scope` (`scope.agentId` as its author). */
 export declare const canWrite: (g: Grant, scope: Scope) => boolean;
+/**
+ * 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 declare function sameRecordAddress(a: Pick<Memory, 'scope' | 'address' | 'author'>, b: Pick<Memory, 'scope' | 'address' | 'author'>): boolean;
+/** The Planet node of a principal: what pre-level grants cover. */
+export declare function planetNode(p: Pick<Principal, 'orgId' | 'customerId'>): NodeRef;
 /**
  * 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