@pellux/goodvibes-sdk 1.0.0 → 1.2.0

package/dist/platform/runtime/fleet/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/fleet/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/fleet/types.ts"],"names":[],"mappings":"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"}

package/dist/platform/runtime/memory-spine/client.d.ts

@@ -0,0 +1,240 @@
+/**
+ * client.ts — the SDK memory-spine surface client (host-vs-client access mode).
+ *
+ * The daemon-owned memory service makes the daemon the SINGLE WRITER of its
+ * canonical sql.js store. sql.js has no row locking and rewrites the whole file on
+ * every save(), so two live processes writing the same file clobber each other —
+ * a whole-file lost update that would DELETE memory. One process must own the
+ * store; every other surface reaches it over the wire.
+ *
+ * This client is the surface-side switch that realizes that invariant, mirroring
+ * the session-spine host-vs-client pattern:
+ *
+ *  - HOST / OFFLINE-EMBEDDED mode (transport NOT attached): the surface IS the only
+ *    process touching its own store file, so it reads/writes the LOCAL embedded
+ *    store directly. This is the offline fallback the agent and TUI keep — a daemon
+ *    is not required for them to work.
+ *  - CLIENT-OF-ADOPTED-DAEMON mode (transport attached): the daemon owns the store;
+ *    the surface routes EVERY memory op through the injected wire transport and
+ *    NEVER opens the file. Enforced structurally here — the active branch only ever
+ *    touches `this.transport`, never `this.local`.
+ *
+ * FULL DETACH (SDK 1.2.0). The 1.1.0 wire family covered five verbs (add,
+ * honestSearch, get, updateReview, delete). That was enough for a surface to store
+ * and recall a fact over the wire, but NOT enough to fully detach every consumer
+ * from the store file: the agent's `list`/`update`/semantic-search paths and the
+ * TUI's `/recall` browse/link/queue/export paths still fell back to a local file.
+ * This client now exposes the FULL read/write catalog those consumers need
+ * (see MemoryExtendedAccess), so a wire client never opens the file for ANY of them.
+ *
+ * ONE-WRITER ENFORCEMENT RULING. The platform's convention (see canonical-memory.ts
+ * and the session spine) is honest sequential/owned access plus stated posture, NOT
+ * an OS advisory lock — sql.js exposes no lock and a cross-process flock would be a
+ * new, unenforceable-on-every-OS mechanism the rest of the store does not rely on.
+ * So the invariant is enforced two ways, both honest: (1) mode exclusivity — a
+ * client in wire mode provably cannot reach the local file because the code routes
+ * exclusively to the transport; (2) a documented single-writer contract for the
+ * embedded case — the daemon host and an offline surface are each the sole process
+ * for their own file. `mode()` reports the current posture so a surface can surface
+ * it rather than guess.
+ *
+ * HONEST FAILURE. Unlike the fire-and-forget session mirror, memory reads/writes
+ * return data, so this client is request/response. In client mode a transport
+ * failure is SURFACED to the caller (the promise rejects); it is deliberately NOT
+ * silently served from the local store — a wire client must not open the
+ * daemon-owned file, and returning a divergent local copy as if it were canonical
+ * would be the exact dishonest-recall failure this whole design exists to prevent.
+ * A sustained daemon loss is handled by `deactivate()`, which returns the surface
+ * to owned-local mode explicitly.
+ *
+ * VERSION TOLERANCE. The five CORE verbs are required of every transport. The
+ * EXTENDED verbs are OPTIONAL on the transport (`MemoryTransport`) so a surface
+ * pinned to an older SDK/daemon pair that predates a verb still satisfies the type.
+ * When a client in wire mode calls an extended verb its adopted daemon does not
+ * implement, the call REJECTS with a stated reason — it never silently reaches into
+ * the local file, which would break the one-writer invariant and lie about which
+ * store answered.
+ */
+import { logger } from '../../utils/logger.js';
+import type { MemoryAddOptions, MemoryBundle, MemoryDoctorReport, MemoryImportResult, MemoryLink, MemoryRecord, MemoryReviewPatch, MemoryScope, MemorySearchFilter, MemorySemanticSearchResult } from '../../state/memory-store.js';
+import type { MemoryVectorStats } from '../../state/memory-vector-store.js';
+import type { HonestMemorySearchOptions, HonestMemorySearchResult } from '../../state/memory-recall-contract.js';
+import { type MemoryRecallSnapshot, type MemoryRecallRefreshOptions } from './recall-snapshot.js';
+/** Patch shape accepted by an editable-field update (scope/summary/detail/tags). */
+export interface MemoryUpdatePatch {
+    readonly scope?: MemoryScope | undefined;
+    readonly summary?: string | undefined;
+    readonly detail?: string | undefined;
+    readonly tags?: string[] | undefined;
+}
+/**
+ * The five CORE verbs, shipped in 1.1.0. Every transport must implement all five —
+ * they are the minimum that lets a surface store and recall a fact over the wire.
+ */
+export interface MemoryCoreAccess {
+    add(opts: MemoryAddOptions): Promise<MemoryRecord>;
+    honestSearch(filter: MemorySearchFilter, options?: HonestMemorySearchOptions): Promise<HonestMemorySearchResult>;
+    get(id: string): Promise<MemoryRecord | null>;
+    updateReview(id: string, patch: MemoryReviewPatch): Promise<MemoryRecord | null>;
+    delete(id: string): Promise<boolean>;
+}
+/**
+ * The EXTENDED verbs added in 1.2.0 so a wire client can fully detach from the file.
+ * Each maps to a MemoryRegistry read/write the consumers were still doing locally:
+ *  - `list`          — bulk read (getAll / literal browse): knowledge injection + agent `list`.
+ *  - `searchSemantic`— scored semantic recall: agent semantic path + TUI `/recall --semantic`.
+ *  - `update`        — edit scope/summary/detail/tags (a scope edit is how a record is "promoted" project→team).
+ *  - `link`/`linksFor` — relate records / read a record's links.
+ *  - `reviewQueue`   — records prioritised for review (the curator/queue surface).
+ *  - `exportBundle`/`importBundle` — the no-loss bundle seam over the wire.
+ *  - `vectorStats`/`doctor` — read the daemon's canonical index diagnostics.
+ *
+ * DELIBERATELY NOT HERE (host-only, ruled in the full-detach decision record):
+ * `rebuildVectors`/`rebuildVectorsAsync`. Rebuilding the vector index is maintenance
+ * a store performs on its OWN index; the daemon keeps its canonical index current on
+ * every add/import and exposes an admin `POST /api/memory/vector/rebuild` for a forced
+ * rebuild. A wire client owns no index to rebuild, so a client-initiated rebuild is an
+ * admin/diagnostic action against a store it does not own — it stays out of band, not
+ * a per-record detach need.
+ */
+export interface MemoryExtendedAccess {
+    list(filter?: MemorySearchFilter): Promise<readonly MemoryRecord[]>;
+    searchSemantic(filter?: MemorySearchFilter): Promise<readonly MemorySemanticSearchResult[]>;
+    update(id: string, patch: MemoryUpdatePatch): Promise<MemoryRecord | null>;
+    link(fromId: string, toId: string, relation: string): Promise<MemoryLink | null>;
+    linksFor(id: string): Promise<readonly MemoryLink[]>;
+    reviewQueue(limit?: number, scope?: MemoryScope): Promise<readonly MemoryRecord[]>;
+    exportBundle(filter?: MemorySearchFilter): Promise<MemoryBundle>;
+    importBundle(bundle: MemoryBundle): Promise<MemoryImportResult>;
+    vectorStats(): Promise<MemoryVectorStats>;
+    doctor(): Promise<MemoryDoctorReport>;
+}
+/**
+ * The full memory read/write surface a caller uses without caring whether it
+ * resolves locally or over the wire. Every method is async so a local (sync store)
+ * and a wire (async) backend present the SAME shape.
+ */
+export interface MemoryAccess extends MemoryCoreAccess, MemoryExtendedAccess {
+}
+/**
+ * The injected wire transport. A consumer builds a thin adapter over the daemon's
+ * memory.records.* routes. The five CORE verbs are required; the EXTENDED verbs are
+ * optional so a surface pinned to an older SDK/daemon still satisfies the type — a
+ * client calling an extended verb the adopted daemon lacks gets an honest rejection,
+ * never a silent local-file read.
+ */
+export type MemoryTransport = MemoryCoreAccess & Partial<MemoryExtendedAccess>;
+/**
+ * The local embedded store surface. The SDK's `MemoryRegistry` satisfies this
+ * structurally (its methods are mostly synchronous; the facade normalizes them to
+ * promises). Kept minimal so the client stays decoupled from the concrete class.
+ */
+export interface LocalMemoryStore {
+    add(opts: MemoryAddOptions): Promise<MemoryRecord> | MemoryRecord;
+    honestSearch(filter: MemorySearchFilter, options?: HonestMemorySearchOptions): HonestMemorySearchResult;
+    get(id: string): MemoryRecord | null;
+    review(id: string, patch: MemoryReviewPatch): MemoryRecord | null;
+    delete(id: string): boolean;
+    search(filter?: MemorySearchFilter): MemoryRecord[];
+    searchSemantic(filter?: MemorySearchFilter): MemorySemanticSearchResult[];
+    update(id: string, patch: MemoryUpdatePatch): MemoryRecord | null;
+    link(fromId: string, toId: string, relation: string): Promise<MemoryLink | null> | MemoryLink | null;
+    linksFor(id: string): MemoryLink[];
+    reviewQueue(limit?: number, scope?: MemoryScope): MemoryRecord[];
+    exportBundle(filter?: MemorySearchFilter): MemoryBundle;
+    importBundle(bundle: MemoryBundle): Promise<MemoryImportResult> | MemoryImportResult;
+    vectorStats(): MemoryVectorStats;
+    doctor(): Promise<MemoryDoctorReport> | MemoryDoctorReport;
+}
+/** Wrap a local embedded store (e.g. a MemoryRegistry) as a full MemoryAccess. */
+export declare function createLocalMemoryAccess(store: LocalMemoryStore): MemoryAccess;
+/** Current access posture — honest, reportable, never guessed. */
+export type MemoryAccessMode = 'local' | 'client';
+type SpineLogger = Pick<typeof logger, 'debug' | 'info'>;
+export interface MemorySpineClientOptions {
+    /** The local embedded store, always present as the offline/host backend. */
+    readonly local: MemoryAccess;
+    /**
+     * Attach a wire transport at construction for CLIENT mode immediately (a surface
+     * that boots already adopted to a daemon). Omit for LOCAL mode until `activate()`
+     * (a surface that adopts a daemon later, or runs offline forever).
+     */
+    readonly transport?: MemoryTransport | undefined;
+    /**
+     * How long a recall snapshot stays "fresh" before `recallSnapshot()` reports it
+     * stale. Defaults to {@link DEFAULT_RECALL_SNAPSHOT_STALE_AFTER_MS}.
+     */
+    readonly recallSnapshotStaleAfterMs?: number | undefined;
+    readonly log?: SpineLogger;
+}
+export type { MemoryRecallSnapshot, MemoryRecallRefreshOptions } from './recall-snapshot.js';
+/**
+ * Routes memory access to the LOCAL embedded store or, when a daemon has been
+ * adopted, THROUGH the wire — never both. Implements {@link MemoryAccess} so a
+ * caller uses one object regardless of mode.
+ */
+export declare class MemorySpineClient implements MemoryAccess {
+    private readonly local;
+    private transport;
+    private readonly log;
+    private readonly staleAfterMs;
+    /** Last recall snapshot captured by refreshRecallSnapshot(); null until first refresh. */
+    private snapshot;
+    constructor(options: MemorySpineClientOptions);
+    /** The current posture: 'client' when routing over the wire, 'local' otherwise. */
+    mode(): MemoryAccessMode;
+    /** Whether a wire transport is attached (client-of-adopted-daemon mode). */
+    get active(): boolean;
+    /**
+     * Adopt a daemon: route every memory op through the wire from now on. The local
+     * store is left untouched for the lifetime of client mode — the daemon is the
+     * single writer.
+     */
+    activate(transport: MemoryTransport): void;
+    /** Release the daemon (mode lost / daemon stopped): return to owned-local access. */
+    deactivate(reason: string): void;
+    add(opts: MemoryAddOptions): Promise<MemoryRecord>;
+    honestSearch(filter: MemorySearchFilter, options?: HonestMemorySearchOptions): Promise<HonestMemorySearchResult>;
+    get(id: string): Promise<MemoryRecord | null>;
+    updateReview(id: string, patch: MemoryReviewPatch): Promise<MemoryRecord | null>;
+    delete(id: string): Promise<boolean>;
+    list(filter?: MemorySearchFilter): Promise<readonly MemoryRecord[]>;
+    searchSemantic(filter?: MemorySearchFilter): Promise<readonly MemorySemanticSearchResult[]>;
+    update(id: string, patch: MemoryUpdatePatch): Promise<MemoryRecord | null>;
+    link(fromId: string, toId: string, relation: string): Promise<MemoryLink | null>;
+    linksFor(id: string): Promise<readonly MemoryLink[]>;
+    reviewQueue(limit?: number, scope?: MemoryScope): Promise<readonly MemoryRecord[]>;
+    exportBundle(filter?: MemorySearchFilter): Promise<MemoryBundle>;
+    importBundle(bundle: MemoryBundle): Promise<MemoryImportResult>;
+    vectorStats(): Promise<MemoryVectorStats>;
+    doctor(): Promise<MemoryDoctorReport>;
+    /**
+     * Refresh the cached recall snapshot ASYNCHRONOUSLY over the CURRENT route (wire
+     * when adopted, local otherwise). Call this from an async pre-turn hook so a
+     * SYNCHRONOUS prompt builder can read the result via {@link recallSnapshot}
+     * without awaiting the wire. Runs the honest recall search (recall-injection
+     * contract ON by default), stamps the capture time and mode, and stores it.
+     */
+    refreshRecallSnapshot(filter?: MemorySearchFilter, options?: MemoryRecallRefreshOptions): Promise<MemoryRecallSnapshot>;
+    /**
+     * Read the last recall snapshot SYNCHRONOUSLY (for a sync prompt builder). Never
+     * opens the file and never awaits: it returns whatever the last async refresh
+     * captured, with a freshly-computed age, a `stale` flag, and an HONEST `note`. If
+     * no refresh has happened yet it returns an EMPTY snapshot whose note says exactly
+     * that — never a silent empty that reads as "nothing was ever stored."
+     */
+    recallSnapshot(now?: number): MemoryRecallSnapshot;
+    /**
+     * The single choke point that realizes the one-writer invariant: in client mode
+     * EVERY op resolves through the transport and the local store is never reached.
+     */
+    private route;
+    /**
+     * Route an extended verb. Local mode → the local store. Client mode → the
+     * transport's verb if it implements it, otherwise an HONEST rejection stating the
+     * adopted daemon does not support it (never a silent local-file read, which would
+     * break the single-writer invariant and misreport which store answered).
+     */
+    private routeExtended;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/platform/runtime/memory-spine/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/memory-spine/client.ts"],"names":[],"mappings":"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"}

package/dist/platform/runtime/memory-spine/client.js

@@ -0,0 +1,221 @@
+/**
+ * client.ts — the SDK memory-spine surface client (host-vs-client access mode).
+ *
+ * The daemon-owned memory service makes the daemon the SINGLE WRITER of its
+ * canonical sql.js store. sql.js has no row locking and rewrites the whole file on
+ * every save(), so two live processes writing the same file clobber each other —
+ * a whole-file lost update that would DELETE memory. One process must own the
+ * store; every other surface reaches it over the wire.
+ *
+ * This client is the surface-side switch that realizes that invariant, mirroring
+ * the session-spine host-vs-client pattern:
+ *
+ *  - HOST / OFFLINE-EMBEDDED mode (transport NOT attached): the surface IS the only
+ *    process touching its own store file, so it reads/writes the LOCAL embedded
+ *    store directly. This is the offline fallback the agent and TUI keep — a daemon
+ *    is not required for them to work.
+ *  - CLIENT-OF-ADOPTED-DAEMON mode (transport attached): the daemon owns the store;
+ *    the surface routes EVERY memory op through the injected wire transport and
+ *    NEVER opens the file. Enforced structurally here — the active branch only ever
+ *    touches `this.transport`, never `this.local`.
+ *
+ * FULL DETACH (SDK 1.2.0). The 1.1.0 wire family covered five verbs (add,
+ * honestSearch, get, updateReview, delete). That was enough for a surface to store
+ * and recall a fact over the wire, but NOT enough to fully detach every consumer
+ * from the store file: the agent's `list`/`update`/semantic-search paths and the
+ * TUI's `/recall` browse/link/queue/export paths still fell back to a local file.
+ * This client now exposes the FULL read/write catalog those consumers need
+ * (see MemoryExtendedAccess), so a wire client never opens the file for ANY of them.
+ *
+ * ONE-WRITER ENFORCEMENT RULING. The platform's convention (see canonical-memory.ts
+ * and the session spine) is honest sequential/owned access plus stated posture, NOT
+ * an OS advisory lock — sql.js exposes no lock and a cross-process flock would be a
+ * new, unenforceable-on-every-OS mechanism the rest of the store does not rely on.
+ * So the invariant is enforced two ways, both honest: (1) mode exclusivity — a
+ * client in wire mode provably cannot reach the local file because the code routes
+ * exclusively to the transport; (2) a documented single-writer contract for the
+ * embedded case — the daemon host and an offline surface are each the sole process
+ * for their own file. `mode()` reports the current posture so a surface can surface
+ * it rather than guess.
+ *
+ * HONEST FAILURE. Unlike the fire-and-forget session mirror, memory reads/writes
+ * return data, so this client is request/response. In client mode a transport
+ * failure is SURFACED to the caller (the promise rejects); it is deliberately NOT
+ * silently served from the local store — a wire client must not open the
+ * daemon-owned file, and returning a divergent local copy as if it were canonical
+ * would be the exact dishonest-recall failure this whole design exists to prevent.
+ * A sustained daemon loss is handled by `deactivate()`, which returns the surface
+ * to owned-local mode explicitly.
+ *
+ * VERSION TOLERANCE. The five CORE verbs are required of every transport. The
+ * EXTENDED verbs are OPTIONAL on the transport (`MemoryTransport`) so a surface
+ * pinned to an older SDK/daemon pair that predates a verb still satisfies the type.
+ * When a client in wire mode calls an extended verb its adopted daemon does not
+ * implement, the call REJECTS with a stated reason — it never silently reaches into
+ * the local file, which would break the one-writer invariant and lie about which
+ * store answered.
+ */
+import { logger } from '../../utils/logger.js';
+import { buildRecallSnapshot, emptyRecallSnapshot, DEFAULT_RECALL_SNAPSHOT_STALE_AFTER_MS, } from './recall-snapshot.js';
+/** Wrap a local embedded store (e.g. a MemoryRegistry) as a full MemoryAccess. */
+export function createLocalMemoryAccess(store) {
+    return {
+        add: (opts) => Promise.resolve(store.add(opts)),
+        honestSearch: (filter, options) => Promise.resolve(store.honestSearch(filter, options)),
+        get: (id) => Promise.resolve(store.get(id)),
+        updateReview: (id, patch) => Promise.resolve(store.review(id, patch)),
+        delete: (id) => Promise.resolve(store.delete(id)),
+        list: (filter) => Promise.resolve(store.search(filter ?? {})),
+        searchSemantic: (filter) => Promise.resolve(store.searchSemantic(filter ?? {})),
+        update: (id, patch) => Promise.resolve(store.update(id, patch)),
+        link: (fromId, toId, relation) => Promise.resolve(store.link(fromId, toId, relation)),
+        linksFor: (id) => Promise.resolve(store.linksFor(id)),
+        reviewQueue: (limit, scope) => Promise.resolve(store.reviewQueue(limit, scope)),
+        exportBundle: (filter) => Promise.resolve(store.exportBundle(filter ?? {})),
+        importBundle: (bundle) => Promise.resolve(store.importBundle(bundle)),
+        vectorStats: () => Promise.resolve(store.vectorStats()),
+        doctor: () => Promise.resolve(store.doctor()),
+    };
+}
+/**
+ * Routes memory access to the LOCAL embedded store or, when a daemon has been
+ * adopted, THROUGH the wire — never both. Implements {@link MemoryAccess} so a
+ * caller uses one object regardless of mode.
+ */
+export class MemorySpineClient {
+    local;
+    transport;
+    log;
+    staleAfterMs;
+    /** Last recall snapshot captured by refreshRecallSnapshot(); null until first refresh. */
+    snapshot = null;
+    constructor(options) {
+        this.local = options.local;
+        this.transport = options.transport ?? null;
+        this.log = options.log ?? logger;
+        this.staleAfterMs = options.recallSnapshotStaleAfterMs ?? DEFAULT_RECALL_SNAPSHOT_STALE_AFTER_MS;
+    }
+    /** The current posture: 'client' when routing over the wire, 'local' otherwise. */
+    mode() {
+        return this.transport ? 'client' : 'local';
+    }
+    /** Whether a wire transport is attached (client-of-adopted-daemon mode). */
+    get active() {
+        return this.transport !== null;
+    }
+    /**
+     * Adopt a daemon: route every memory op through the wire from now on. The local
+     * store is left untouched for the lifetime of client mode — the daemon is the
+     * single writer.
+     */
+    activate(transport) {
+        this.transport = transport;
+        this.log.info('memory spine activated — routing memory through the adopted external daemon (single writer)', {});
+    }
+    /** Release the daemon (mode lost / daemon stopped): return to owned-local access. */
+    deactivate(reason) {
+        if (this.transport === null)
+            return;
+        this.transport = null;
+        this.log.info('memory spine deactivated — reverting to owned-local memory access', { reason });
+    }
+    // ── Core verbs (routed local-or-wire) ─────────────────────────────────────────
+    add(opts) {
+        return this.route().add(opts);
+    }
+    honestSearch(filter, options) {
+        return this.route().honestSearch(filter, options);
+    }
+    get(id) {
+        return this.route().get(id);
+    }
+    updateReview(id, patch) {
+        return this.route().updateReview(id, patch);
+    }
+    delete(id) {
+        return this.route().delete(id);
+    }
+    // ── Extended verbs (routed local-or-wire; honest reject if the daemon lacks one) ─
+    list(filter) {
+        return this.routeExtended('list', (a) => a.list(filter), (t) => t.list?.(filter));
+    }
+    searchSemantic(filter) {
+        return this.routeExtended('searchSemantic', (a) => a.searchSemantic(filter), (t) => t.searchSemantic?.(filter));
+    }
+    update(id, patch) {
+        return this.routeExtended('update', (a) => a.update(id, patch), (t) => t.update?.(id, patch));
+    }
+    link(fromId, toId, relation) {
+        return this.routeExtended('link', (a) => a.link(fromId, toId, relation), (t) => t.link?.(fromId, toId, relation));
+    }
+    linksFor(id) {
+        return this.routeExtended('linksFor', (a) => a.linksFor(id), (t) => t.linksFor?.(id));
+    }
+    reviewQueue(limit, scope) {
+        return this.routeExtended('reviewQueue', (a) => a.reviewQueue(limit, scope), (t) => t.reviewQueue?.(limit, scope));
+    }
+    exportBundle(filter) {
+        return this.routeExtended('exportBundle', (a) => a.exportBundle(filter), (t) => t.exportBundle?.(filter));
+    }
+    importBundle(bundle) {
+        return this.routeExtended('importBundle', (a) => a.importBundle(bundle), (t) => t.importBundle?.(bundle));
+    }
+    vectorStats() {
+        return this.routeExtended('vectorStats', (a) => a.vectorStats(), (t) => t.vectorStats?.());
+    }
+    doctor() {
+        return this.routeExtended('doctor', (a) => a.doctor(), (t) => t.doctor?.());
+    }
+    // ── The sync-recall seam ──────────────────────────────────────────────────────
+    /**
+     * Refresh the cached recall snapshot ASYNCHRONOUSLY over the CURRENT route (wire
+     * when adopted, local otherwise). Call this from an async pre-turn hook so a
+     * SYNCHRONOUS prompt builder can read the result via {@link recallSnapshot}
+     * without awaiting the wire. Runs the honest recall search (recall-injection
+     * contract ON by default), stamps the capture time and mode, and stores it.
+     */
+    async refreshRecallSnapshot(filter = {}, options = {}) {
+        const recall = options.recall ?? true;
+        const result = await this.route().honestSearch(filter, { recall });
+        this.snapshot = buildRecallSnapshot(result, this.mode(), Date.now(), this.staleAfterMs);
+        return this.snapshot;
+    }
+    /**
+     * Read the last recall snapshot SYNCHRONOUSLY (for a sync prompt builder). Never
+     * opens the file and never awaits: it returns whatever the last async refresh
+     * captured, with a freshly-computed age, a `stale` flag, and an HONEST `note`. If
+     * no refresh has happened yet it returns an EMPTY snapshot whose note says exactly
+     * that — never a silent empty that reads as "nothing was ever stored."
+     */
+    recallSnapshot(now = Date.now()) {
+        const cached = this.snapshot;
+        if (cached === null || cached.search === null || cached.capturedAt === null)
+            return emptyRecallSnapshot(this.mode());
+        return buildRecallSnapshot(cached.search, cached.mode, cached.capturedAt, this.staleAfterMs, now);
+    }
+    /**
+     * The single choke point that realizes the one-writer invariant: in client mode
+     * EVERY op resolves through the transport and the local store is never reached.
+     */
+    route() {
+        return this.transport ?? this.local;
+    }
+    /**
+     * Route an extended verb. Local mode → the local store. Client mode → the
+     * transport's verb if it implements it, otherwise an HONEST rejection stating the
+     * adopted daemon does not support it (never a silent local-file read, which would
+     * break the single-writer invariant and misreport which store answered).
+     */
+    routeExtended(verb, local, wire) {
+        if (this.transport === null)
+            return local(this.local);
+        const call = wire(this.transport);
+        if (call === undefined) {
+            return Promise.reject(new Error(`memory spine: the adopted daemon does not support the '${verb}' memory verb over the wire — `
+                + 'upgrade the daemon to a build that serves it, or run this surface offline (no daemon adopted). '
+                + 'A wire client will not read its own local store for this op, because that would break the '
+                + 'single-writer invariant and report a divergent local copy as if it were the canonical store.'));
+        }
+        return call;
+    }
+}

package/dist/platform/runtime/memory-spine/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @pellux/goodvibes-sdk/platform/runtime/memory-spine
+ *
+ * The surface-side host-vs-client switch for the daemon-owned single-writer memory
+ * service. A daemon host (and any offline/embedded surface) uses the LOCAL store
+ * directly; a surface that has adopted a compatible daemon routes memory THROUGH
+ * the wire and never opens the store file. Mirrors the session-spine pattern; the
+ * offline fallback stays, so the agent and TUI keep working with no daemon running.
+ *
+ * As of 1.2.0 the client exposes the FULL read/write catalog (see
+ * MemoryExtendedAccess) so a wire client fully detaches from the file, plus a
+ * freshness-stamped recall snapshot (recall-snapshot.ts) for the synchronous
+ * per-turn prompt-injection seam.
+ */
+export { MemorySpineClient, createLocalMemoryAccess, type MemoryAccess, type MemoryCoreAccess, type MemoryExtendedAccess, type MemoryAccessMode, type MemoryTransport, type MemoryUpdatePatch, type LocalMemoryStore, type MemorySpineClientOptions, type MemoryRecallSnapshot, type MemoryRecallRefreshOptions, } from './client.js';
+export { buildRecallSnapshot, emptyRecallSnapshot, DEFAULT_RECALL_SNAPSHOT_STALE_AFTER_MS, } from './recall-snapshot.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/runtime/memory-spine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/memory-spine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,GAChC,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,sCAAsC,GACvC,MAAM,sBAAsB,CAAC"}

package/dist/platform/runtime/memory-spine/index.js

@@ -0,0 +1,16 @@
+/**
+ * @pellux/goodvibes-sdk/platform/runtime/memory-spine
+ *
+ * The surface-side host-vs-client switch for the daemon-owned single-writer memory
+ * service. A daemon host (and any offline/embedded surface) uses the LOCAL store
+ * directly; a surface that has adopted a compatible daemon routes memory THROUGH
+ * the wire and never opens the store file. Mirrors the session-spine pattern; the
+ * offline fallback stays, so the agent and TUI keep working with no daemon running.
+ *
+ * As of 1.2.0 the client exposes the FULL read/write catalog (see
+ * MemoryExtendedAccess) so a wire client fully detaches from the file, plus a
+ * freshness-stamped recall snapshot (recall-snapshot.ts) for the synchronous
+ * per-turn prompt-injection seam.
+ */
+export { MemorySpineClient, createLocalMemoryAccess, } from './client.js';
+export { buildRecallSnapshot, emptyRecallSnapshot, DEFAULT_RECALL_SNAPSHOT_STALE_AFTER_MS, } from './recall-snapshot.js';

package/dist/platform/runtime/memory-spine/recall-snapshot.d.ts

@@ -0,0 +1,74 @@
+/**
+ * recall-snapshot.ts — the sync-recall seam for the memory spine.
+ *
+ * THE PROBLEM. Per-turn memory recall wants to inject the recall-eligible records
+ * into the system prompt. But the prompt builder is SYNCHRONOUS
+ * (`Orchestrator.getSystemPrompt()` returns a string, not a promise), while a wire
+ * client's memory reads are ASYNCHRONOUS (a fetch to the adopted daemon). A sync
+ * function cannot await a wire read, so it cannot pull fresh memory over the wire
+ * inline.
+ *
+ * THE DESIGN (cached snapshot, freshness-stamped, honest staleness note). Rather
+ * than make the whole prompt path async (a large, cross-consumer refactor) or open
+ * the store file from a wire client (which would break the single-writer invariant),
+ * the spine maintains a CACHED recall snapshot:
+ *
+ *   1. an ASYNC pre-turn hook calls `MemorySpineClient.refreshRecallSnapshot()` —
+ *      this awaits the wire (or local) honest recall search and stamps the result
+ *      with a capture time and the access mode it came from;
+ *   2. the SYNC prompt builder calls `MemorySpineClient.recallSnapshot()` — this
+ *      returns the cached records immediately, with a freshly-computed age, a
+ *      `stale` flag, and a human-readable `note`.
+ *
+ * HONESTY. The snapshot never lies about its own freshness. If it has never been
+ * refreshed, it returns an EMPTY snapshot whose note says exactly that — never a
+ * silent empty that a reader would misread as "nothing was ever stored". If the last
+ * refresh is older than the staleness window, `stale` is true and the note says so,
+ * so an injector can choose to note the staleness in the prompt rather than present
+ * possibly-old memory as live. The `mode` records WHERE the snapshot was captured
+ * (local host store vs the adopted daemon over the wire), so the note never implies
+ * a wire read happened when it did not.
+ */
+import type { MemoryRecord } from '../../state/memory-store.js';
+import type { HonestMemorySearchResult } from '../../state/memory-recall-contract.js';
+import type { MemoryAccessMode } from './client.js';
+/** Default freshness window: a snapshot older than this reports `stale: true`. */
+export declare const DEFAULT_RECALL_SNAPSHOT_STALE_AFTER_MS = 30000;
+export interface MemoryRecallRefreshOptions {
+    /**
+     * Apply the recall-injection contract when refreshing (exclude flagged records and
+     * drop sub-floor records, each exclusion counted). Defaults to TRUE — the snapshot
+     * exists for prompt injection, which must honor the recall floor. Pass false to
+     * capture an unfiltered browse set instead.
+     */
+    readonly recall?: boolean | undefined;
+}
+/**
+ * A freshness-stamped, synchronously-readable recall result. `records` is what a
+ * sync prompt builder injects; the rest is the honest receipt.
+ */
+export interface MemoryRecallSnapshot {
+    /** The recall-eligible records captured by the last refresh (empty until first refresh). */
+    readonly records: readonly MemoryRecord[];
+    /** The full honest search envelope the records came from (null until first refresh). */
+    readonly search: HonestMemorySearchResult | null;
+    /** When the snapshot was captured (epoch ms), or null if never refreshed. */
+    readonly capturedAt: number | null;
+    /** Age of the snapshot in ms at read time, or null if never refreshed. */
+    readonly ageMs: number | null;
+    /** True when the snapshot is older than the staleness window (or never captured). */
+    readonly stale: boolean;
+    /** Where the snapshot was captured from — 'client' (over the wire) or 'local'. */
+    readonly mode: MemoryAccessMode;
+    /** An honest, human-readable freshness/degradation note — never silent. */
+    readonly note: string;
+}
+/** The snapshot returned before any refresh has happened — empty, and it says so. */
+export declare function emptyRecallSnapshot(mode: MemoryAccessMode): MemoryRecallSnapshot;
+/**
+ * Build a snapshot from an honest search envelope captured at `capturedAt`, with age
+ * and staleness computed against `now`. The `note` states the source, the age, and
+ * — when stale — that the records may be out of date.
+ */
+export declare function buildRecallSnapshot(search: HonestMemorySearchResult, mode: MemoryAccessMode, capturedAt: number, staleAfterMs: number, now?: number): MemoryRecallSnapshot;
+//# sourceMappingURL=recall-snapshot.d.ts.map

package/dist/platform/runtime/memory-spine/recall-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-snapshot.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/memory-spine/recall-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,kFAAkF;AAClF,eAAO,MAAM,sCAAsC,QAAS,CAAC;AAE7D,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,CAWhF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,GAAG,GAAE,MAAmB,GACvB,oBAAoB,CAqBtB"}