hippo-memory 2.0.0 → 2.1.0

package/dist/server/types.d.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { Context } from '../api/index.js';
+import type { ContextWith, StoreContext } from '../api/index.js';
 import type { JsonValue } from '../util/json.js';
 import type { RateLimiter } from './rate-limit.js';
 import type { HippoStore, StoreGroup } from '../store/index.js';
@@ -7,8 +7,8 @@ export interface ServerHandle {
     port: number;
     url: string;
     stop: () => Promise<void>;
-    /** Introspection-only: the underlying node:http Server, so tests can assert keep-alive/headers timeout hardening without reaching into serve()'s closure.
-     * Do not use for control flow. */
+    /** Introspection-only: the underlying node:http Server, so tests can assert keep-alive/headers timeout hardening
+     * without reaching into serve()'s closure. Do not use for control flow. */
     server?: import('node:http').Server;
 }
 /** Identity an {@link AuthResolver} vouches for. The core sanitises it before use. */
@@ -20,11 +20,12 @@ export interface ResolvedBearer {
     role: 'admin' | 'member';
     scopes?: readonly string[];
 }
-/** Sole judge of non-`hk_` bearer tokens: null is a 401; a throw or missed deadline is a 503, so throw only when upstream is down. */
+/** Sole judge of non-`hk_` bearer tokens: null is a 401; a throw or missed deadline is a 503, so throw only when
+ * upstream is down. */
 export type AuthResolver = (token: string) => ResolvedBearer | null | Promise<ResolvedBearer | null>;
 /** What an add-on route's handler gets: the caller core authenticated and the parsed JSON body. */
 export interface AddonCall {
-    readonly ctx: Context;
+    readonly ctx: StoreContext;
     readonly body: Readonly<Record<string, JsonValue>>;
 }
 /** A POST /v1 route an add-on mounts through serve(): core authenticates and parses first, then sends the
@@ -46,14 +47,16 @@ export interface ServeOpts {
     authResolverTimeoutMs?: number;
     port?: number;
     host?: string;
-    /** Stop and exit on SIGINT/SIGTERM, and drain then exit 1 on an uncaught exception or unhandled rejection. A stop still running
-     * 10 s past `shutdownDrainMs` ends the process with a failure exit. Only `hippo serve` owns the process, so only it sets this. */
+    /** Stop and exit on SIGINT/SIGTERM, and drain then exit 1 on an uncaught exception or unhandled rejection. A stop
+     * still running 10 s past `shutdownDrainMs` ends the process with a failure exit. Only `hippo serve` sets this. */
     handleSignals?: boolean;
     /** How long stop() lets in-flight requests finish before closing their sockets; defaults to 5000 ms. */
     shutdownDrainMs?: number;
-    /** How long a request may stay unanswered before one warn names it; the request itself is left alone. Defaults to 60000 ms. */
+    /** How long a request may stay unanswered before one warn names it; the request itself is left alone. Defaults to
+     * 60000 ms. */
     slowRequestWarnMs?: number;
-    /** Defaults to hippo.db under `hippoRoot`. A store of another kind runs only the routes ported to it; its caller closes it. */
+    /** Defaults to hippo.db under `hippoRoot`. A store of another
+     * kind runs only the routes ported to it; its caller closes it. */
     store?: HippoStore;
     autoSleep?: false;
     routes?: readonly AddonRoute[];
@@ -66,14 +69,17 @@ export interface ServeOpts {
         cert: string | Buffer;
         key: string | Buffer;
     };
-    /** Lets a non-loopback bind start without `tls`, for TLS that ends at a proxy in front; else serve() refuses it. Also HIPPO_ALLOW_CLEARTEXT=1. */
+    /** Lets a non-loopback bind start without `tls`, for TLS that ends at a
+     * proxy in front; else serve() refuses it. Also HIPPO_ALLOW_CLEARTEXT=1. */
     allowCleartext?: boolean;
-    /** The role a keyless local request (HIPPO_ALLOW_KEYLESS_LOCAL=1) gets; defaults to HIPPO_KEYLESS_LOCAL_ROLE, else 'member'. Only 'admin' is host admin. */
+    /** The role a keyless local request (HIPPO_ALLOW_KEYLESS_LOCAL=1) gets; defaults to HIPPO_KEYLESS_LOCAL_ROLE, else
+     * 'member'. Only 'admin' is host admin. */
     keylessLocalRole?: 'member' | 'admin';
-    /** Static JSON served to anyone at GET <path>; built once at boot and never authenticated, so it must hold nothing secret. */
+    /** Static JSON served to anyone at GET <path>; built once at
+     * boot and never authenticated, so it must hold nothing secret. */
     publicJson?: Readonly<Record<string, JsonValue>>;
-    /** Request limits: perCaller after auth, on by default (HIPPO_CALLER_RPS, else 20 per second, burst 40); perAddress replaces HIPPO_V1_RPS when set;
-     * 'off' disables either; failedAuthPerAddress guards scrypt. */
+    /** Request limits: perCaller after auth, on by default (HIPPO_CALLER_RPS, else 20 per second, burst 40); perAddress
+     * replaces HIPPO_V1_RPS when set; 'off' disables either; failedAuthPerAddress guards scrypt. */
     rateLimits?: {
         perCaller?: RateLimitSpec | 'off';
         perAddress?: RateLimitSpec | 'off';
@@ -82,6 +88,8 @@ export interface ServeOpts {
 }
 export type ResolvedServeOpts = ServeOpts & {
     store: HippoStore;
+    /** Fences a loop-off route's work from hippo.db on the server thread when the store has workers. */
+    offLoop: <T>(run: () => T) => T;
     publicJsonBodies: ReadonlyMap<string, string>;
     callerLimiter?: RateLimiter;
     failedAuthLimiter: RateLimiter;
@@ -94,19 +102,20 @@ export interface RouteRequest {
     query: URLSearchParams;
 }
 /** A request past the dispatch gate, carrying the caller the gate authenticated. */
-export interface AuthedRouteRequest extends RouteRequest {
-    ctx: Context;
+export interface AuthedRouteRequest<G extends StoreGroup = 'base'> extends RouteRequest {
+    ctx: ContextWith<G>;
 }
-/** A route's store status: a `storeReady` group, a `sqliteOnly` reason, or neither while it waits for a group; never both. */
-type StoreStatus = {
-    storeReady?: StoreGroup;
+/** A route's store status: a `storeReady` group, a `sqliteOnly`
+ * reason, or neither while it waits for a group; never both. */
+type StoreStatus<S extends StoreGroup> = {
+    storeReady?: S;
     sqliteOnly?: never;
 } | {
     sqliteOnly: string;
     storeReady?: never;
 };
-/** What the dispatch gate proves before a handler runs: any caller, an admin, a host admin on loopback, or nothing, for a route
- * whose handler checks the sender's signature itself. */
+/** What the dispatch gate proves before a handler runs: any caller, an admin, a host admin on loopback, or nothing, for
+ * a route whose handler checks the sender's signature itself. */
 export type RouteAuth = 'caller' | 'admin' | 'host-admin-local' | 'webhook-signature';
 export type RouteEndpoint<R> = {
     path: string;
@@ -118,15 +127,18 @@ export type RouteEndpoint<R> = {
     regex: RegExp;
     handler: (r: R, match: RegExpMatchArray) => Promise<void>;
 };
-/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with one method's handler. Under another store it runs only with its
- * store's `storeReady` group; `loop: 'off'` runs its SQLite work on a worker thread, so the handler opens no hippo.db on the server thread. */
-export type Route = {
+/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with one method's handler. Under another
+ * store it runs only with its store's `storeReady` group; `loop: 'off'` runs its SQLite work on a worker thread. */
+export type RouteOf<G extends StoreGroup, S extends StoreGroup = G> = {
     method: string;
     loop?: 'off';
-} & StoreStatus & (({
+} & StoreStatus<S> & (({
     auth: Exclude<RouteAuth, 'webhook-signature'>;
-} & RouteEndpoint<AuthedRouteRequest>) | ({
+} & RouteEndpoint<AuthedRouteRequest<G>>) | ({
     auth: 'webhook-signature';
 } & RouteEndpoint<RouteRequest>));
+/** A route as the table holds it, its handler's group erased: `defineRoute` is where a handler's group meets the
+ * row's `storeReady`. */
+export type Route = RouteOf<'base', StoreGroup>;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/server/validation.d.ts

@@ -8,9 +8,12 @@ export declare function parseListLimit(limitRaw: string | null, defaultLimit?: n
  * an authenticated caller; the key mint reads under its own small cap. */
 export declare function parseJsonBody(req: IncomingMessage, _authed: Context): Promise<Record<string, JsonValue>>;
 export declare function parseJsonObjectText(raw: string): Record<string, JsonValue>;
+/** Absent (undefined or null) is undefined; a present value of the wrong type is a 400, never a silent default. */
 export declare function getString(obj: Record<string, JsonValue>, key: string): string | undefined;
 export declare function getStringArray(obj: Record<string, JsonValue>, key: string): string[] | undefined;
-/** Keeps only `name` and `aliases`: a client's `legacy_name` is a folder name, which must never become a row's origin. */
+/**
+ * Keeps only `name` and `aliases`: a client's `legacy_name` is a folder name, which must never become a row's origin.
+ */
 export declare function getCallerProject(body: Record<string, JsonValue>): RememberOpts['project'];
 export declare function validateIdSegment(id: string, fieldName: string): void;
 //# sourceMappingURL=validation.d.ts.map

package/dist/server/validation.js

@@ -1,10 +1,12 @@
 import { HttpError, readBody } from '../util/http-util.js';
 import { DEFAULT_LIST_LIMIT, MAX_ID_LEN, MAX_LIST_LIMIT, resolveListLimit } from '../util/limits.js';
 import { isJsonString, isJsonObject } from '../util/json.js';
-// Runtime membership check for a `ReadonlySet<T>` of string-literal members: Set<T>.has gives no narrowing, so this is the one place the `as T` assertion lives
+// Runtime membership check for a `ReadonlySet<T>` of string-literal members: Set<T>.has gives no narrowing, so this is
+// the one place the `as T` assertion lives
 // and callers narrow via the `value is T` return.
 export function isSetMember(set, value) {
-    // SAFETY: `value as T` is discarded unless `set.has` (the real runtime check) confirms membership; the `value is T` return type does the narrowing.
+    // SAFETY: `value as T` is discarded unless `set.has` (the real runtime check) confirms membership; the `value is T`
+    // return type does the narrowing.
     return set.has(value);
 }
 // Cap for short free-text HTTP fields (names, text, context, change summaries) on the object routes.
@@ -36,19 +38,26 @@ export function parseJsonObjectText(raw) {
         throw new HttpError(400, 'invalid JSON body');
     }
 }
+/** Absent (undefined or null) is undefined; a present value of the wrong type is a 400, never a silent default. */
 export function getString(obj, key) {
     const v = obj[key];
-    return isJsonString(v) ? v : undefined;
+    if (v === undefined || v === null)
+        return undefined;
+    if (!isJsonString(v))
+        throw new HttpError(400, `${key} must be a string`);
+    return v;
 }
 export function getStringArray(obj, key) {
     const v = obj[key];
-    if (!Array.isArray(v))
-        return undefined;
-    if (!v.every(isJsonString))
+    if (v === undefined || v === null)
         return undefined;
+    if (!Array.isArray(v) || !v.every(isJsonString))
+        throw new HttpError(400, `${key} must be an array of strings`);
     return v;
 }
-/** Keeps only `name` and `aliases`: a client's `legacy_name` is a folder name, which must never become a row's origin. */
+/**
+ * Keeps only `name` and `aliases`: a client's `legacy_name` is a folder name, which must never become a row's origin.
+ */
 export function getCallerProject(body) {
     const v = body.project;
     if (v === undefined || v === null)
@@ -63,8 +72,12 @@ export function getCallerProject(body) {
     }
     return { name: v.name, aliases: v.aliases };
 }
-/** Charset + length validation for `:id` captures, called right after `matchPath` so empty/overlong/illegal ids get a 400, not "not found".
- * Allows every production id shape (`mem_<hex>`, `sess-<id>`, Slack ids) plus `:` and `.`; no `/`, since `rejectEncodedSlash` stops `%2F` smuggling. */
+/**
+ * Charset + length validation for `:id` captures, called right after `matchPath` so empty/overlong/illegal ids get a
+ * 400, not "not found".
+ * Allows every production id shape (`mem_<hex>`, `sess-<id>`, Slack ids) plus `:` and `.`; no `/`, since
+ * `rejectEncodedSlash` stops `%2F` smuggling.
+ */
 const ID_SEGMENT_RE = /^[A-Za-z0-9_:.-]+$/;
 export function validateIdSegment(id, fieldName) {
     if (id.length === 0)

package/dist/server.d.ts

@@ -1,23 +1,28 @@
-import { type Actor, authCreateSelf, type AuthCreateSelfOpts, type AuthCreateSelfResult, authRevoke, type AuthRevokeResult, type Context } from './api/index.js';
+import { type Actor, type AuthCreateOpts, type AuthCreateResult, type AuthCreateSelfOpts, type AuthCreateSelfResult, type AuthRevokeResult, type Context } from './api/index.js';
+import { promptHookContext as renderPromptHook, type PromptHookOpts, type PromptHookRequest } from './api/prompt-hook.js';
 import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './core/api-errors.js';
 export { serve } from './server/boot.js';
-export { authCreateSelf, authRevoke, BadRequestError, ConflictError, ForbiddenError, NotFoundError, type AuthCreateSelfOpts, type AuthCreateSelfResult, type AuthRevokeResult, type Context, type Actor, };
+declare function authCreate(ctx: Context, opts: AuthCreateOpts): Promise<AuthCreateResult>;
+declare function authCreateSelf(ctx: Context, opts: AuthCreateSelfOpts): Promise<AuthCreateSelfResult>;
+declare function authRevoke(ctx: Context, keyId: string): Promise<AuthRevokeResult>;
+declare function promptHookContext(ctx: Context, req: PromptHookRequest, opts?: PromptHookOpts): ReturnType<typeof renderPromptHook>;
+export { authCreate, authCreateSelf, authRevoke, BadRequestError, ConflictError, ForbiddenError, NotFoundError, promptHookContext, type AuthCreateSelfOpts, type AuthCreateSelfResult, type AuthRevokeResult, type Context, type Actor, };
 export { isCrossSite, LOOPBACK_HOST_HEADER } from './util/http-util.js';
 export { clientIpForRateLimit } from './server/client-ip.js';
 export { isLoopback, isReservedActor } from './server/auth.js';
-export type { AddonCall, AddonRoute, AuthResolver, RateLimitSpec, ResolvedBearer, ServeOpts, ServerHandle } from './server/types.js';
+export type { AddonCall, AddonRoute, AuthResolver, RateLimitSpec, ResolvedBearer, ServeOpts, ServerHandle, } from './server/types.js';
 export type { HippoStore } from './store/index.js';
 export { HttpError } from './util/http-util.js';
-export { promptHookContext, type CallerProject } from './api/prompt-hook.js';
+export type { CallerProject } from './api/prompt-hook.js';
 export type { JsonValue } from './util/json.js';
 export { captureSessionTexts, type SessionCaptureRequest, type SessionCaptureResult } from './capture/session-texts.js';
-export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api/index.js';
+export type { AuthCreateOpts, AuthCreateResult };
 export { ownerOrSubject } from './api/index.js';
-export { bindSessionOwner } from './api/session-owners.js';
-export { preCompactForCaller, type CallerHookOutput, type CallerPreCompactRequest } from './capture/pre-compact-caller.js';
+export { bindSessionOwner, bindSessionOwnerOn } from './api/auth/session-owners.js';
+export { preCompactForCaller, type CallerHookOutput, type CallerPreCompactRequest, } from './capture/pre-compact-caller.js';
 export { compactResumeForCaller, type CallerCompactResumeRequest } from './capture/compact-resume-caller.js';
-export { saveCompactionItemsForCaller, type CallerItemsRequest, type CallerItemsResult } from './capture/compaction-items-caller.js';
-export { captureFailureForCaller, type CallerFailureRequest, type CallerFailureResult } from './capture/failure-caller.js';
-export { sessionEndHandoffForCaller, type CallerEvidence, type CallerSessionEndRequest, type CallerSessionEndResult } from './capture/session-end-caller.js';
+export { saveCompactionItemsForCaller, type CallerItemsRequest, type CallerItemsResult, } from './capture/compaction-items-caller.js';
+export { captureFailureForCaller, type CallerFailureRequest, type CallerFailureResult, } from './capture/failure-caller.js';
+export { sessionEndHandoffForCaller, type CallerEvidence, type CallerSessionEndRequest, type CallerSessionEndResult, } from './capture/session-end-caller.js';
 export type { WorkingState } from './capture/working-state.js';
 //# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -1,25 +1,45 @@
-import { authCreateSelf, authRevoke, } from './api/index.js';
+import { authCreate as createKey, authCreateSelf as createSelfKey, authRevoke as revokeKey, } from './api/index.js';
+import { promptHookContext as renderPromptHook, } from './api/prompt-hook.js';
 import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './core/api-errors.js';
+import { hasGroup } from './store/port.js';
+import { sqliteReach, withStoreGroups } from './store/sqlite/store.js';
 export { serve } from './server/boot.js';
+// An add-on hands in a Context with no store, so each entry that
+// needs one fills it with hippo.db under the Context's root.
+async function authCreate(ctx, opts) {
+    return createKey(withStoreGroups(ctx, 'keyWrites'), opts);
+}
+async function authCreateSelf(ctx, opts) {
+    return createSelfKey(withStoreGroups(ctx, 'keyWrites'), opts);
+}
+async function authRevoke(ctx, keyId) {
+    return revokeKey(withStoreGroups(ctx, 'keyAudit'), keyId);
+}
+async function promptHookContext(ctx, req, opts) {
+    const filled = withStoreGroups(ctx, 'contextReads');
+    // Only hippo.db has a global store beside it; an add-on's own store reads as one project.
+    const sqliteBacked = ctx.store === undefined || hasGroup(ctx.store, 'localFiles');
+    const reach = ctx.reach ?? (sqliteBacked ? sqliteReach(ctx.hippoRoot, filled.store, opts?.sharedStore) : undefined);
+    return renderPromptHook({ ...filled, reach }, req, opts);
+}
 // Add-on packages mint and revoke keys through these without importing the whole api surface.
-export { authCreateSelf, authRevoke, BadRequestError, ConflictError, ForbiddenError, NotFoundError, };
+export { authCreate, authCreateSelf, authRevoke, BadRequestError, ConflictError, ForbiddenError, NotFoundError, promptHookContext, };
 export { isCrossSite, LOOPBACK_HOST_HEADER } from './util/http-util.js';
 export { clientIpForRateLimit } from './server/client-ip.js';
 export { isLoopback, isReservedActor } from './server/auth.js';
-// An add-on route replies 4xx with HttpError, renders the prompt hook elsewhere with promptHookContext, and types its body as JsonValue.
+// An add-on route replies 4xx with HttpError, renders the prompt hook elsewhere with promptHookContext, and types its
+// body as JsonValue.
 export { HttpError } from './util/http-util.js';
-export { promptHookContext } from './api/prompt-hook.js';
 // A session-end route stores the turns its caller read from a transcript on the caller's own machine.
 export { captureSessionTexts } from './capture/session-texts.js';
-// An add-on's install step mints the first admin key into a store folder it names, which `hippo auth create` cannot reach.
-export { authCreate } from './api/index.js';
 export { ownerOrSubject } from './api/index.js';
 // A route that writes for a session binds it to the caller's owner first.
-export { bindSessionOwner } from './api/session-owners.js';
-// A hook route for a caller on another machine: each call binds the session, then writes under the caller's owner and project.
-export { preCompactForCaller } from './capture/pre-compact-caller.js';
+export { bindSessionOwner, bindSessionOwnerOn } from './api/auth/session-owners.js';
+// A hook route for a caller on another machine: each call binds
+// the session, then writes under the caller's owner and project.
+export { preCompactForCaller, } from './capture/pre-compact-caller.js';
 export { compactResumeForCaller } from './capture/compact-resume-caller.js';
-export { saveCompactionItemsForCaller } from './capture/compaction-items-caller.js';
-export { captureFailureForCaller } from './capture/failure-caller.js';
-export { sessionEndHandoffForCaller } from './capture/session-end-caller.js';
+export { saveCompactionItemsForCaller, } from './capture/compaction-items-caller.js';
+export { captureFailureForCaller, } from './capture/failure-caller.js';
+export { sessionEndHandoffForCaller, } from './capture/session-end-caller.js';
 //# sourceMappingURL=server.js.map

package/dist/sharing/global-store.d.ts

@@ -1,18 +1,13 @@
-import { MemoryEntry } from '../core/memory.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { PromoteOptions } from '../store/port/promotion.js';
 /** Returns the path to the global Hippo store.
  *  Resolution order: $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo/ */
 export declare function getGlobalRoot(): string;
 /** Ensure the global store exists. */
 export declare function initGlobal(): void;
-export interface PromoteOptions {
-    actor?: string;
-    tenantId?: string;
-    /** Also writes one `promote` audit row for the copy ({sourceId}), in the copy's own transaction. */
-    auditAs?: {
-        tenantId: string;
-        actor: string;
-    };
-}
+export type { PromoteOptions };
 /** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
 export declare function promoteToGlobal(localRoot: string, id: string, opts?: PromoteOptions): MemoryEntry;
+/** Fire-and-forget: embedMemory gates on availability and never rejects. */
+export declare function embedGlobalCopy(globalEntry: MemoryEntry): void;
 //# sourceMappingURL=global-store.d.ts.map

package/dist/sharing/global-store.js

@@ -1,17 +1,9 @@
 // The global store: where it lives, creating it, and copying a local memory into it.
-import { BadRequestError, NotFoundError } from '../core/api-errors.js';
 import * as fs from 'fs';
-import { generateId } from '../core/memory.js';
+import { resolveGlobalRootDir } from '../core/project-identity.js';
 import { initStore } from '../store/open.js';
-import { writeEntryWithHook } from '../store/entry-writes.js';
-import { readEntry } from '../store/entry-reads.js';
-import { isPersonalScope } from '../core/recall-scope.js';
-import { fallbackOrigin, resolveGlobalRootDir } from '../core/project-identity.js';
-import { isSharedStore } from '../core/config.js';
-import { detectSecret } from '../util/secret-detect.js';
-import { isQuarantineScope } from '../trust/quarantine.js';
+import { copyToGlobal } from '../store/sqlite/global-promote.js';
 import { embedMemory } from '../search/embed-memories.js';
-import { appendAuditEvent } from '../store/audit.js';
 /** Returns the path to the global Hippo store.
  *  Resolution order: $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo/ */
 export function getGlobalRoot() {
@@ -32,39 +24,12 @@ export function initGlobal() {
 }
 /** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
 export function promoteToGlobal(localRoot, id, opts) {
-    const entry = readEntry(localRoot, id, opts?.tenantId);
-    if (!entry)
-        throw new NotFoundError(`Memory not found: ${id}`);
-    // Same quarantine veto as shareMemory; a promoted copy would have no quarantine record to review.
-    if (isQuarantineScope(entry.scope)) {
-        throw new BadRequestError(`Refusing to promote ${id}: it is quarantined pending review. Approve it first via 'hippo quarantine approve ${id}'.`);
-    }
-    if (isPersonalScope(entry.scope ?? null)) {
-        throw new BadRequestError(`Refusing to promote ${id}: it is a personal memory and stays with its owner on this server.`);
-    }
-    // Secret producer veto: promote is a producer path to the global store
-    // exactly like shareMemory - same hard rule.
-    const promoteSecret = detectSecret(entry);
-    if (promoteSecret.flagged) {
-        throw new BadRequestError(`Refusing to promote ${id} to the global store: content matches secret material (${promoteSecret.reason}). ` +
-            `Secrets stay in their owning project's store.`);
-    }
-    initGlobal();
-    const globalRoot = getGlobalRoot();
-    // A project store's NULL row gets its folder back; a shared store's folder is no caller's project, so NULL stays and the label names no path.
-    const globalEntry = {
-        ...entry,
-        id: generateId('g'),
-        source: isSharedStore(localRoot) ? `shared::${new Date().toISOString()}` : `promoted:${localRoot}`,
-        origin_project: entry.origin_project ?? fallbackOrigin(localRoot),
-    };
-    const { auditAs } = opts ?? {};
-    const promoteRow = auditAs && ((db, globalId) => {
-        appendAuditEvent(db, { tenantId: auditAs.tenantId, actor: auditAs.actor, op: 'promote', targetId: globalId, metadata: { sourceId: id } });
-    });
-    writeEntryWithHook(globalRoot, globalEntry, { actor: opts?.actor, afterWrite: promoteRow });
-    // Fire-and-forget: embedMemory gates on availability and never rejects.
-    void embedMemory(globalRoot, globalEntry);
+    const globalEntry = copyToGlobal(localRoot, id, opts);
+    embedGlobalCopy(globalEntry);
     return globalEntry;
 }
+/** Fire-and-forget: embedMemory gates on availability and never rejects. */
+export function embedGlobalCopy(globalEntry) {
+    void embedMemory(getGlobalRoot(), globalEntry);
+}
 //# sourceMappingURL=global-store.js.map

package/dist/sharing/global-sync.d.ts

@@ -1,4 +1,6 @@
-/** Copy all global memories into the local store, skipping entries that already exist locally by ID or text (promote and share copy under a new ID).
+/**
+ * Copy all global memories into the local store, skipping entries that already exist locally by ID or text (promote and
+ * share copy under a new ID).
  *  Returns the count of newly copied entries. */
 export declare function syncGlobalToLocal(localRoot: string, globalRoot: string, opts?: {
     includeCrossProject?: boolean;

package/dist/sharing/global-sync.js

@@ -13,7 +13,9 @@ import { detectSecret } from '../util/secret-detect.js';
 import { embedAll } from '../search/embed-memories.js';
 import { log } from '../util/log.js';
 import { logEmbedAllFailure } from './search-both.js';
-/** Copy all global memories into the local store, skipping entries that already exist locally by ID or text (promote and share copy under a new ID).
+/**
+ * Copy all global memories into the local store, skipping entries that already exist locally by ID or text (promote and
+ * share copy under a new ID).
  *  Returns the count of newly copied entries. */
 export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
     if (isSharedStore(localRoot)) {
@@ -25,7 +27,10 @@ export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
     return withRequestStoresSync(() => copyMissingRows(localRoot, globalRoot, opts.includeCrossProject === true));
 }
 const textKey = (e) => `${e.tenant_id}\n${e.content}`;
-/** One open per store and one transaction: id, tenant and text decide which rows to read whole, and the copies commit together. */
+/**
+ * One open per store and one transaction: id, tenant and text decide which rows to read whole, and the copies commit
+ * together.
+ */
 function copyMissingRows(localRoot, globalRoot, includeCrossProject) {
     // Host-wide read: the global union is copied into a tenant-scoped local store, and each copy keeps its own tenant.
     const localKeys = loadEntryTextKeys(localRoot);
@@ -35,8 +40,11 @@ function copyMissingRows(localRoot, globalRoot, includeCrossProject) {
     const candidates = loadEntryTextKeys(globalRoot).filter((k) => !localIds.has(k.id) && !k.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX) && !localText.has(textKey(k)));
     if (candidates.length === 0)
         return 0;
-    const byId = new Map(chunked(candidates.map((k) => k.id)).flatMap((ids) => loadEntriesByIds(globalRoot, ids)).map((e) => [e.id, e]));
-    // Syncing down must not re-import what ambient context excludes: other-project rows are skipped by default and secret rows never copied.
+    const byId = new Map(chunked(candidates.map((k) => k.id))
+        .flatMap((ids) => loadEntriesByIds(globalRoot, ids))
+        .map((e) => [e.id, e]));
+    // Syncing down must not re-import what ambient context excludes: other-project rows are skipped by default and secret
+    // rows never copied.
     // origin_project is preserved on the copy (the write stamps it only when missing).
     const currentProject = resolveProjectIdentity(path.dirname(path.resolve(localRoot)));
     // A locally rejected value must not come back through sync down: skipped per item, printed as one line.
@@ -44,13 +52,15 @@ function copyMissingRows(localRoot, globalRoot, includeCrossProject) {
     const count = writeEntriesSkippingRejected(localRoot, (put) => {
         for (const { id } of candidates) {
             const entry = byId.get(id);
-            // A row the global store dropped between the two reads, or a text an earlier copy in this batch already brought down.
+            // A row the global store dropped between the two reads, or a text an earlier copy in this batch already brought
+            // down.
             if (!entry || localText.has(textKey(entry)))
                 continue;
             if (detectSecret(entry).flagged)
                 continue;
-            if (!includeCrossProject && classifyOriginProject(entry.origin_project, currentProject) === 'cross-project')
+            if (!includeCrossProject && classifyOriginProject(entry.origin_project, currentProject) === 'cross-project') {
                 continue;
+            }
             if (put(entry))
                 localText.add(textKey(entry));
             else

package/dist/sharing/project-merge.d.ts

@@ -6,13 +6,18 @@ export interface ProjectSummary {
     readonly live: number;
     readonly imported: number;
     readonly newest: string;
-    /** Imported notes whose text another project name also holds: evidence of a duplicate import, never a merge target. */
+    /**
+     * Imported notes whose text another project name also holds: evidence of a duplicate import, never a merge target.
+     */
     readonly copiesElsewhere: number;
 }
 export interface MergeResult {
     readonly from: string;
     readonly into: string;
-    /** Imports `into` already holds for the same note, moved to dormant storage; the rest are re-tagged and the next sync files them under `into`. */
+    /**
+     * Imports `into` already holds for the same note, moved to dormant storage; the rest are re-tagged and the next sync
+     * files them under `into`.
+     */
     readonly setAside: readonly string[];
     readonly restamped: readonly string[];
     readonly dormantRestamped: readonly string[];
@@ -25,11 +30,17 @@ export interface ProjectCollision {
     readonly ids: readonly string[];
 }
 export interface RepairResult {
-    /** Imported notes filed under the wrong project, or under a project name when a user-global import holds the same text: set aside. */
+    /**
+     * Imported notes filed under the wrong project, or under a project name when a user-global import holds the same
+     * text: set aside.
+     */
     readonly copies: readonly string[];
     /** Names whose recorded session folders all resolve to one other project today, folded as `merge` would. */
     readonly folds: readonly ProjectFold[];
-    /** Names left unfolded because their folders now resolve to more than one project; only `merge` by hand can split them. */
+    /**
+     * Names left unfolded because their folders now resolve to more than one project; only `merge` by hand can split
+     * them.
+     */
     readonly collisions: readonly ProjectCollision[];
     readonly toProject: ReadonlyArray<{
         readonly id: string;
@@ -45,13 +56,19 @@ export interface RepairResult {
 export declare function listProjects(store: ProjectTagReads): ProjectSummary[];
 /** Refuses user-global and unknown: they are not projects, and folding them would leak or hide every row. */
 export declare function validateMergeNames(from: string, into: string): string | null;
-/** Folds project `from` into `into` for one tenant in one transaction; a dry run rolls back and writes nothing, mirrors included. */
+/**
+ * Folds project `from` into `into` for one tenant in one transaction; a dry run rolls back and writes nothing, mirrors
+ * included.
+ */
 export declare function mergeProjects(store: ProjectTagStore, opts: {
     from: string;
     into: string;
     dryRun: boolean;
 }): MergeResult;
-/** Reads only, so doctor and a dry run take no write lock; merged rows are planned before any fold, so a few may re-tag differently once folds apply. */
+/**
+ * Reads only, so doctor and a dry run take no write lock; merged rows are planned before any fold, so a few may re-tag
+ * differently once folds apply.
+ */
 export declare function planProjectRepair(store: ProjectTagReads, hippoRoot: string, globalFolds?: boolean): Omit<RepairResult, 'backup'>;
 /** Sets aside stray imports, folds the names the resolver now maps elsewhere, then
  * re-tags sleep's user-global merges by their parents; a dry run only plans. */
@@ -60,6 +77,7 @@ export declare function repairProjects(store: ProjectTagStore, opts: {
     globalFolds?: boolean;
 }): RepairResult;
 /** Sleep runs repair once per store, so an upgrade needs no command. Global-store folds stay
- *  with `hippo projects repair`: their evidence is compaction folders, blind to a same-named repo that never compacted. */
+ * with `hippo projects repair`: their evidence is compaction folders, blind to a same-named repo that never compacted.
+ */
 export declare function repairOnceOnSleep(store: ProjectTagStore): RepairResult | null;
 //# sourceMappingURL=project-merge.d.ts.map