@josephyoung/pi-openviking 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Young
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# pi-openviking
+
+An independent OpenViking memory extension for pi, tracked by
+[Dano #465](https://github.com/zhengchengqiaobusiness-arch/Dano/issues/465).
+
+**Implementation in progress. No package release or production activation yet.**
+The package name is `@josephyoung/pi-openviking`. Both entry modules compile
+against pi 0.85.1. The real pi loader loads both entries and keeps a single
+registration after reload; the standard entry fails closed without its launcher binding.
+The Linux CLI now runs through the public pi entry; memory-enabled CLI acceptance and product integration continue under [#474](https://github.com/zhengchengqiaobusiness-arch/Dano/issues/474).
+
+## Implemented
+
+- A Linux native-tool IPC worker with distinct UID, irreversible `no_new_privs`, explicit environment
+  allowlist, kernel identity checks, bounded requests/results, streamed updates
+  and cancellation. All seven native definitions and interactive `!`/`!!` shell
+  operations have worker proxies; the standard entry registers these proxies
+  with the memory extension. The protected CLI bootstraps and binds the worker.
+- Immutable account/user binding and owner-checked private state files. Before
+  first data access, the authenticated health response must confirm the expected
+  account, user and USER role; an HTTP 200 with missing identity is insufficient.
+- OS advisory locks, atomic replacement, file and directory fsync. The state
+  contains delivery/consent metadata and pending payloads, not a second memory
+  database. Kernel locks are released when a writer dies; no lease timeout can
+  grant a second process permission to repeat a remote mutation.
+- Standard and host factory entry modules; the host never reads global credentials.
+- Bounded, quoted recall in a non-persisted custom context message, with a host
+  tokenizer, per-request cache and pause/lifecycle invalidation.
+- Default-off consent, explicit durable enqueue and stable source deduplication.
+- A dedicated remote Session per save operation, with persisted causal phases.
+  An unknown message/commit outcome is reconciled through public APIs and never
+  blindly retransmitted. Missing or expired receipts require reconciliation;
+  they do not authorize repeating a non-idempotent call.
+- Owner-level background scheduling with durable backoff, startup recovery,
+  bounded processing and shutdown. Exhausted reconciliation stays visibly blocked;
+  it never turns an unknown remote outcome into an automatic resend.
+- Protected resource-loader configuration rejects workspace packages/extensions
+  while preserving explicitly supplied trusted Skills. Apply before package
+  resolution; `noExtensions` alone is insufficient.
+- `ready` requires a completed matching task, an archive containing the source,
+  a matching memory diff, current content and a successful retrieval probe.
+- Pause suppresses unsent operations and removes their pending bodies. Enabling
+  again does not replay those operations or authorize automatic collection.
+
+## Development
+
+Requires Node.js >=22.19, a POSIX system, Python and a C++ compiler for the
+`fs-ext` native advisory-lock binding. Install scripts for that audited native
+module must run when installing. This first local run used Node 26.8.2; the
+release gate must also test the selected Linux/Node deployment combination.
+
+```sh
+npm ci
+npm test
+npm run check
+```
+
+`npm test` covers independent processes, killed writers, concurrent processors,
+response loss, source conflicts, owner mismatch, consent, recall budgets and
+lifecycle behavior (38 tests in the current development run). It does not prove
+end-to-end host isolation or UI acceptance.
+
+For a separately provisioned disposable `extension-test-*` account, place an
+owner-only JSON file outside the repository with `owner: {accountId, userId}`,
+`baseUrl` (server origin) and a USER-level `apiKey`, then run:
+
+```sh
+npm run build
+node scripts/real-service.mjs /absolute/private/test-run/connection.json
+```
+
+This invokes the configured server's extraction models and may incur charges.
+The script rejects non-test account names, leaves synthetic data for inspection
+and writes a credential-free result alongside the protected connection file.
+Do not commit connection files, state, credentials or real user data.
+
+## Security and release boundaries
+
+State permissions alone do not protect credentials from same-UID Agent tools.
+The selected memory-enabled profile requires a trusted Linux host and a
+separate tool UID, protected installation/state and no executable discovery
+from tool-writable paths. That launcher must be integrated and verified before
+activating memory in either pi or Dano. Current modules are not a substitute
+for that boundary.
+
+Further #474 gates: memory-enabled CLI acceptance and Dano worker lifecycle integration,
+credential isolation, Dano exact-version integration, authenticated settings
+and management, ordinary pi and real in-app Browser acceptance. Subsequent
+#475–477 work covers full collection/lifecycle/governance and release gates.
+
+## Verified service combination
+
+- OpenViking server: unmodified 0.4.20.
+- OpenViking TypeScript SDK: 0.1.0, exact dependency.
+- pi: 0.85.1, exact peer dependency (not bundled).
+- Local actual-adapter save: 2026-09-18, synthetic fact reached `ready` and was
+  recalled after ~22.8 seconds. Every delivery step recreated the adapter from
+  persisted state. This is one functional run, not the PRD performance sample.
+
+See `THIRD_PARTY_NOTICES.md` for distribution responsibilities.
+
+## Executed worker boundary
+
+`scripts/linux-worker.mjs` exercises the actual worker in a disposable root
+Linux container, with the three numeric identities supplied as arguments. The
+2026-09-18 run used pi 0.82.1 and Node 22.23.2: workspace read/write succeeded;
+absolute and symlink read/write/edit against the host-private credential failed;
+Bash inherited no synthetic memory key; updates and cancellation worked. The
+container used no network and was removed after the run. This verifies the
+worker primitive, not the final CLI/Dano launch and resource-discovery profile.
+
+The actual background scheduler also completed a fresh real-service save on
+2026-09-18: it reached `ready` after 30.3 seconds and the subsequent query
+retrieved the synthetic preference. No viewer or foreground delivery calls
+advanced the operation. Reproduce with `scripts/real-scheduler.mjs` and a fresh
+disposable account config, using the same private-config rules above.
+
+The standard entry exposes `/memory enable` (interactive confirmation),
+`/memory pause`, `/memory status`, and `/memory show <operation-id>`. Its enable
+gate checks the exact worker used by its native tools. Automatic collection
+remains unapproved. Read-only saved-content and credential-owner checks against
+the actual service are reproducible with `scripts/real-read.mjs`.
+
+The Linux worker integration now exercises the registered tool proxies and
+interactive shell, preserving streaming and exit codes. Both cancellation
+paths are checked for absence of a delayed file write, rather than only testing
+that the caller receives a cancellation error.
+
+## Protected bootstrap primitive
+
+`bootstrapProtectedWorker` validates canonical workspace, private agent/state
+roots and a protected installation tree before starting the worker and dropping
+bootstrap UID/GID. It rejects workspace overlap, replaceable ancestors,
+worker-writable code, and installation symlinks escaping the installation root.
+Private directories must already belong to the configured host UID with no
+group/other permissions. Provisioning is explicit; this function never widens
+permissions or repairs arbitrary paths.
+
+The worker uses a configured absolute util-linux `setpriv` path to set
+`no_new_privs` before Node executes. Kernel `NoNewPrivs: 1` is checked alongside
+UID identity. The complete bootstrap primitive passed the real Linux worker
+fixture, including its tool/interactive-shell and cancellation checks. This
+does not by itself establish the multi-user Dano worker lifecycle.
+
+## Protected pi CLI
+
+`pi-openviking /etc/pi-openviking/profile.json [pi chat arguments]` starts the
+Linux worker, drops host privileges, loads a trusted host module and calls pi's
+public `main` entry with the standard extension factory. The profile and its
+ancestors must be root-owned and not group/other-writable. It contains bootstrap
+paths/IDs/limits, `hostModule`, `shutdownTimeoutMs` and optional
+`trustedSkillPaths`; it must contain no provider credentials. See the exported
+`LauncherProfile` type for required fields.
+
+The installed host module exports `createHost({ paths, assertToolIsolation })`
+and returns `{ memory, scheduler }`. It reads keys from the host-private root
+and supplies the selected model's exact tokenizer. It runs after privilege
+drop. Its source and approved Skill paths must be inside the protected
+installation. The CLI fixes private session storage and denies executable
+resource/trust overrides and package/config administration commands.
+
+Print mode closes its scheduler/worker on return. Interactive pi emits its own
+shutdown hooks and exits; worker IPC disconnect terminates outstanding tool
+work. Delivery does not depend on an exit flush: the durable queue recovers on
+the next launch. A container supervisor must terminate the entire process tree
+on abrupt host termination.
+
+The 2026-09-18 Linux run used the real configured model through pi 0.82.1:
+Bash wrote `cli-proof.txt`, read returned its content, and the file belonged to
+the separate worker UID. Workspace extension discovery was denied and the CLI
+exited normally. `scripts/linux-cli.mjs` reproduces this in a disposable root
+container; its `cli-test-host.mjs` deliberately leaves memory disabled and does
+not substitute for memory-enabled acceptance. Model credentials are copied to
+a private agent directory. Extra CA certificates must remain readable after
+host privilege drop; TLS verification stays enabled.
+
+## Release candidate validation
+
+The standard CLI RPC path has now passed explicit enable confirmation, real
+OpenViking save to `ready`, content/source inspection, new-session recall and
+pause. Automatic collection remains separately unapproved. This passed first
+on pi 0.82.1 and again with a fresh account on pi 0.85.1. See
+[the acceptance record](docs/acceptance-2026-09-18.md). Interactive TUI screenshots
+and Dano's real in-app Browser gate remain outstanding.
+
+The exact peer moved to pi 0.85.1 because pi 0.82.1's bundled shrinkwrap kept
+vulnerable transitive dependencies despite root overrides. The 0.85.1 install
+resolves undici 8.9.0 and brace-expansion 5.0.9; `npm audit` currently reports
+zero vulnerabilities. The package includes the Apache-2.0 license text needed
+for the unmodified OpenViking SDK.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-party distribution review
+
+This repository's adapter code is original MIT-licensed code. It does not copy
+OpenViking server or example implementation code.
+
+- `@openviking/sdk@0.1.0` declares Apache-2.0. Its upstream npm tarball omits a
+  standalone LICENSE. The complete Apache-2.0 text is shipped in `licenses/Apache-2.0.txt`.
+  Upstream: https://github.com/volcengine/OpenViking/tree/b54001e2e5c974ffd7a09ba543813fa104a99561/sdk/typescript.
+  The dependency is unmodified; its published tarball contains no separate
+  NOTICE or copyright attribution file. Its package metadata and original
+  source notices remain in the dependency. Review the final image dependency
+  tree separately; this notice does not relabel the server license.
+- `fs-ext@2.1.1` declares MIT. Preserve its license and the notices of native
+  build dependencies when distributing them.
+- pi 0.85.1 is an MIT peer dependency. The extension must not bundle a second
+  kernel. Images distributing pi must retain its applicable license/notices.
+- OpenViking server 0.4.20 is a separate AGPL-3.0 service, not part of this
+  extension artifact. Server-image delivery must include applicable license,
+  notices and exact corresponding source/build/install materials. Reassess
+  obligations if the server is modified. HTTP separation is not a blanket
+  exemption from license obligations.
+
+The release candidate uses pi 0.85.1 after the initial pi 0.82.1 combination
+reported undici and brace-expansion vulnerabilities. Root overrides did not
+replace the old package's bundled shrinkwrap. The current exact peer resolves
+undici 8.9.0 and brace-expansion 5.0.9 and passes `npm audit` with zero findings
+on 2026-09-18. Re-audit the final host image and later releases separately.

package/dist/bootstrap.d.ts

@@ -0,0 +1,20 @@
+import { NativeToolWorker, type WorkerOptions } from './tool-worker.js';
+export interface ProtectedPaths {
+    workspace: string;
+    agentDir: string;
+    stateDir: string;
+    installationDir: string;
+    hostUid: number;
+    workerUid: number;
+    workerGid: number;
+}
+/** Canonical paths returned here must be used throughout the subsequent bootstrap. */
+export declare function validateProtectedPaths(options: ProtectedPaths): Promise<ProtectedPaths>;
+/** Single-host CLI bootstrap. Multi-user hosts must provision each worker explicitly. */
+export declare function bootstrapProtectedWorker(options: ProtectedPaths & Omit<WorkerOptions, 'workspace' | 'hostUid' | 'workerUid' | 'workerGid'> & {
+    hostGid: number;
+}): Promise<{
+    worker: NativeToolWorker;
+    paths: ProtectedPaths;
+    piPackageContext: string;
+}>;

package/dist/bootstrap.js

@@ -0,0 +1,117 @@
+import { lstat, realpath, readdir } from 'node:fs/promises';
+import { dirname, relative, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { NativeToolWorker } from './tool-worker.js';
+function contains(parent, child) {
+    const path = relative(parent, child);
+    return path === '' || (!path.startsWith('../') && path !== '..' && !isAbsolute(path));
+}
+function permissions(stat, options) {
+    if (stat.uid === options.workerUid)
+        return (stat.mode >> 6) & 7;
+    if (stat.gid === options.workerGid)
+        return (stat.mode >> 3) & 7;
+    return stat.mode & 7;
+}
+async function protectedAncestors(path, options, readable) {
+    let current = path;
+    let child;
+    for (;;) {
+        const stat = await lstat(current);
+        const access = permissions(stat, options);
+        // A sticky shared ancestor may be writable, but the worker must own neither
+        // it nor the protected child entry. Without sticky semantics, replacement
+        // remains possible even when the protected child itself is read-only.
+        const stickyProtection = child && (stat.mode & 0o1000) && stat.uid !== options.workerUid && child.uid !== options.workerUid;
+        if (stat.uid === options.workerUid || ((access & 2) && !stickyProtection))
+            throw new Error('WORKER_CAN_REPLACE_PROTECTED_PATH');
+        if (readable && (!(access & 1) || (current === path && !(access & 4))))
+            throw new Error('WORKER_CANNOT_LOAD_INSTALLATION');
+        const parent = dirname(current);
+        if (parent === current)
+            return;
+        child = stat;
+        current = parent;
+    }
+}
+async function verifyInstallationTree(root, options) {
+    const visited = new Set();
+    const pending = [root];
+    while (pending.length) {
+        const path = await realpath(pending.pop());
+        if (!contains(root, path))
+            throw new Error('INSTALLATION_LINK_ESCAPES_ROOT');
+        if (visited.has(path))
+            continue;
+        visited.add(path);
+        const stat = await lstat(path);
+        const access = permissions(stat, options);
+        if (stat.uid === options.workerUid || (access & 2))
+            throw new Error('WORKER_CAN_REPLACE_PROTECTED_PATH');
+        if (stat.isDirectory()) {
+            for (const entry of await readdir(path))
+                pending.push(`${path}/${entry}`);
+        }
+        else if (!stat.isFile())
+            throw new Error('UNSUPPORTED_INSTALLATION_ENTRY');
+    }
+}
+/** Canonical paths returned here must be used throughout the subsequent bootstrap. */
+export async function validateProtectedPaths(options) {
+    if (![options.hostUid, options.workerUid, options.workerGid].every(id => Number.isSafeInteger(id) && id > 0)
+        || options.hostUid === options.workerUid)
+        throw new Error('INVALID_MEMORY_IDENTITIES');
+    const keys = ['workspace', 'agentDir', 'stateDir', 'installationDir'];
+    const paths = { ...options };
+    for (const key of keys) {
+        if (!isAbsolute(paths[key]))
+            throw new Error('MEMORY_PATH_MUST_BE_ABSOLUTE');
+        paths[key] = await realpath(paths[key]);
+        if (!(await lstat(paths[key])).isDirectory())
+            throw new Error('MEMORY_PATH_NOT_DIRECTORY');
+    }
+    for (const key of ['agentDir', 'stateDir', 'installationDir']) {
+        if (contains(paths.workspace, paths[key]) || contains(paths[key], paths.workspace))
+            throw new Error('MEMORY_WORKSPACE_OVERLAP');
+        await protectedAncestors(paths[key], paths, key === 'installationDir');
+    }
+    for (const key of ['agentDir', 'stateDir']) {
+        if (contains(paths.installationDir, paths[key]) || contains(paths[key], paths.installationDir))
+            throw new Error('MEMORY_INSTALLATION_STATE_OVERLAP');
+        const stat = await lstat(paths[key]);
+        if (stat.uid !== paths.hostUid || (stat.mode & 0o077) !== 0)
+            throw new Error('MEMORY_PRIVATE_DIRECTORY_REQUIRED');
+    }
+    if ((permissions(await lstat(paths.workspace), paths) & 7) !== 7)
+        throw new Error('WORKER_CANNOT_USE_WORKSPACE');
+    await verifyInstallationTree(paths.installationDir, paths);
+    return paths;
+}
+/** Single-host CLI bootstrap. Multi-user hosts must provision each worker explicitly. */
+export async function bootstrapProtectedWorker(options) {
+    if (process.platform !== 'linux' || process.getuid?.() !== 0
+        || !Number.isSafeInteger(options.hostGid) || options.hostGid <= 0)
+        throw new Error('PRIVILEGED_LINUX_BOOTSTRAP_REQUIRED');
+    const paths = await validateProtectedPaths(options);
+    const extensionEntry = await realpath(fileURLToPath(import.meta.url));
+    if (!contains(paths.installationDir, extensionEntry))
+        throw new Error('EXTENSION_OUTSIDE_PROTECTED_INSTALLATION');
+    const piPackageContext = await realpath(options.piPackageContext);
+    if (!contains(paths.installationDir, piPackageContext) || !(await lstat(piPackageContext)).isFile()) {
+        throw new Error('PI_CONTEXT_OUTSIDE_PROTECTED_INSTALLATION');
+    }
+    const privilegeGuard = await realpath(options.privilegeGuard);
+    await protectedAncestors(privilegeGuard, paths, true);
+    await protectedAncestors(await realpath(process.execPath), paths, true);
+    const worker = new NativeToolWorker({ ...options, ...paths, piPackageContext, privilegeGuard });
+    try {
+        process.setgid(options.hostGid);
+        process.setuid(paths.hostUid);
+        await worker.assertIsolated();
+        return { worker, paths, piPackageContext };
+    }
+    catch (error) {
+        worker.close();
+        throw error;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute } from 'node:path';
+import { runProtectedPi } from './launcher.js';
+try {
+    const [profilePath, ...args] = process.argv.slice(2);
+    if (!profilePath || !isAbsolute(profilePath))
+        throw new Error('ABSOLUTE_LAUNCH_PROFILE_REQUIRED');
+    const canonical = await realpath(profilePath);
+    // The bootstrap profile is administrator-owned data. Validate the whole path
+    // before parsing it; it must not be replaceable from an untrusted workspace.
+    for (let current = canonical;; current = dirname(current)) {
+        const stat = await lstat(current);
+        if (stat.uid !== 0 || (stat.mode & 0o022) !== 0)
+            throw new Error('ADMIN_OWNED_LAUNCH_PROFILE_REQUIRED');
+        if (current === canonical && !stat.isFile())
+            throw new Error('INVALID_LAUNCH_PROFILE');
+        if (dirname(current) === current)
+            break;
+    }
+    const profile = JSON.parse(await readFile(canonical, 'utf8'));
+    await runProtectedPi(profile, args);
+}
+catch {
+    // Configuration and provider failures can contain keys or endpoints.
+    console.error('Protected pi startup failed. Check the administrator-owned launch profile and private host configuration.');
+    process.exitCode = 1;
+}

package/dist/delivery.d.ts

@@ -0,0 +1,44 @@
+import { type Operation, type Owner, type Source, type StateStore } from './types.js';
+/** Each method is owner-bound. Reconciliation never mutates the service. */
+export interface DeliveryTransport {
+    readonly owner: Owner;
+    createSession(id: string): Promise<void>;
+    sessionExists(id: string): Promise<boolean>;
+    append(operation: Readonly<Operation>): Promise<void>;
+    hasSource(operation: Readonly<Operation>): Promise<boolean>;
+    commit(id: string): Promise<{
+        taskId: string;
+        archiveId?: string;
+    }>;
+    findCommit(id: string): Promise<{
+        taskId: string;
+        archiveId?: string;
+    } | null>;
+    inspect(operation: Readonly<Operation>): Promise<{
+        status: 'processing';
+    } | {
+        status: 'failed';
+        code: string;
+    } | {
+        status: 'ready';
+        archiveId: string;
+        memoryUris: string[];
+    }>;
+}
+export declare class MemoryDelivery {
+    #private;
+    constructor(options: {
+        store: StateStore;
+        transport: DeliveryTransport;
+        maxPayloadBytes: number;
+    });
+    get owner(): Owner;
+    enable(policyVersion: string): Promise<void>;
+    pause(): Promise<void>;
+    save(source: Source, content: string, scope?: string | null): Promise<Operation | {
+        phase: 'blocked';
+        errorCode: string;
+    }>;
+    /** Advances at most one remote mutation. The caller owns scheduling/lifetime. */
+    advance(id: string): Promise<void>;
+}

package/dist/delivery.js

@@ -0,0 +1,167 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { checkedOwner, sameOwner } from './types.js';
+const terminal = new Set(['ready', 'failed', 'blocked_by_pause', 'blocked']);
+const unsent = new Set(['queued', 'session_created', 'message_delivered']);
+export class MemoryDelivery {
+    #store;
+    #transport;
+    #maxPayloadBytes;
+    constructor(options) {
+        checkedOwner(options.store.owner);
+        if (!sameOwner(options.store.owner, options.transport.owner))
+            throw new Error('MEMORY_OWNER_MISMATCH');
+        if (!Number.isSafeInteger(options.maxPayloadBytes) || options.maxPayloadBytes <= 0)
+            throw new Error('INVALID_MEMORY_LIMIT');
+        this.#store = options.store;
+        this.#transport = options.transport;
+        this.#maxPayloadBytes = options.maxPayloadBytes;
+    }
+    get owner() { return this.#store.owner; }
+    async enable(policyVersion) {
+        if (!policyVersion)
+            throw new Error('MISSING_POLICY_VERSION');
+        await this.#store.transact(state => {
+            state.authorization = { enabled: true, automaticCollection: false,
+                epoch: state.authorization.epoch + 1, effectiveAt: new Date().toISOString(), policyVersion };
+        });
+    }
+    async pause() {
+        await this.#store.transact(state => {
+            state.authorization.enabled = false;
+            state.authorization.epoch++;
+            state.authorization.effectiveAt = new Date().toISOString();
+            for (const operation of Object.values(state.operations)) {
+                if (unsent.has(operation.phase)) {
+                    operation.phase = 'blocked_by_pause';
+                    delete operation.payload;
+                    operation.updatedAt = new Date().toISOString();
+                }
+            }
+        });
+    }
+    async save(source, content, scope = null) {
+        if (typeof content !== 'string' || !content.trim() || Buffer.byteLength(content) > this.#maxPayloadBytes
+            || !source || ![source.sessionId, source.entryId, source.branchId, source.contentVersion].every(x => typeof x === 'string' && x.length > 0)) {
+            throw new Error('INVALID_MEMORY_SOURCE');
+        }
+        // Scope is supplied by the host, never copied from model input.
+        if (scope !== null && !/^[A-Za-z0-9_-]{1,128}$/.test(scope))
+            throw new Error('INVALID_MEMORY_SCOPE');
+        return this.#store.transact(state => {
+            if (!state.authorization.enabled)
+                return { phase: 'blocked', errorCode: 'MEMORY_DISABLED' };
+            const id = createHash('sha256').update(JSON.stringify([
+                state.owner, scope, source, state.authorization.epoch,
+            ])).digest('hex');
+            const previous = state.operations[id];
+            if (previous) {
+                if (previous.payload !== undefined && previous.payload !== content)
+                    throw new Error('MEMORY_SOURCE_CONFLICT');
+                return structuredClone(previous);
+            }
+            const now = new Date().toISOString();
+            const operation = {
+                id, owner: state.owner, source: { ...source }, scope, kind: 'explicit',
+                authorizationEpoch: state.authorization.epoch, createdAt: now, updatedAt: now,
+                phase: 'queued', remoteSessionId: randomUUID(), payload: content,
+            };
+            state.operations[id] = operation;
+            return structuredClone(operation);
+        });
+    }
+    /** Advances at most one remote mutation. The caller owns scheduling/lifetime. */
+    async advance(id) {
+        if (!/^[a-f0-9]{64}$/.test(id))
+            throw new Error('INVALID_MEMORY_OPERATION');
+        const operation = await this.#store.transact(state => {
+            const current = state.operations[id];
+            if (!current || terminal.has(current.phase))
+                return null;
+            if (unsent.has(current.phase) && (!state.authorization.enabled
+                || current.authorizationEpoch !== state.authorization.epoch)) {
+                current.phase = 'blocked_by_pause';
+                delete current.payload;
+                return null;
+            }
+            const snapshot = structuredClone(current);
+            if (current.phase === 'queued')
+                current.phase = 'session_unknown';
+            if (current.phase === 'session_created')
+                current.phase = 'message_unknown';
+            if (current.phase === 'message_delivered')
+                current.phase = 'commit_unknown';
+            current.updatedAt = new Date().toISOString();
+            return snapshot;
+        });
+        if (!operation)
+            return;
+        try {
+            switch (operation.phase) {
+                case 'queued':
+                    await this.#transport.createSession(operation.remoteSessionId);
+                    await this.#transition(id, 'session_unknown', { phase: 'session_created' });
+                    break;
+                case 'session_unknown':
+                    if (await this.#transport.sessionExists(operation.remoteSessionId)) {
+                        await this.#transition(id, 'session_unknown', { phase: 'session_created' });
+                    }
+                    break;
+                case 'session_created':
+                    await this.#transport.append(operation);
+                    await this.#transition(id, 'message_unknown', { phase: 'message_delivered' });
+                    break;
+                case 'message_unknown':
+                    if (await this.#transport.hasSource(operation)) {
+                        await this.#transition(id, 'message_unknown', { phase: 'message_delivered' });
+                    }
+                    break;
+                case 'message_delivered': {
+                    const receipt = await this.#transport.commit(operation.remoteSessionId);
+                    await this.#transition(id, 'commit_unknown', { phase: 'processing', ...receipt });
+                    break;
+                }
+                case 'commit_unknown': {
+                    const receipt = await this.#transport.findCommit(operation.remoteSessionId);
+                    if (receipt)
+                        await this.#transition(id, 'commit_unknown', { phase: 'processing', ...receipt });
+                    break;
+                }
+                case 'processing': {
+                    const result = await this.#transport.inspect(operation);
+                    if (result.status === 'failed') {
+                        await this.#transition(id, 'processing', { phase: 'failed', errorCode: result.code });
+                    }
+                    else if (result.status === 'ready') {
+                        if (!result.memoryUris.length)
+                            throw new Error('MEMORY_NOT_RETRIEVABLE');
+                        await this.#transition(id, 'processing', { phase: 'ready', archiveId: result.archiveId, memoryUris: result.memoryUris });
+                    }
+                    break;
+                }
+            }
+        }
+        catch {
+            // The persisted unknown phase survives transport errors. Neither an
+            // exception nor an absent receipt authorizes replay of a mutation.
+            await this.#store.transact(state => {
+                const current = state.operations[id];
+                if (current && !terminal.has(current.phase))
+                    current.errorCode = 'MEMORY_RECONCILIATION_REQUIRED';
+            });
+        }
+    }
+    async #transition(id, expected, patch) {
+        await this.#store.transact(state => {
+            const current = state.operations[id];
+            if (current?.phase !== expected)
+                return;
+            Object.assign(current, patch, { updatedAt: new Date().toISOString() });
+            if (!patch.errorCode)
+                delete current.errorCode;
+            current.deliveryAttempts = 0;
+            current.nextAttemptAt = 0;
+            if (terminal.has(current.phase))
+                delete current.payload;
+        });
+    }
+}

package/dist/host.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+import { type DeliveryTransport } from './delivery.js';
+import type { RecalledMemory } from './openviking-client.js';
+import { type Owner, type StateStore } from './types.js';
+export { protectedMemoryResources } from './resource-profile.js';
+export { FileStateStore } from './state-store.js';
+export { DeliveryScheduler } from './scheduler.js';
+export { MemoryDelivery } from './delivery.js';
+export { OwnerMemoryClient } from './openviking-client.js';
+export type { Owner, Source, Operation, StateStore } from './types.js';
+export interface MemoryExtensionOptions {
+    owner: Owner;
+    client: DeliveryTransport & {
+        readMemory?(uri: string): Promise<string>;
+        recall(query: string, limit: number, signal?: AbortSignal): Promise<RecalledMemory[]>;
+    };
+    stateStore: StateStore;
+    scope?: string | null;
+    /** Host implementation must verify the live isolated worker, not a config flag. */
+    assertToolIsolation(): Promise<void>;
+    policy: {
+        maxPayloadBytes: number;
+        recallTimeoutMs: number;
+        recallTokenBudget: number;
+        recallLimit: number;
+        minimumScore: number;
+        /** Exact tokenizer for the active model, supplied by the trusted host. */
+        countTokens(text: string): number;
+    };
+    /** Wake the owner-level bounded scheduler; does not perform a foreground flush. */
+    wakeDelivery(): void;
+}
+export declare function createOpenVikingExtension(options: MemoryExtensionOptions): ExtensionFactory;