@vaur94/agz-memory 0.4.1 → 0.5.0

package/dist/types/capture/contract.d.ts

@@ -1,5 +1,5 @@
 import * as z from "zod/v4";
-export declare const CAPTURE_SCHEMA: "agz-memory.capture/1";
+export declare const CAPTURE_SCHEMA: "agz-memory.capture/2";
 export declare const SUPPORTED_OPENCODE_VERSION: "0.0.0-beta-18743";
 export declare const CAPTURE_EVENT_MAX_BYTES: number;
 export declare const CAPTURE_CONTENT_MAX_CHARACTERS = 4800;
@@ -34,7 +34,7 @@ declare const candidateSchema: z.ZodObject<{
     }>;
 }, z.core.$strict>;
 export declare const captureEventSchema: z.ZodObject<{
-    schema: z.ZodLiteral<"agz-memory.capture/1">;
+    schema: z.ZodLiteral<"agz-memory.capture/2">;
     idempotencyKey: z.ZodString;
     projectID: z.ZodUUID;
     bindingKey: z.ZodString;
@@ -96,7 +96,9 @@ export declare const captureEventSchema: z.ZodObject<{
         truncated: z.ZodBoolean;
     }, z.core.$strict>;
 }, z.core.$strict>;
-export type MemoryCandidateV1 = z.infer<typeof candidateSchema>;
-export type CaptureEventV1 = z.infer<typeof captureEventSchema>;
-export declare function parseCaptureEvent(value: unknown): CaptureEventV1;
+export type MemoryCandidateV2 = z.infer<typeof candidateSchema>;
+export type CaptureEventV2 = z.infer<typeof captureEventSchema>;
+export type MemoryCandidateV1 = MemoryCandidateV2;
+export type CaptureEventV1 = CaptureEventV2;
+export declare function parseCaptureEvent(value: unknown): CaptureEventV2;
 export {};

package/dist/types/capture/redact.d.ts

@@ -9,4 +9,5 @@ export interface RedactionResult {
 export declare function redactText(value: string, options?: {
     maxCharacters?: number;
     denylist?: readonly string[];
+    sourceTruncated?: boolean;
 }): RedactionResult;

package/dist/types/context.d.ts

@@ -1 +1 @@
-export declare const MEMORY_GUIDANCE = "Use project-scoped memory for durable facts across sessions.\n- Start with project_list. Use the immutable projectID for stable references; projectName is a convenient unique lookup.\n- Create a project with project_create before storing its first note. Renaming a project never changes its ID.\n- Every memory_recall, memory_read, memory_update, memory_link, and memory_pin call must select exactly one project by projectID or projectName.\n- No notes are injected automatically; use memory_recall for relevant project history.\n- Read indexed note bodies and graph neighbors with memory_read.\n- Store only durable verified facts, decisions, procedures, research, preferences, or substantial completed work.\n- Use memory_pin to prioritize important matching notes inside their project. Pinning never moves notes between projects.\n- Never save transcripts, guesses, secrets, or routine progress.\n- project_delete permanently destroys the project and all of its memory. Call project_list first and provide the immutable ID, exact current name, and required confirmation phrase only when deletion is explicitly intended.";
+export declare const MEMORY_GUIDANCE = "Use project-scoped memory for durable facts across sessions.\n- Start with project_list. Reuse a project only when it intentionally represents the same durable workspace or product; create one only when no matching project exists. If the listed projects are ambiguous, ask rather than guessing from a directory or session name.\n- Prefer the immutable projectID for stable references. projectName is a convenient unique lookup, but names can change.\n- Every memory_recall, memory_read, memory_update, memory_link, and memory_pin call must select exactly one project by projectID or projectName.\n- The MCP server does not inject notes automatically. Recall relevant history before relying on prior decisions, and use memory_read for full indexed content and graph neighbors.\n- After substantial completed work, update an existing note or create a new one only for durable verified facts, decisions, procedures, research, preferences, tasks, or context.\n- Never save transcripts, guesses, secrets, credentials, hidden reasoning, or routine progress.\n- Use memory_pin only to prioritize important matching notes. Read directed links as sourceID PREDICATE targetID; links never cross projects.\n- Inspect every result from a batch because mutations are ordered and non-atomic: earlier items remain applied when a later item fails.\n- memory_update with delete:true permanently deletes one note. project_delete permanently deletes a project and all owned memory. Verify current IDs first and use destructive operations only when explicitly intended.";

package/dist/types/core.d.ts

@@ -1,4 +1,4 @@
-import type { RetrievalBackend } from "./retrieval/contract";
+import type { OutboxBackend, RetrievalBackend } from "./retrieval/contract";
 import { type OpenedDB } from "./db";
 import { CaptureStore } from "./store/capture";
 import { MemoryStore } from "./store";
@@ -7,7 +7,7 @@ import { RetrievalStore } from "./store/retrieval";
 export interface MemoryCoreOptions {
     indexBackends?: readonly string[];
     retrievalBackend?: RetrievalBackend;
-    outboxBackends?: ReadonlyMap<string, RetrievalBackend>;
+    outboxBackends?: ReadonlyMap<string, OutboxBackend>;
 }
 export declare class MemoryCore {
     private opened;

package/dist/types/db/backup.d.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { type MaintenanceGate } from "./maintenance";
 export declare const BACKUP_FORMAT: "agz-memory-backup/1";
 export interface BackupManifest {
     format: typeof BACKUP_FORMAT;
@@ -21,5 +22,5 @@ export interface VerifiedBackup {
 }
 export declare function createVerifiedBackup(db: Database, databasePath: string, sourceSchema: number, targetSchema: number, productVersion: string): VerifiedBackup;
 export declare function verifyBackupManifest(manifestPath: string): VerifiedBackup;
-export declare function restoreVerifiedBackup(manifestPath: string, targetPath: string, confirmation: string): string;
+export declare function restoreVerifiedBackup(manifestPath: string, targetPath: string, confirmation: string, existingGate?: MaintenanceGate, expectedSha256?: string): string;
 export declare function inspectBackupDatabase(path: string): import("./health").DatabaseHealth;

package/dist/types/db/health.d.ts

@@ -7,5 +7,7 @@ export interface DatabaseHealth {
 }
 export declare function inspectDatabase(db: Database): DatabaseHealth;
 export declare function assertHealthyDatabase(db: Database): DatabaseHealth;
+export declare function assertSchemaV11(db: Database): void;
+export declare function isSQLiteBusyError(error: unknown): boolean;
 export declare function hasTable(db: Database, table: string): boolean;
 export declare function hasColumn(db: Database, table: string, column: string): boolean;

package/dist/types/db/legacy-health.d.ts

@@ -0,0 +1,2 @@
+import type { Database } from "bun:sqlite";
+export declare function assertLegacySchemaIdentity(db: Database, version: number): void;

package/dist/types/db/maintenance.d.ts

@@ -0,0 +1,21 @@
+export interface DatabaseLease {
+    databasePath: string;
+    release: () => void;
+}
+export interface MaintenanceGate {
+    databasePath: string;
+    release: () => void;
+    assertOwned: () => void;
+    retain: () => void;
+}
+export interface MaintenanceRecovery {
+    ownerID: string;
+    confirmation: "RECOVER_RETAINED_MAINTENANCE_GATE";
+}
+export declare function acquireDatabaseLease(databasePath: string): DatabaseLease;
+export declare function acquireMaintenanceGate(databasePath: string, recovery?: MaintenanceRecovery): MaintenanceGate;
+export declare function recoverStaleMaintenanceGate(databasePath: string, validate: () => void): boolean;
+export declare function assertMaintenanceGateFor(gate: MaintenanceGate, databasePath: string): void;
+export declare function canonicalDatabasePath(path: string): string;
+export declare function ensureDatabaseParent(path: string): void;
+export declare function assertNoSymbolicLinks(path: string, allowMissingLeaf?: boolean): void;

package/dist/types/db/migrations/v011.d.ts

@@ -0,0 +1,3 @@
+import type { Database } from "bun:sqlite";
+export declare function migrateV10ToV11(db: Database): void;
+export declare function assertV10SourceDatabase(db: Database): void;

package/dist/types/db/schema.d.ts

@@ -1,6 +1,15 @@
-import type { Database } from "bun:sqlite";
+import { Database } from "bun:sqlite";
+export declare const APPLICATION_ID = 1095195213;
+export declare const PRODUCT_ID: "agz-memory";
+export declare const HASH_POLICY: "hash-tuple/2";
 export declare const SCHEMA_TABLES: string;
 export declare const FTS_V9 = "\nCREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(\n  title, summary, content,\n  content='notes', content_rowid='rowid',\n  tokenize='unicode61'\n);\nCREATE TRIGGER IF NOT EXISTS notes_fts_ai AFTER INSERT ON notes BEGIN\n  INSERT INTO notes_fts(rowid, title, summary, content)\n  VALUES (new.rowid, new.title, new.summary, new.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS notes_fts_ad AFTER DELETE ON notes BEGIN\n  INSERT INTO notes_fts(notes_fts, rowid, title, summary, content)\n  VALUES ('delete', old.rowid, old.title, old.summary, old.content);\nEND;\nCREATE TRIGGER IF NOT EXISTS notes_fts_au AFTER UPDATE OF title, summary, content ON notes BEGIN\n  INSERT INTO notes_fts(notes_fts, rowid, title, summary, content)\n  VALUES ('delete', old.rowid, old.title, old.summary, old.content);\n  INSERT INTO notes_fts(rowid, title, summary, content)\n  VALUES (new.rowid, new.title, new.summary, new.content);\nEND;\n";
+export declare const SCHEMA_V11_TABLES: string;
+export declare function captureEventsTableV11(table?: "capture_events" | "capture_events_v11"): string;
+export declare function schemaFingerprint(db: Database): string;
+export declare function expectedSchemaFingerprint(): string;
+export declare function createSchemaV11(db: Database): void;
+export declare function insertV11Identity(db: Database, databaseID?: `${string}-${string}-${string}-${string}-${string}`, createdAt?: number): void;
 export declare function createSchema(db: Database): void;
 export declare function rebuildFts(db: Database): void;
 export declare function captureEventsTable(table?: "capture_events" | "capture_events_v10"): string;

package/dist/types/db.d.ts

@@ -4,3 +4,4 @@ export interface OpenedDB {
     close: () => void;
 }
 export declare function openMemoryDatabase(path: string): OpenedDB;
+export declare function openReadOnlyMemoryDatabase(path: string): OpenedDB;

package/dist/types/hash.d.ts

@@ -0,0 +1,4 @@
+export type HashTupleValue = null | string | boolean | number | Uint8Array;
+export declare function hashTuple(domain: string, version: number, fields: readonly HashTupleValue[]): string;
+export declare function noteContentHash(kind: string, title: string, summary: string, content: string): string;
+export declare const canonicalNoteHash: typeof noteContentHash;

package/dist/types/retrieval/contract.d.ts

@@ -32,11 +32,23 @@ export interface BackendHealth {
     version?: string;
     errorCode?: string;
 }
+export interface BackendOperationContext {
+    operationKey: string;
+    sequence: number;
+    fence: number;
+}
+export interface OutboxBackend extends RetrievalBackend {
+    readonly outboxProtocol: "agz-memory-outbox/1";
+    upsert(document: DerivedDocument, signal: AbortSignal, operation: BackendOperationContext): Promise<void>;
+    delete(ref: DerivedRef, signal: AbortSignal, operation: BackendOperationContext): Promise<void>;
+    purgeProject(projectID: string, signal: AbortSignal, operation: BackendOperationContext): Promise<void>;
+}
 export interface RetrievalBackend {
     id: string;
-    upsert(document: DerivedDocument, signal: AbortSignal): Promise<void>;
-    delete(ref: DerivedRef, signal: AbortSignal): Promise<void>;
-    purgeProject(projectID: string, signal: AbortSignal): Promise<void>;
+    upsert(document: DerivedDocument, signal: AbortSignal, operation?: BackendOperationContext): Promise<void>;
+    delete(ref: DerivedRef, signal: AbortSignal, operation?: BackendOperationContext): Promise<void>;
+    purgeProject(projectID: string, signal: AbortSignal, operation?: BackendOperationContext): Promise<void>;
     query(projectID: string, query: string, limit: number, signal: AbortSignal): Promise<RankedHit[]>;
     health(signal: AbortSignal): Promise<BackendHealth>;
 }
+export declare function validateBackendHits(value: unknown): value is RankedHit[];

package/dist/types/server.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import type { MemoryStore } from "./store";
 export declare const SERVER_NAME = "agz-memory";
-export declare const SERVER_VERSION: "0.4.1";
+export declare const SERVER_VERSION: "0.5.0";
 export declare function createMemoryServer(store: MemoryStore): McpServer;

package/dist/types/store/capture.d.ts

@@ -6,6 +6,7 @@ export interface ProjectBindingInput {
     workspaceID?: string;
 }
 export type CaptureMode = "shadow" | "auto-write";
+type CheckpointState = "active" | "idle" | "unavailable" | "closed";
 export interface CaptureIngestResult {
     outcome: "shadowed" | "materialized" | "duplicate" | "ignored" | "review" | "rejected" | "quarantined";
     idempotencyKey: string;
@@ -17,15 +18,18 @@ export declare class CaptureStore {
     private indexBackends;
     constructor(db: Database, indexBackends?: readonly string[]);
     bindProject(input: ProjectBindingInput): {
+        ok: true;
         bindingKey: string;
         projectID: string;
     };
-    checkpoint(sessionID: string, bindingKey: string, projectID: string, messageID?: string, state?: "active" | "idle" | "unavailable" | "closed"): void;
-    markReconciled(sessionID: string, state: "active" | "idle" | "unavailable" | "closed", lastMessageID?: string, failed?: boolean): void;
-    getCheckpoint(sessionID: string): {
+    checkpoint(sessionID: string, bindingKey: string, projectID: string, messageID?: string, state?: CheckpointState): void;
+    markReconciled(sessionID: string, state: CheckpointState, lastMessageID?: string, failed?: boolean, bindingKey?: string, projectID?: string): void;
+    markReconciled(sessionID: string, bindingKey: string, state: CheckpointState, lastMessageID?: string, failed?: boolean, projectID?: string): void;
+    markReconciled(sessionID: string, bindingKey: string, projectID: string, state: CheckpointState, lastMessageID?: string, failed?: boolean): void;
+    getCheckpoint(sessionID: string, bindingKey?: string, projectID?: string): {
         sessionID: string;
         lastMessageID?: string;
-        state: "active" | "idle" | "unavailable" | "closed";
+        state: CheckpointState;
     } | undefined;
     ingest(input: unknown, mode: CaptureMode, options?: {
         allowedKinds?: readonly string[];
@@ -48,4 +52,8 @@ export declare class CaptureStore {
     private enqueueOutbox;
     private finishEvent;
     private binding;
+    private hasBinding;
+    private checkpointRow;
+    private uniqueCheckpointForSession;
 }
+export {};

package/dist/types/store/outbox.d.ts

@@ -1,14 +1,17 @@
 import type { Database } from "bun:sqlite";
-import type { RetrievalBackend } from "../retrieval/contract";
-export type OutboxOutcome = "idle" | "succeeded" | "stale" | "quarantined" | "retry" | "dead";
+import type { OutboxBackend } from "../retrieval/contract";
+export type OutboxOutcome = "idle" | "succeeded" | "stale" | "quarantined" | "retry" | "dead" | "lost_lease";
 export declare class OutboxWorker {
     private db;
     private backends;
     private now;
     private random;
     private readonly workerID;
-    constructor(db: Database, backends: ReadonlyMap<string, RetrievalBackend>, now?: () => number, random?: () => number);
+    constructor(db: Database, backends: ReadonlyMap<string, OutboxBackend>, now?: () => number, random?: () => number);
     processNext(): Promise<OutboxOutcome>;
+    private claim;
+    private runBackend;
+    private stale;
     private succeed;
     private fail;
 }

package/dist/types/store/retrieval.d.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import type { RetrievalBackend, RetrievalRequest } from "../retrieval/contract";
+import { type RetrievalBackend, type RetrievalRequest } from "../retrieval/contract";
 import type { RecallCard } from "../types";
 export interface RetrievalResult {
     cards: RecallCard[];
@@ -14,5 +14,5 @@ export declare class RetrievalStore {
     private lexical;
     private graph;
     private graphPredicates;
-    private note;
+    private notes;
 }

package/dist/types/store.d.ts

@@ -55,11 +55,18 @@ export declare class MemoryStore {
     };
     update(projectID: string, input: UpdateInput): UpdateResult;
     pin(projectID: string, id: string, pinned: boolean): {
-        ok: boolean;
-        reason: string;
-        id?: undefined;
         projectID?: undefined;
         projectName?: undefined;
+        id?: undefined;
+        ok: boolean;
+        reason: string;
+        pinned?: undefined;
+    } | {
+        ok: boolean;
+        id: string;
+        projectID: string;
+        projectName: string;
+        reason: string;
         pinned?: undefined;
     } | {
         reason?: undefined;
@@ -88,8 +95,10 @@ export declare class MemoryStore {
     };
     recall(projectID: string, query: string, limit?: number): RecallCard[];
     private getProjectRow;
+    private getProjectByNormalizedName;
     private projectNameExists;
     private getNoteRow;
     private recordCurrentRevision;
     private enqueueOutbox;
+    private immediateTransaction;
 }

package/dist/types/types.d.ts

@@ -1,4 +1,4 @@
-export declare const SCHEMA_VERSION = 10;
+export declare const SCHEMA_VERSION = 11;
 export declare const INLINE_LIMIT = 1200;
 export declare const KINDS: readonly ["decision", "fact", "procedure", "context", "research", "preference", "task"];
 export type Kind = (typeof KINDS)[number];

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const PRODUCT_VERSION: "0.4.1";
+export declare const PRODUCT_VERSION: "0.5.0";

package/docs/adr/hash-identity-v2.md

@@ -0,0 +1,57 @@
+# ADR: Version 2 Tuple Hash Identities
+
+Status: Accepted
+
+Date: 2026-09-02
+
+## Context
+
+Schema 10 hashes several user-controlled tuples by joining strings with NUL bytes. NUL is not rejected by every producer, so two different tuples can serialize to the same byte sequence. JavaScript string length also counts UTF-16 code units rather than UTF-8 bytes, which makes an implicit character-based framing contract unsuitable for persisted identities.
+
+The affected values include canonical note hashes, derived-document hashes, OpenCode capture identities, project binding keys, and capture payload hashes. These values survive process restarts and must be deterministic on every supported platform.
+
+## Decision
+
+Schema 11 uses one exported helper:
+
+```ts
+hashTuple(domain, version, fields)
+```
+
+The encoder writes the following byte sequence into SHA-256:
+
+1. A fixed `agz-memory/hash-tuple` format marker.
+2. A length-prefixed UTF-8 domain.
+3. An unsigned version integer.
+4. A field count.
+5. For every field, a one-byte type tag, an unsigned UTF-8/byte payload length, and the payload.
+
+`null`, strings, booleans, finite numbers, and byte arrays use distinct tags. Empty strings and `null` are therefore different. String lengths are measured after UTF-8 encoding, never with JavaScript `String.length`. Numbers use a canonical finite representation and unsafe integers are rejected.
+
+Each use has a separate domain. The initial version 2 domains are:
+
+- `canonical-note`
+- `derived-note`
+- `capture-identity`
+- `capture-payload`
+- `project-binding`
+- `checkpoint-identity`
+- `outbox-operation`
+
+Schema 11 recomputes canonical and revision hashes from persisted source fields. Derived hashes are recomputed from `deriveDocument()`. Capture keys are recomputed from strict source identities; a legacy row that cannot satisfy its event-kind identity contract stops migration with a safe row identifier and error code. Different legacy rows mapping to the same version 2 key stop migration; they are never merged or ignored.
+
+The capture writer emits `agz-memory.capture/2`. The migration reader accepts `/1` only while migrating persisted schema 10 rows. Runtime ingestion accepts `/2` and independently recomputes the idempotency key before insertion.
+
+## Consequences
+
+- NUL and Unicode tuple collision counterexamples no longer collide.
+- Hashes intentionally change during the schema 10 to 11 migration.
+- Version 2 databases cannot be safely written by version 0.4.1; the existing newer-schema guard must reject them before any DDL.
+- Hashes identify content or operation tuples; they are not secret storage and do not replace redaction.
+- Migration produces an aggregate mapping audit without recording note bodies, prompts, credentials, or other private payloads.
+
+## Rejected Alternatives
+
+- Delimiter escaping was rejected because every producer would need identical escaping and type/null handling.
+- `JSON.stringify` was rejected because object/key representation and numeric edge cases are not the persisted contract we need.
+- Reusing version 1 hashes was rejected because it preserves the collision class.

package/docs/adr/maintenance-lock.md

@@ -0,0 +1,93 @@
+# ADR: Cross-Process Database Maintenance Gate
+
+Status: Accepted
+
+Date: 2026-09-02
+
+## Context
+
+SQLite WAL coordinates transactions but does not make replacing the database pathname safe while another process holds an open connection. An old connection can continue to use the replaced inode and its WAL after restore. Before schema 11, the migration lock serialized migration owners only; normal MCP and plugin handles did not participate.
+
+AGZ Memory must run on Linux, macOS, and Windows under Bun. Bun does not currently expose one portable shared/exclusive advisory-file-lock API for this package, so schema 11 uses a conservative filesystem protocol and fails closed whenever ownership cannot be established.
+
+## Decision
+
+Every normal database handle owns a lease for its complete lifetime. Migration, restore, backup publication, and prune use one exclusive maintenance gate associated with the canonical database path.
+
+### Normal Open
+
+1. Resolve and validate the canonical path and parent policy.
+2. Reject an existing maintenance gate.
+3. Publish a private lease file by exclusive staging and atomic rename. Its record contains an opaque owner ID, PID, process-start marker, hostname, and creation time. It contains no database content or configured private path.
+4. Check the maintenance gate again. If it appeared, remove only the caller's verified lease and retry or fail.
+5. Open and validate SQLite.
+6. Keep the lease until statements and the SQLite handle are closed.
+
+The second gate check closes the race where maintenance creates the gate between the first check and lease publication. Maintenance either observes the published lease, or the opener observes the gate and withdraws.
+
+### Maintenance
+
+1. Atomically create the gate. Only one owner can succeed.
+2. Validate the gate owner record after publication.
+3. Enumerate leases. A local lease is stale only when PID liveness and process-start identity prove that its owner is gone or the PID was reused. A remote-host or unverifiable lease remains active and blocks maintenance.
+4. If any active lease exists, remove only the caller's gate and return `active_database_handles`.
+5. Perform the operation without exposing a normal handle.
+6. Verify the installed canonical database before removing the gate.
+
+There is no `--force` bypass for active or unverifiable leases. Stale cleanup requires current owner identity checks. Gate and lease deletion never recursively removes an unverified replacement pathname.
+
+Migration waiters recheck the canonical schema under a normal lease while they
+still own the migration lock. A waiter that finds the target schema returns that
+handle without creating another maintenance gate. After a successful migration,
+the owner releases the maintenance gate and publishes its normal lease before
+releasing the migration lock. This handoff prevents queued stale observations
+from creating a new gate between migration completion and reopen.
+
+An active gate left by a crashed local process is reclaimed in place: an
+exclusive takeover record serializes contenders and atomically replaces the
+stale owner while the gate directory remains continuously present. A reused PID
+is stale only when both process-start markers exist and differ. Remote owners,
+live owners, unavailable markers, malformed records, and missing records remain
+fail-closed.
+
+`retain()` atomically persists `state: recovery-required` before returning. Such
+a gate is never reclaimed automatically. A verified restore may take it over
+only with the exact recorded owner ID and
+`RECOVER_RETAINED_MAINTENANCE_GATE`; the restore keeps the gate continuously
+held and validates the installed database before release.
+
+### Restore
+
+While the maintenance gate is held and no leases exist:
+
+1. Open the backup and manifest through the validated no-symlink policy.
+2. Copy the source into a private same-parent staging file while streaming SHA-256 and byte count.
+3. Validate manifest hash/size, application ID, database UUID/product, schema version/fingerprint, row counts, `integrity_check`, and `foreign_key_check` on the staging inode.
+4. Checkpoint and preserve the current canonical database.
+5. Fsync staging and its parent, atomically replace the canonical pathname, and quarantine stale WAL/SHM files.
+6. Reopen the installed target and repeat identity, fingerprint, count, and health validation.
+7. On failure, restore the preserved source while still holding the gate. If rollback cannot be verified, retain the gate as a recovery-required marker and fail closed.
+
+Backup hashing is streaming. Restore never copies a pathname that was validated and then reopened as the source of truth.
+
+## Platform Policy
+
+- The database, backup root, manifest, maintenance gate, lease registry, lock records, and their existing parents must not be symbolic links.
+- Existing components must have the expected file type and private ownership/permissions when the platform exposes those attributes.
+- New files use exclusive creation and private modes.
+- An unsupported no-follow or identity check causes the sensitive operation to fail closed rather than silently weaken the policy.
+- Process-start markers use the strongest local facility available. An unavailable marker never justifies breaking a live lease.
+
+## Consequences
+
+- Restore is offline-safe, not an online hot swap.
+- Long-lived MCP/plugin handles explicitly block maintenance until clean shutdown.
+- A crashed owner can be reclaimed only with verifiable stale-owner evidence.
+- The protocol is cooperative against same-user processes; it does not protect a database directory writable by an untrusted account. Unsafe ownership or permissions are rejected.
+
+## Rejected Alternatives
+
+- WAL checkpoint alone was rejected because it does not invalidate old file descriptors.
+- PID-only lock files were rejected because PIDs are reused.
+- Unconditional stale timeout and `--force` were rejected because a paused live writer could lose acknowledged writes.
+- Path-only verify-then-copy was rejected because it leaves a TOCTOU window.

package/docs/backup-restore-runbook.md

@@ -2,7 +2,7 @@
 
 English | [Türkçe](backup-restore-runbook.tr.md)
 
-This runbook applies to `@vaur94/agz-memory@0.4.1` and SQLite schema v10.
+This runbook applies to `@vaur94/agz-memory@0.5.0` and SQLite schema v11.
 
 ## Preconditions
 
@@ -25,20 +25,20 @@ Do not proceed with a guessed or empty path.
 Run a read-only health report first:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin doctor
 ```
 
 `ok` must be `true`. Record `schemaVersion`, row counts, and invariant counts.
 Then create a standalone verified backup and upgrade:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin upgrade --to 10
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin upgrade --to 11
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin doctor
 ```
 
 The upgrade itself creates another verified pre-migration backup when the
-database schema is older than v10. Preserve each printed manifest path and
+database schema is older than v11. Preserve each printed manifest path and
 SHA-256. Do not start a writer if the final report has `ok: false`.
 
 ## Verify A Backup
@@ -54,16 +54,16 @@ The manifest format is `agz-memory-backup/1`. `agz-memory-admin restore` verifie
 that the manifest and database are regular files in the same backup directory,
 then checks size, SHA-256, SQLite integrity, foreign keys, and row counts.
 
-Final `0.4.1` does not accept prerelease manifest formats. Use the originating
+Final `0.5.0` does not accept prerelease manifest formats. Use the originating
 prerelease to restore such a backup, run its doctor check, and only then upgrade
-that restored database with `0.4.1`.
+that restored database with `0.5.0`.
 
 ## Restore Rehearsal
 
 Keep all writers stopped. First request a dry run by omitting confirmation:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json"
 ```
 
@@ -71,7 +71,7 @@ Compare `targetPath`, `sourceSchema`, `targetSchema`, row counts, size, and
 SHA-256 with the recorded backup. Then use the exact manifest hash:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json" \
   --sha256 <manifest-database-sha256> \
   --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP
@@ -84,9 +84,9 @@ database passes all checks.
 ## Post-Restore Validation
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin outbox status
 ```
 
 Start only the MCP server and perform read-only `project_list`, `memory_recall`,
@@ -94,6 +94,26 @@ and `memory_read` smoke calls. Compare project/note counts with the manifest.
 Only after those checks pass should OpenCode be restarted. Keep the plugin in
 `off` until a separate rollout decision is made.
 
+## Retained Maintenance Gate
+
+`<database>.maintenance/owner.json` with `state: recovery-required` means a
+previous restore could not verify its rollback. It is never removed
+automatically. Stop every MCP/plugin process, preserve the database, sidecars,
+gate, and restore artifacts, then select a verified backup. Supply the exact
+recorded owner ID only on the restoring command:
+
+```sh
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin restore <manifest> \
+  --sha256 <manifest-sha256> \
+  --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP \
+  --maintenance-owner <owner-id> \
+  --maintenance-confirm RECOVER_RETAINED_MAINTENANCE_GATE
+```
+
+Remote, live, malformed, or otherwise unverifiable owners remain blocked. Never
+delete the gate manually; the recovery restore atomically takes ownership while
+the gate directory remains present.
+
 ## Stale Migration Lock
 
 The lock is `<database>.migration.lock/owner.json`. Never remove it while the
@@ -104,7 +124,7 @@ style error first if uncertain. Break only a proven stale lock with the exact
 owner ID and confirmation:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin unlock \
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin unlock \
   --owner <owner-id> \
   --confirm BREAK_STALE_MIGRATION_LOCK
 ```
@@ -118,13 +138,13 @@ The first command is non-destructive and returns a digest over the exact backup
 set:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin backup prune
 ```
 
 Review every listed manifest/database pair. Delete only that unchanged set:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune \
+bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin backup prune \
   --digest <dry-run-digest> \
   --confirm DELETE_VERIFIED_BACKUPS
 ```