relembra 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -25,7 +25,7 @@ and storage (an adapter). relembra enforces the rules:
 - **Measured.** An evaluation harness with leak, scope, retrieval and wake-coverage gates, plus
   controls that must fail. Results: [docs/eval/](docs/eval/).
 
-Version: 1.0.0-beta.4, a beta ([changelog](CHANGELOG.md),
+Version: 1.0.0-beta.6, a beta ([changelog](CHANGELOG.md),
 [releases](https://github.com/mneves75/relembra/releases)). Release procedure:
 [docs/RELEASE.md](docs/RELEASE.md).
 Design: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
@@ -57,7 +57,7 @@ Entry points:
 
 | Import | What |
 |---|---|
-| `relembra` | `createRelembra`, the error types and the domain types |
+| `relembra` | `createRelembra`, `advanceFence`, `exportJsonl`, `importJsonl`, `importOptmem`, `integrationOpId`, `identityEgress`, the error types and the domain types |
 | `relembra/sqlite` | `openSqliteStore`, the SQLite adapter (`node:sqlite`) |
 | `relembra/postgres` | `openPostgresStore`, the Postgres adapter over a SQL client the host passes |
 | `relembra/pi-durable` | `createMemoryExtension`, memory tools for a pi-durable Harness |
@@ -226,7 +226,7 @@ On Windows, check the hash with `Get-FileHash` and copy the binary onto `PATH` a
 
 Before replacing an installed executable, retain a backup and its hash. Verify installed bytes
 against the release checksum and export metadata from a disposable store
-(`relembra: "1.0.0-beta.4"`); there is no `--version` flag. The [release procedure](docs/RELEASE.md) covers isolated checks and
+(`relembra: "1.0.0-beta.6"`); there is no `--version` flag. The [release procedure](docs/RELEASE.md) covers isolated checks and
 rollback without opening a live memory store. After verification, `relembra init` prints the
 session hook for your agent.
 
@@ -238,8 +238,11 @@ Commands, flags, exit codes and the JSON envelope: [docs/CLI.md](docs/CLI.md).
 
 ## MCP
 
-`relembra mcp` is an MCP server over stdio for clients that speak protocol revision 2026-07-28
-(older revisions are refused with the supported list). It is a subcommand of the same binary,
+`relembra mcp` is a dual-era MCP server over stdio supporting 2026-07-28, 2025-11-25,
+2025-06-18, 2025-03-26 and 2024-11-05. Modern requests carry their version and capabilities in
+`_meta` and stay stateless, even after a legacy `initialize` in the same process. Legacy clients
+negotiate once with `initialize`: a supported legacy version is returned unchanged; any other
+string falls back to 2025-11-25. It is a subcommand of the same binary,
 so it takes its scope, principal and store from the launch environment exactly as the CLI does,
 and no tool argument changes them. It writes at `agent`
 trust at most and never asks for owner trust. Its tools are `note`, `find`, `brief`, `wake` and
@@ -251,7 +254,7 @@ project's directory or with `RELEMBRA_SCOPE` set. The contract (methods, tools,
 framing, pending requests) is in [docs/CLI.md](docs/CLI.md#relembra-mcp).
 
 The server holds at most 64 requests queued or running. One more gets the error `-31000`,
-`data: { maxPending: 64 }`, at once and is never queued. The revision defines no overload code and
+`data: { maxPending: 64 }`, at once and is never queued. The modern revision defines no overload code and
 reserves `-32020` to `-32099` for its own, so `-31000` sits outside `-32768` to `-32000`, as its
 Error Codes section asks. A client that stops reading its responses stops being read.
 
@@ -259,11 +262,18 @@ Qualified with the official MCP TypeScript SDK client, `@modelcontextprotocol/cl
 (with `@modelcontextprotocol/core` 2.4.0), pinned to protocol revision 2026-07-28
 (`versionNegotiation: { mode: { pin: "2026-07-28" } }`): `test/cli/mcp-sdk.test.ts` runs a stdio
 round trip through it against the built binary. It is a development dependency only; the library
-and the binary have no runtime dependencies. A client that speaks only the earlier,
-`initialize`-based revisions cannot use this server: `initialize` is refused with `-32022`, which
-names the supported version.
+and the binary have no runtime dependencies. The motivating initialize-based clients are codex
+0.166.0 (2025-06-18) and opencode 1.19.5 (2025-11-25); the SDK test also covers legacy negotiation.
 
-Implemented from these pages of the specification (read 2026-10-31):
+Legacy results omit modern result and cache metadata. The 2024-11-05 tool definitions contain
+only `name`, `description` and `inputSchema`; 2025-03-26 adds annotations with `annotations.title`
+and alone accepts JSON-RPC batches. From 2025-06-18, tools also have top-level titles and output
+schemas where defined, results may carry structured content, and `serverInfo` has a title.
+Only 2025-11-25 returns input-schema failures as tool execution errors; earlier revisions and
+modern requests return `-32602`. Legacy sessions support `ping`, `tools/list` and `tools/call`.
+A modern `_meta` naming another version gets `-32022` with all five supported versions.
+
+Implemented from these pages of the specification:
 
 - [Key Changes](https://modelcontextprotocol.io/specification/2026-07-28/changelog): no
   `initialize` handshake, per-request `_meta`, required `server/discover`, `resultType`, `ttlMs`
@@ -273,8 +283,19 @@ Implemented from these pages of the specification (read 2026-10-31):
   ("Per-request protocol fields", "Per-response protocol fields").
 - [Versioning and Compatibility](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning):
   Protocol Version Negotiation, and "Backward Compatibility with Initialization-Based Versions"
-  for the answer to `initialize`. The revision has no lifecycle page:
+  for dual-era operation. The revision has no lifecycle page:
   `/specification/2026-07-28/basic/lifecycle` redirects here.
+- Legacy lifecycle: [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle),
+  [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle),
+  [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/lifecycle) and
+  [2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle):
+  initialization and version negotiation.
+- Legacy key changes: [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/changelog)
+  adds annotations and requires batching;
+  [2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/changelog) adds structured
+  output, output schemas and titles, and removes batching;
+  [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/changelog) makes input
+  validation failures tool execution errors (SEP-1303).
 - [stdio](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio): the
   framing, stdout and stderr rules, Cancellation and Shutdown.
 - [Cancellation](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/cancellation).
@@ -291,8 +312,8 @@ Implemented from these pages of the specification (read 2026-10-31):
 
 Where these pages go beyond the ticket, the server follows them: cache fields go on
 `server/discover` and `tools/list` only (the Caching page lists no other operation this server
-offers), `serverInfo` is in every result's `_meta` (a SHOULD), and `initialize` is answered with
-`-32022` naming the supported version (a SHOULD for a server that speaks no legacy revision).
+offers), and `serverInfo` is in every modern result's `_meta` (a SHOULD). Legacy results follow
+their negotiated revision; initialize params never change the environment's scope or principal.
 
 The 2026-07-28 revision has no per-call identifier a server could derive an op id from, and the
 JSON-RPC id changes on every retry. So instead of the plan's `[host, conversation, task, call]`

package/dist/frozen.d.ts

@@ -0,0 +1,4 @@
+/** Frozen, detached copies, as the stores hand values out: a caller cannot change what is stored. */
+import type { Event, NewEvent } from "./model.js";
+export declare function deepFreeze<T>(value: T): T;
+export declare function detachEvent(event: NewEvent, seq: number): Event;

package/dist/frozen.js

@@ -0,0 +1,11 @@
+export function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+export function detachEvent(event, seq) {
+    return deepFreeze(structuredClone({ ...event, seq }));
+}

package/dist/model.d.ts

@@ -12,6 +12,8 @@ export type OpId = string;
  * model. `agent`: model-authored and unreviewed. `untrusted`: known to come from external content.
  */
 export type Trust = "owner" | "agent" | "untrusted";
+/** Every trust tier, highest first. */
+export declare const TRUSTS: readonly Trust[];
 /**
  * A writer's authority as the host grants it: a fencing key and the epoch this writer holds. The
  * store keeps the highest epoch it has seen per key. A write whose epoch is lower commits

package/dist/model.js

@@ -1,3 +1,5 @@
+/** Every trust tier, highest first. */
+export const TRUSTS = ["owner", "agent", "untrusted"];
 /**
  * The event format of the kinds format 1 defines (note, retract, redact, supersede, summarize),
  * which every event of those kinds carries (docs/FORMAT.md).

package/dist/optmem.js

@@ -9,7 +9,6 @@ import { findGuardViolation, MAX_MEMORY_BYTES } from "./guard.js";
 import { EVENT_FORMAT, } from "./model.js";
 import { systemClock } from "./ports.js";
 import { acceptanceTime, checkFence, checkName, checkPrincipal, checkProvenance, enforceFence, lowerTrust, owns, trustCeiling, } from "./relembra.js";
-import { MAX_SCOPE_BYTES, utf8Bytes } from "./render.js";
 import { MAX_IMPORT_BYTES, MAX_IMPORT_EVENTS, } from "./transfer.js";
 const STORE_NAME = /^[A-Za-z0-9._-]{1,64}$/;
 const NEWLINE = 0x0a;
@@ -48,9 +47,6 @@ export async function importOptmem(store, principal, input) {
         throw new ScopeDeniedError("own");
     if (!principal.writable.includes(scope))
         throw new ScopeDeniedError("write");
-    if (typeof scope !== "string" || scope === "" || utf8Bytes(scope) > MAX_SCOPE_BYTES) {
-        throw new RangeError(`a scope must be 1 to ${MAX_SCOPE_BYTES} UTF-8 bytes`);
-    }
     checkName("scope", scope);
     if (typeof name !== "string" || !STORE_NAME.test(name)) {
         throw new RangeError("an OptMem store name is 1 to 64 letters, digits, '.', '_' or '-'");

package/dist/pi-durable/index.js

@@ -1,5 +1,6 @@
+import { MAX_MEMORY_BYTES } from "../guard.js";
 import { integrationOpId } from "../ops.js";
-import { checkCarrier } from "../relembra.js";
+import { checkCarrier, MAX_FIND_LIMIT, MAX_QUERY_LENGTH, } from "../relembra.js";
 export const MEMORY_EXTENSION_NAME = "relembra";
 /**
  * The key of relembra's system prompt section. Section keys are shared by every extension (a later
@@ -8,9 +9,8 @@ export const MEMORY_EXTENSION_NAME = "relembra";
 export const MEMORY_SECTION_KEY = "relembra_memory";
 /** What the memory section shows when the wake cannot be rendered: no memory text at all. */
 export const WAKE_UNAVAILABLE = '<wake unavailable="true"/>';
+/** The most an argument may hold before the guard reads it; the guard's own limit is far lower. */
 const MAX_TEXT = 4_000;
-const MAX_QUERY = 1_000;
-const MAX_LIMIT = 100;
 /** pi-durable's generation task; hooks match tasks by this name. */
 const GENERATION_TASK = "pi.generation";
 /** The kind of every carrier this extension records. */
@@ -35,7 +35,8 @@ export function createMemoryExtension(options) {
     const resolve = async (conversationId) => options.resolve(conversationId);
     const note = {
         name: "memory_note",
-        description: "Save one durable fact for later sessions: a decision, preference or lesson, as one line.",
+        description: "Save one durable fact for later sessions: a decision, preference or lesson, as one line " +
+            `of at most ${MAX_MEMORY_BYTES} bytes.`,
         parameters: {
             type: "object",
             required: ["text"],
@@ -66,13 +67,13 @@ export function createMemoryExtension(options) {
             type: "object",
             required: ["query"],
             properties: {
-                query: { type: "string", minLength: 1, maxLength: MAX_QUERY },
-                limit: { type: "integer", minimum: 1, maximum: MAX_LIMIT },
+                query: { type: "string", minLength: 1, maxLength: MAX_QUERY_LENGTH },
+                limit: { type: "integer", minimum: 1, maximum: MAX_FIND_LIMIT },
             },
             additionalProperties: false,
         },
         replay: "safe",
-        prepareArguments: strictArguments("memory_find", "query", MAX_QUERY, true),
+        prepareArguments: strictArguments("memory_find", "query", MAX_QUERY_LENGTH, true),
         async execute(args, api) {
             const { context } = await resolve(api.conversationId);
             const limit = args.limit;
@@ -90,11 +91,11 @@ export function createMemoryExtension(options) {
         parameters: {
             type: "object",
             required: ["topic"],
-            properties: { topic: { type: "string", minLength: 1, maxLength: MAX_QUERY } },
+            properties: { topic: { type: "string", minLength: 1, maxLength: MAX_QUERY_LENGTH } },
             additionalProperties: false,
         },
         replay: "safe",
-        prepareArguments: strictArguments("memory_brief", "topic", MAX_QUERY),
+        prepareArguments: strictArguments("memory_brief", "topic", MAX_QUERY_LENGTH),
         async execute(args, api) {
             const { context } = await resolve(api.conversationId);
             const rendering = await relembra.brief(context, {
@@ -178,7 +179,7 @@ function withWake(messages, wake) {
  */
 function strictArguments(tool, field, max, limit = false) {
     const message = `${tool}: invalid arguments: ${field} must be a string of 1 to ${max} characters` +
-        `${limit ? `, limit an optional integer from 1 to ${MAX_LIMIT}` : ""}, and nothing else`;
+        `${limit ? `, limit an optional integer from 1 to ${MAX_FIND_LIMIT}` : ""}, and nothing else`;
     const allowed = new Set(limit ? [field, "limit"] : [field]);
     return (args) => {
         if (typeof args !== "object" || args === null || Array.isArray(args))
@@ -193,7 +194,7 @@ function strictArguments(tool, field, max, limit = false) {
         if (!limit || given.limit === undefined)
             return { [field]: value };
         const count = given.limit;
-        if (!Number.isInteger(count) || count < 1 || count > MAX_LIMIT) {
+        if (!Number.isInteger(count) || count < 1 || count > MAX_FIND_LIMIT) {
             throw new Error(message);
         }
         return { [field]: value, limit: count };

package/dist/postgres/index.js

@@ -1,4 +1,5 @@
 import { StoreBusyError } from "../errors.js";
+import { detachEvent } from "../frozen.js";
 import { redactedEvent, } from "../model.js";
 import { sqlState } from "./client.js";
 import { MIGRATIONS, migrate } from "./migrations.js";
@@ -431,9 +432,6 @@ function pause(attempts) {
     const ceiling = Math.min(2 ** attempts, 64);
     return new Promise((done) => setTimeout(done, ceiling / 2 + Math.random() * ceiling));
 }
-function detachEvent(event, seq) {
-    return deepFreeze(structuredClone({ ...event, seq }));
-}
 function memoryRow(memory) {
     return [
         memory.id,
@@ -482,11 +480,3 @@ function opFromRow(row) {
         seq: Number(row.seq),
     };
 }
-function deepFreeze(value) {
-    if (typeof value === "object" && value !== null) {
-        for (const child of Object.values(value))
-            deepFreeze(child);
-        Object.freeze(value);
-    }
-    return value;
-}

package/dist/relembra.d.ts

@@ -306,6 +306,10 @@ export interface BriefInput extends RenderingTarget {
     /** The most UTF-8 bytes the rendering may have, frame included. Default 9,500. */
     readonly budgetBytes?: number;
 }
+/** The most results one find may return. */
+export declare const MAX_FIND_LIMIT = 100;
+/** The most characters a find query or a brief topic may have. */
+export declare const MAX_QUERY_LENGTH = 1000;
 export declare function createRelembra<Context>(options: RelembraOptions<Context>): Relembra<Context>;
 /** A rendering's carrier, once both its fields pass the identifier rule; undefined when absent. */
 export declare function checkCarrier(carrier: Carrier | undefined): Carrier | undefined;
@@ -318,6 +322,8 @@ export declare function advanceFence(store: Store, fence: AuthorityFence): Promi
 export declare function enforceFence(tx: StoreTransaction, fence: AuthorityFence): Promise<void>;
 /** Copies the fence once, so an accessor cannot answer differently to the check and the store. */
 export declare function checkFence(fence: AuthorityFence): AuthorityFence;
+/** The most sources one summary may have. */
+export declare const MAX_SUMMARY_SOURCES = 100;
 /**
  * The sources copied once, checked (1 to 100, each a memory id and a positive revision, no memory
  * twice) and sorted by memory id, so the order they were given in changes nothing.

package/dist/relembra.js

@@ -8,8 +8,10 @@ import { hasTokens, parseQuery, rank, scoreIndex } from "./ranking.js";
 import { briefEntries, briefSummaries, checkBudget, coveredIds, DEFAULT_BUDGET_BYTES, findEntries, fitRendering, identityEgress, isSummary, MAX_ID_BYTES, MAX_SCOPE_BYTES, newestFirst, trustOf, utf8Bytes, wakeEntries, wakeOrder, } from "./render.js";
 const DEFAULT_RECALL_LIMIT = 50;
 const DEFAULT_FIND_LIMIT = 10;
-const MAX_FIND_LIMIT = 100;
-const MAX_QUERY_LENGTH = 1_000;
+/** The most results one find may return. */
+export const MAX_FIND_LIMIT = 100;
+/** The most characters a find query or a brief topic may have. */
+export const MAX_QUERY_LENGTH = 1_000;
 export function createRelembra(options) {
     const { store } = options;
     // Every principal the host's policy gives is checked once, before any operation uses it.
@@ -687,7 +689,7 @@ function checkRetention(given) {
     return Object.freeze(rules);
 }
 /** The most sources one summary may have. */
-const MAX_SUMMARY_SOURCES = 100;
+export const MAX_SUMMARY_SOURCES = 100;
 /**
  * The sources copied once, checked (1 to 100, each a memory id and a positive revision, no memory
  * twice) and sorted by memory id, so the order they were given in changes nothing.

package/dist/sqlite/database.d.ts

@@ -62,6 +62,8 @@ export declare function storeFolderAccounts(userSid: string): string[];
  * chmodded: someone else may already have read it.
  */
 export declare function checkOwnerOnly(path: string): void;
+/** Whether the store file's header says WAL (bytes 18 and 19 are 2). A new, empty file does not. */
+export declare function walInHeader(path: string): boolean;
 /**
  * Opens the file defensively, refuses a newer schema before changing anything, then switches to
  * WAL with synchronous=FULL and migrates. Busy errors on the way become StoreBusyError.

package/dist/sqlite/database.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, } from "node:fs";
 import { dirname, win32 } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { pathToFileURL } from "node:url";
@@ -341,9 +341,16 @@ function switchToWal(db, timeoutMs) {
     }
 }
 /** Whether the store file's header says WAL (bytes 18 and 19 are 2). A new, empty file does not. */
-function walInHeader(path) {
-    const header = readFileSync(path).subarray(0, 20);
-    return header.length === 20 && header[18] === 2 && header[19] === 2;
+export function walInHeader(path) {
+    // The header only: the file is the whole store, and every open comes through here.
+    const header = new Uint8Array(20);
+    const fd = openSync(path, "r");
+    try {
+        return readSync(fd, header, 0, 20, 0) === 20 && header[18] === 2 && header[19] === 2;
+    }
+    finally {
+        closeSync(fd);
+    }
 }
 /**
  * Switches a rollback-journal (or new) file to WAL only after checking its schema version, under

package/dist/sqlite/index.js

@@ -1,3 +1,4 @@
+import { detachEvent } from "../frozen.js";
 import { redactedEvent, } from "../model.js";
 import { checkBusyTimeout, createOwnerOnly, isBusy, openDatabase, StoreBusyError, } from "./database.js";
 import { termIndex } from "./term-index.js";
@@ -423,9 +424,6 @@ async function withBusyRetry(timeoutMs, step) {
         }
     }
 }
-function detachEvent(event, seq) {
-    return deepFreeze(structuredClone({ ...event, seq }));
-}
 function memoryRow(memory) {
     return [
         memory.id,
@@ -474,11 +472,3 @@ function opFromRow(row) {
         seq: row.seq,
     };
 }
-function deepFreeze(value) {
-    if (typeof value === "object" && value !== null) {
-        for (const child of Object.values(value))
-            deepFreeze(child);
-        Object.freeze(value);
-    }
-    return value;
-}

package/dist/testing/memory-store.js

@@ -1,3 +1,4 @@
+import { deepFreeze } from "../frozen.js";
 import { redactedEvent, } from "../model.js";
 import { documentTerms } from "../ranking.js";
 /** A store held in process memory, for tests and examples. */
@@ -250,11 +251,3 @@ function opKey(principalId, opId) {
 function snapshot(value) {
     return deepFreeze(structuredClone(value));
 }
-function deepFreeze(value) {
-    if (typeof value === "object" && value !== null) {
-        for (const child of Object.values(value))
-            deepFreeze(child);
-        Object.freeze(value);
-    }
-    return value;
-}

package/dist/transfer.js

@@ -5,7 +5,7 @@
  */
 import { IdentifierError, ImportError, ProvenanceError, ScopeDeniedError, } from "./errors.js";
 import { findGuardViolation, MAX_MEMORY_BYTES } from "./guard.js";
-import { EVENT_FORMAT, LATEST_EVENT_FORMAT, PROMOTE_FORMAT, } from "./model.js";
+import { EVENT_FORMAT, LATEST_EVENT_FORMAT, PROMOTE_FORMAT, TRUSTS, } from "./model.js";
 import { systemClock } from "./ports.js";
 import { acceptanceTime, checkFence, checkPrincipal, checkProvenance, checkSources, enforceCeiling, enforceFence, liveDerived, lowerTrust, MAX_PRINCIPAL_ID_BYTES, owns, redactionPlan, redactWithDerived, retractAll, trustCeiling, } from "./relembra.js";
 import { isSummary, MAX_ID_BYTES, MAX_SCOPE_BYTES, utf8Bytes } from "./render.js";
@@ -210,7 +210,6 @@ function checkPrincipalId(id, line) {
     checkIdentifier("principalId", id, MAX_PRINCIPAL_ID_BYTES, line);
 }
 const CAUSES = ["request", "retention", "source"];
-const TRUSTS = ["owner", "agent", "untrusted"];
 /** One event line, checked field by field; anything else in the line is ignored. */
 function checkEvent(value, line, header, latest) {
     const { scopes } = header;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** This relembra's version, as package.json gives it. An export's header carries it. */
-export declare const RELEMBRA_VERSION = "1.0.0-beta.4";
+export declare const RELEMBRA_VERSION = "1.0.0-beta.6";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** This relembra's version, as package.json gives it. An export's header carries it. */
-export const RELEMBRA_VERSION = "1.0.0-beta.4";
+export const RELEMBRA_VERSION = "1.0.0-beta.6";

package/docs/FORMAT.md

@@ -1,6 +1,6 @@
 # relembra storage format
 
-Status: event formats 1 and 2, SQLite schema version 6, Postgres schema version 3. Release 1.0.0-beta.4.
+Status: event formats 1 and 2, SQLite schema version 6, Postgres schema version 3. Release 1.0.0-beta.6.
 
 This document is the contract for what relembra stores. A reader that follows it needs no
 relembra code.
@@ -175,7 +175,7 @@ the events above, so a reader needs only this document.
 |---|---|---|
 | `export` | string | Always `relembra`. What makes the file an export. |
 | `format` | integer | The newest event format of the lines after it: `1` when none is a `promote` line, so a format 1 reader still reads the file, and `2` when one is. |
-| `relembra` | string | The relembra version that wrote the file, such as `1.0.0-beta.4`. Informational: a reader decides by `format` alone. |
+| `relembra` | string | The relembra version that wrote the file, such as `1.0.0-beta.6`. Informational: a reader decides by `format` alone. |
 | `scopes` | array of strings | The scopes exported. Every event's `scope` is one of them. |
 
 ### Events (lines 2 onward)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relembra",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "description": "A curated, scoped, bounded, durable, erasable and measured memory for AI agents.",
   "license": "MIT",
   "author": "mneves75",

package/dist/cli/args.d.ts

@@ -1,26 +0,0 @@
-import { type CommandSpec } from "./commands.js";
-export interface Parsed {
-    readonly command: CommandSpec;
-    readonly positionals: readonly string[];
-    /** Each given flag's values; a boolean flag has one empty value. */
-    readonly flags: ReadonlyMap<string, readonly string[]>;
-}
-export type ParseResult = {
-    readonly kind: "help";
-} | {
-    readonly kind: "command";
-    readonly parsed: Parsed;
-};
-/** Whether `--json` appears before any `--`, so even a usage error can answer in JSON. */
-export declare function wantsJson(argv: readonly string[]): boolean;
-/**
- * Parses `argv` against the command table. Every token that starts with `-` before `--` must be
- * a flag the command declares (or a global flag): an unknown flag is a usage error, never
- * ignored, so no spelling of an undeclared option can change what a command does.
- */
-export declare function parseArgs(argv: readonly string[]): ParseResult;
-/** The single value of a flag, or undefined when it was not given. */
-export declare function flagValue(parsed: Parsed, name: string): string | undefined;
-export declare function hasFlag(parsed: Parsed, name: string): boolean;
-/** A positive integer flag value, at most `max`; undefined when the flag is absent. */
-export declare function intFlag(parsed: Parsed, name: string, max: number): number | undefined;

package/dist/cli/args.js

@@ -1,109 +0,0 @@
-import { COMMANDS } from "./commands.js";
-import { usage } from "./errors.js";
-/** Whether `--json` appears before any `--`, so even a usage error can answer in JSON. */
-export function wantsJson(argv) {
-    for (const arg of argv) {
-        if (arg === "--")
-            return false;
-        if (arg === "--json")
-            return true;
-    }
-    return false;
-}
-/**
- * Parses `argv` against the command table. Every token that starts with `-` before `--` must be
- * a flag the command declares (or a global flag): an unknown flag is a usage error, never
- * ignored, so no spelling of an undeclared option can change what a command does.
- */
-export function parseArgs(argv) {
-    if (argv.includes("--help") && !argv.slice(0, argv.indexOf("--help")).includes("--")) {
-        return { kind: "help" };
-    }
-    const [name, ...rest] = argv.filter((arg, index) => !(arg === "--json" && !argv.slice(0, index).includes("--")));
-    if (name === undefined)
-        throw usage("missing-command", "no command given; see relembra --help");
-    const command = COMMANDS.find((spec) => spec.name === name);
-    if (command === undefined)
-        throw usage("unknown-command", `unknown command: ${name.slice(0, 40)}`);
-    const positionals = [];
-    const flags = new Map();
-    for (let index = 0; index < rest.length; index++) {
-        const arg = rest[index];
-        if (arg === "--") {
-            positionals.push(...rest.slice(index + 1));
-            break;
-        }
-        if (!arg.startsWith("-") || arg === "-") {
-            positionals.push(arg);
-            continue;
-        }
-        const equals = arg.indexOf("=");
-        const flagName = equals < 0 ? arg : arg.slice(0, equals);
-        const spec = command.flags.find((flag) => flag.name === flagName);
-        if (spec === undefined) {
-            throw usage("unknown-flag", `${command.name} takes no flag ${flagName.slice(0, 40)}`);
-        }
-        let value = "";
-        if (spec.value) {
-            if (equals >= 0)
-                value = arg.slice(equals + 1);
-            else {
-                const next = rest[index + 1];
-                if (next === undefined)
-                    throw usage("missing-value", `${flagName} needs a value`);
-                value = next;
-                index++;
-            }
-        }
-        else if (equals >= 0) {
-            throw usage("unexpected-value", `${flagName} takes no value`);
-        }
-        const values = flags.get(flagName) ?? [];
-        if (values.length > 0 && !spec.repeat) {
-            throw usage("repeated-flag", `${flagName} may be given once`);
-        }
-        flags.set(flagName, [...values, value]);
-    }
-    checkPositionals(command, positionals);
-    return { kind: "command", parsed: { command, positionals, flags } };
-}
-function checkPositionals(command, positionals) {
-    const count = positionals.length;
-    const max = {
-        none: 0,
-        id: 1,
-        text: 1,
-        "id-text": 2,
-        words: Number.POSITIVE_INFINITY,
-        path: 1,
-    }[command.positionals];
-    const min = { none: 0, id: 1, text: 0, "id-text": 1, words: 1, path: 0 }[command.positionals];
-    if (count > max) {
-        throw usage("extra-argument", command.positionals === "text" || command.positionals === "id-text"
-            ? `${command.name} takes the text as one argument; quote it`
-            : `${command.name} takes at most ${max} argument${max === 1 ? "" : "s"}`);
-    }
-    if (count < min)
-        throw usage("missing-argument", `usage: ${command.usage}`);
-}
-/** The single value of a flag, or undefined when it was not given. */
-export function flagValue(parsed, name) {
-    return parsed.flags.get(name)?.[0];
-}
-export function hasFlag(parsed, name) {
-    return parsed.flags.has(name);
-}
-/** A positive integer flag value, at most `max`; undefined when the flag is absent. */
-export function intFlag(parsed, name, max) {
-    const value = flagValue(parsed, name);
-    if (value === undefined)
-        return undefined;
-    if (!/^[0-9]{1,15}$/.test(value)) {
-        throw usage("bad-value", `${name} takes a whole number from 1 to ${max}`);
-    }
-    const number = Number(value);
-    if (number < 1 || number > max) {
-        throw usage("bad-value", `${name} takes a whole number from 1 to ${max}`);
-    }
-    return number;
-}

package/dist/cli/commands.d.ts

@@ -1,40 +0,0 @@
-/**
- * The CLI's command table: every command, its arguments and its flags. docs/CLI.md documents
- * exactly this table, and test/cli/contract.test.ts checks the two against each other.
- * No flag names a scope, a home or a user: those come from the environment only.
- */
-export interface FlagSpec {
-    /** `--name`. */
-    readonly name: string;
-    /** Whether the flag takes a value (`--limit 5`, `--limit=5`). */
-    readonly value: boolean;
-    /** Whether the flag may be given more than once. */
-    readonly repeat?: boolean;
-}
-/** What a command takes as positional arguments. */
-export type Positionals = 
-/** None. */
-"none"
-/** Exactly one memory id. */
- | "id"
-/** At most one text argument; stdin when absent. */
- | "text"
-/** A memory id, then at most one text argument; stdin when absent. */
- | "id-text"
-/** One or more words, joined by single spaces. */
- | "words"
-/** At most one file path. */
- | "path";
-export interface CommandSpec {
-    readonly name: string;
-    readonly positionals: Positionals;
-    readonly flags: readonly FlagSpec[];
-    /** One line for `relembra --help`. */
-    readonly usage: string;
-}
-export declare const COMMANDS: readonly CommandSpec[];
-/** Flags every command takes. */
-export declare const GLOBAL_FLAGS: readonly ["--json", "--help"];
-/** The environment the CLI reads, in the order docs/CLI.md lists it. */
-export declare const ENV_VARS: readonly ["RELEMBRA_HOME", "RELEMBRA_SCOPE", "RELEMBRA_GLOBAL_SCOPE", "RELEMBRA_AGENT", "RELEMBRA_HARNESS", "RELEMBRA_MODEL", "BUN_OPTIONS", "BUN_BYTECODE_ORDER_OUT", "PATH", "HOME", "XDG_CONFIG_HOME", "SystemRoot"];
-export declare function usageText(): string;