@hasna/mementos 0.14.68 → 0.14.69

package/dist/cli/register-all.d.ts

@@ -0,0 +1,17 @@
+import type { Command } from "commander";
+/**
+ * Attach EVERY command group to `program`, in the order the CLI presents them.
+ *
+ * This is the single registration list. `index.tsx` calls it to build the real
+ * CLI, and `global-options.test.ts` calls it to walk the real option tables — so
+ * the structural short-flag guard cannot silently check a smaller tree than the
+ * one that ships.
+ *
+ * That drift was real: the guard originally re-listed 11 groups by hand while
+ * the CLI wired 15 sources, leaving `init`, `project-panel`, `brains` and the
+ * `@hasna/events` groups (`events`, `webhooks`) unwalked. Seven live `-j`
+ * collisions sat in that blind spot while the guard reported clean. Adding a
+ * command group here is now the only step required for it to be covered.
+ */
+export declare function registerAllCommands(program: Command): Command;
+//# sourceMappingURL=register-all.d.ts.map

package/dist/cli/register-all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-all.d.ts","sourceRoot":"","sources":["../../src/cli/register-all.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBzC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAiB7D"}

package/dist/cli/startup-side-effects.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+/**
+ * Mark a command as having no startup database access, and return it so it can
+ * be used inline at the end of a builder chain.
+ */
+export declare function withoutStartupDbAccess<T extends Command>(command: T): T;
+/** Whether the command about to run has opted out of the startup DB access. */
+export declare function skipsStartupDbAccess(command: Command | undefined): boolean;
+//# sourceMappingURL=startup-side-effects.d.ts.map

package/dist/cli/startup-side-effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-side-effects.d.ts","sourceRoot":"","sources":["../../src/cli/startup-side-effects.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAGvE;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAE1E"}

package/dist/db/__fixtures__/fail-closed-stub-server.d.ts

@@ -0,0 +1,2 @@
+declare const server: Bun.Server<undefined>;
+//# sourceMappingURL=fail-closed-stub-server.d.ts.map

package/dist/db/__fixtures__/fail-closed-stub-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail-closed-stub-server.d.ts","sourceRoot":"","sources":["../../../src/db/__fixtures__/fail-closed-stub-server.ts"],"names":[],"mappings":"AAcA,QAAA,MAAM,MAAM,uBAiBV,CAAC"}

package/dist/db/api-mode.d.ts

@@ -2,7 +2,56 @@ export interface ApiConfig {
     baseUrl: string;
     apiKey: string;
 }
+export declare const API_URL_ENV_KEYS: readonly ["HASNA_MEMENTOS_API_URL", "MEMENTOS_API_URL"];
+export declare const API_KEY_ENV_KEYS: readonly ["HASNA_MEMENTOS_API_KEY", "MEMENTOS_API_KEY"];
+export declare const DATABASE_URL_ENV_KEYS: readonly ["HASNA_MEMENTOS_DATABASE_URL", "MEMENTOS_DATABASE_URL"];
+/**
+ * Which env keys currently select API mode, by name only — never the values.
+ * Used by the operator-facing mode report so a human can see *why* the client
+ * is pointed at the cloud without reading source or echoing a credential.
+ */
+export declare function getApiModeEnvSources(): {
+    urlKey: string | null;
+    keyKey: string | null;
+    databaseUrlKey: string | null;
+};
+/**
+ * Escape hatch for a test that genuinely must reach a non-loopback endpoint.
+ * Opt-in by design: the default has to be safe, because the failure it prevents
+ * is silent and lands in a shared store.
+ */
+export declare const ALLOW_REMOTE_API_IN_TESTS_ENV = "MEMENTOS_ALLOW_REMOTE_API_IN_TESTS";
 /** Resolve the API client config from env, or `null` when not configured. */
+/** The env keys that explicitly select the local SQLite store. */
+export declare const DB_PATH_ENV_KEYS: readonly ["HASNA_MEMENTOS_DB_PATH", "MEMENTOS_DB_PATH"];
+/** Raised when the environment does not unambiguously select one store. */
+export declare class MementosStoreConfigError extends Error {
+    readonly code = "MEMENTOS_STORE_CONFIG";
+    constructor(message: string);
+}
+/**
+ * Throw unless the environment unambiguously selects one store.
+ *
+ * AMBIGUOUS CONFIGURATION IS AN ERROR, NOT A DEFAULT. Half an API configuration
+ * used to resolve to `null`, which every caller read as "local SQLite" — so an
+ * operator whose API key failed to load silently got a different, usually stale,
+ * dataset with no error and no flag. From the caller's side that is
+ * indistinguishable from a store that is working.
+ *
+ * Precedence, highest first:
+ *  1. An explicit SQLite path (`HASNA_MEMENTOS_DB_PATH` / `MEMENTOS_DB_PATH`) is
+ *     the narrowest, most specific signal and selects LOCAL, so local dev,
+ *     tooling and import/export keep working when a stray credential is exported
+ *     globally.
+ *  2. A client DSN present disables API mode. Unchanged here, and tracked
+ *     separately — a DSN on a client is forbidden and handled in database.ts.
+ *  3. Both API URL and API key present -> API mode.
+ *  4. Exactly ONE of them present -> ERROR naming the missing variable.
+ *  5. Neither present -> LOCAL. The documented single-operator default.
+ *
+ * Never reads, logs, or embeds a credential value — only variable NAMES.
+ */
+export declare function assertUnambiguousStoreEnv(): void;
 export declare function getApiConfig(): ApiConfig | null;
 /**
  * True when the client should route memory operations to the cloud API.
@@ -15,8 +64,27 @@ export declare class ApiRequestError extends Error {
     readonly body: string;
     constructor(message: string, status: number, body: string);
 }
-/** Authed JSON request. Throws {@link ApiRequestError} on non-2xx (except 404 handled by callers). */
-export declare function apiJson<T = unknown>(method: string, path: string, body?: unknown): {
+export interface ApiJsonOptions {
+    /**
+     * Treat `404` as a normal outcome and return `{status: 404, data: undefined}`
+     * instead of throwing. ONLY for callers where "absent" is a real answer —
+     * a GET of one record by id, a DELETE that tolerates an already-gone row, or
+     * a call that has an explicit fallback for a route an older server image does
+     * not serve yet (see `runCleanupViaApi`).
+     *
+     * It must never be set on a create/upsert path. A 404 there means the route
+     * did not exist on the server (client/server version skew, wrong base URL),
+     * so nothing was written; returning success-shaped data made the CLI print
+     * "Saved:" and exit 0 having persisted nothing. Default is fail-closed.
+     */
+    allow404?: boolean;
+}
+/**
+ * Authed JSON request. Throws {@link ApiRequestError} on every non-2xx,
+ * including 404, unless the caller opts into 404 pass-through via
+ * {@link ApiJsonOptions.allow404}.
+ */
+export declare function apiJson<T = unknown>(method: string, path: string, body?: unknown, options?: ApiJsonOptions): {
     status: number;
     data: T;
 };

package/dist/db/api-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-mode.d.ts","sourceRoot":"","sources":["../../src/db/api-mode.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAqBD,6EAA6E;AAC7E,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAK/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAGnC;AAED,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAK/B;AAsGD,sGAAsG;AACtG,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAiB9G;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAe/D"}
+{"version":3,"file":"api-mode.d.ts","sourceRoot":"","sources":["../../src/db/api-mode.ts"],"names":[],"mappings":"AA0CA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AASD,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AACxF,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AACxF,eAAO,MAAM,qBAAqB,mEAAoE,CAAC;AAsBvG;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAMtH;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,uCAAuC,CAAC;AAyDlF,6EAA6E;AAC7E,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AAExF,2EAA2E;AAC3E,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,2BAA2B;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAuBhD;AAED,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAM/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAGnC;AAED,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAK/B;AA0GD,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAiB7B;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAe/D"}

package/dist/db/locks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../src/db/locks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAI1D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAC5F,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,YAAY,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,QAAQ,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,QAAsB,EAChC,UAAU,SAAM,EAChB,EAAE,CAAC,EAAE,QAAQ,GACZ,YAAY,GAAG,IAAI,CAuErB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAenF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAW3E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,QAAQ,EACnB,EAAE,CAAC,EAAE,QAAQ,GACZ,YAAY,EAAE,CAqBhB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,QAAQ,EACnB,EAAE,CAAC,EAAE,QAAQ,GACZ,YAAY,GAAG,IAAI,CAcrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,YAAY,EAAE,CAa7E;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,eAAe,EAAE,CAS1E;AAED,wBAAgB,iBAAiB,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAQvD"}
+{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../src/db/locks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAI1D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AAC5F,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,YAAY,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,QAAQ,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,QAAsB,EAChC,UAAU,SAAM,EAChB,EAAE,CAAC,EAAE,QAAQ,GACZ,YAAY,GAAG,IAAI,CAuErB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAgBnF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAW3E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,QAAQ,EACnB,EAAE,CAAC,EAAE,QAAQ,GACZ,YAAY,EAAE,CAqBhB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,QAAQ,EACnB,EAAE,CAAC,EAAE,QAAQ,GACZ,YAAY,GAAG,IAAI,CAcrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,YAAY,EAAE,CAa7E;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,eAAe,EAAE,CAS1E;AAED,wBAAgB,iBAAiB,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAQvD"}

package/dist/db/memories.d.ts

@@ -4,7 +4,15 @@ export declare function parseMemoryRow(row: Record<string, unknown>): Memory;
 export declare function createMemory(input: CreateMemoryInput, dedupeMode?: DedupeMode, db?: Database): Memory;
 export interface BulkUpsertResult {
     inserted: number;
+    /** Rows the store already had (id or unique-key conflict) — a benign no-op. */
     skipped: number;
+    /**
+     * Rows the store REFUSED (bad enum, failed CHECK/FK, missing key). These did
+     * NOT persist. Kept separate from `skipped` so a caller can never read a
+     * dropped row as an idempotent no-op; every rejection also has a line in
+     * `errors`. `inserted + skipped + rejected === total`.
+     */
+    rejected: number;
     errors: string[];
     total: number;
 }
@@ -18,12 +26,22 @@ export interface BulkUpsertResult {
  *  - does NOT dedupe by key/scope/agent and does NOT fire hooks / entity
  *    extraction / embedding work (those run asynchronously elsewhere).
  *
- * Idempotency is by primary-key `id`: `INSERT OR IGNORE` maps to
- * `ON CONFLICT DO NOTHING` on Postgres, so a row whose `id` already exists is
- * left untouched and re-runs never create duplicate rows. This is the
- * cross-machine → cloud backfill path for the fleet self-host cutover: a
- * machine's local memories are shipped to the cloud store verbatim without
- * mutating rows that are already present.
+ * Idempotency is by conflict, not by suppression: the statement carries an
+ * explicit bare `ON CONFLICT DO NOTHING`, which SQLite and Postgres both read
+ * as "ignore a uniqueness conflict (primary-key `id` or the unique key index)".
+ * A row already present is therefore left untouched and re-runs never create
+ * duplicates. This is the cross-machine → cloud backfill path for the fleet
+ * self-host cutover: a machine's local memories are shipped to the cloud store
+ * verbatim without mutating rows that are already present.
+ *
+ * It deliberately does NOT use `INSERT OR IGNORE`: on SQLite that swallows
+ * *every* constraint failure, so a row refused by the `category`/`scope`/
+ * `source`/`status` CHECK vanished with `changes === 0` and was counted as an
+ * idempotent `skipped` — a cloud write that did not persist reporting success.
+ * With a bare `ON CONFLICT DO NOTHING` a CHECK/FK/NOT NULL violation still
+ * throws into the catch below and lands in `rejected` + `errors`. Enum values
+ * are additionally pre-validated per row so the reason names the field and the
+ * accepted set instead of quoting raw constraint SQL.
  *
  * FK-referenced agent/project/session/machine rows are stubbed via
  * {@link ensureMemoryReferences} so cross-machine authorship ids never fail the

package/dist/db/memories.d.ts.map

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

package/dist/db/session-jobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-jobs.d.ts","sourceRoot":"","sources":["../../src/db/session-jobs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAK1D,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,eAAe,CAAC;AACpF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEjF,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AA6BD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,qBAAqB,EAC5B,EAAE,CAAC,EAAE,QAAQ,GACZ,gBAAgB,CAwBlB;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,gBAAgB,GAAG,IAAI,CAehF;AAED,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,gBAAgB,EACzB,EAAE,CAAC,EAAE,QAAQ,GACZ,gBAAgB,EAAE,CA2CpB;AAED,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,qBAAqB,EAC9B,EAAE,CAAC,EAAE,QAAQ,GACZ,gBAAgB,GAAG,IAAI,CAwCzB;AAED,wBAAgB,iBAAiB,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,gBAAgB,GAAG,IAAI,CASxE"}
+{"version":3,"file":"session-jobs.d.ts","sourceRoot":"","sources":["../../src/db/session-jobs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAK1D,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,eAAe,CAAC;AACpF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEjF,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AA6BD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,qBAAqB,EAC5B,EAAE,CAAC,EAAE,QAAQ,GACZ,gBAAgB,CAwBlB;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,gBAAgB,GAAG,IAAI,CAiBhF;AAED,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,gBAAgB,EACzB,EAAE,CAAC,EAAE,QAAQ,GACZ,gBAAgB,EAAE,CA2CpB;AAED,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,qBAAqB,EAC9B,EAAE,CAAC,EAAE,QAAQ,GACZ,gBAAgB,GAAG,IAAI,CAwCzB;AAED,wBAAgB,iBAAiB,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,gBAAgB,GAAG,IAAI,CASxE"}

package/dist/db/store-backend.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The transport that reads and writes will actually use.
+ *
+ * - `local-sqlite`   — the on-disk SQLite file at `db_path` is authoritative.
+ * - `cloud-api`      — authed HTTPS to the self-hosted server (the shared store).
+ * - `cloud-postgres` — a direct Postgres DSN; server-only, never a client.
+ */
+export type StoreBackend = "local-sqlite" | "cloud-api" | "cloud-postgres";
+export interface StoreBackendReport {
+    /** Machine-readable contract for scripts and test guards. */
+    schema: "mementos.store_backend.v1";
+    backend: StoreBackend;
+    /** True when the HTTPS client transport is engaged (client reads AND writes). */
+    api_mode: boolean;
+    /** The `getStorageMode()` value — reported for diagnosis, NOT the answer. */
+    storage_mode: string;
+    /** The SQLite path that WOULD be used. Meaningful only for `local-sqlite`. */
+    db_path: string;
+    /** Cloud endpoint origin + prefix. Not a secret; the key is never included. */
+    api_endpoint: string | null;
+    /** Whether an API key is configured. The value is never read or reported. */
+    api_key_present: boolean;
+    /** Env key NAMES that produced this backend, or `"default"`. Names only. */
+    selected_by: string;
+}
+/**
+ * Resolve the effective store backend from the environment.
+ *
+ * Pure with respect to storage: touches no database, makes no network call, and
+ * never places a credential value in the returned report.
+ */
+export declare function resolveStoreBackend(): StoreBackendReport;
+//# sourceMappingURL=store-backend.d.ts.map

package/dist/db/store-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-backend.d.ts","sourceRoot":"","sources":["../../src/db/store-backend.ts"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,MAAM,EAAE,2BAA2B,CAAC;IACpC,OAAO,EAAE,YAAY,CAAC;IACtB,iFAAiF;IACjF,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,6EAA6E;IAC7E,eAAe,EAAE,OAAO,CAAC;IACzB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,kBAAkB,CAkCxD"}

package/dist/index.js

@@ -938,7 +938,7 @@ import { tmpdir } from "os";
 import { join as join2 } from "path";
 import { writeFileSync as writeFileSync2, unlinkSync } from "fs";
 import { randomUUID } from "crypto";
-function firstEnv(...keys) {
+function firstEnv(keys) {
   for (const k of keys) {
     const v = process.env[k]?.trim();
     if (v)
@@ -946,8 +946,38 @@ function firstEnv(...keys) {
   }
   return;
 }
+function firstEnvKey(keys) {
+  for (const k of keys) {
+    if (process.env[k]?.trim())
+      return k;
+  }
+  return null;
+}
 function hasDatabaseUrl() {
-  return Boolean(firstEnv("HASNA_MEMENTOS_DATABASE_URL", "MEMENTOS_DATABASE_URL"));
+  return Boolean(firstEnv(DATABASE_URL_ENV_KEYS));
+}
+function isLoopbackHost(rawHost) {
+  const host = rawHost.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+  return host === "localhost" || host === "::1" || /^127\./.test(host);
+}
+function assertRequestAllowedUnderTest(baseUrl) {
+  if (process.env["NODE_ENV"] !== "test")
+    return;
+  if (process.env[ALLOW_REMOTE_API_IN_TESTS_ENV]?.trim())
+    return;
+  let host;
+  try {
+    host = new URL(baseUrl).hostname;
+  } catch {
+    host = "";
+  }
+  if (host && isLoopbackHost(host))
+    return;
+  throw new Error("api-mode: REFUSING to make a cloud request from a test process \u2014 this would write to or read " + "from the SHARED PRODUCTION memory store, where test fixtures are indistinguishable from real " + `memories.
+` + `  host           : ${host || "(unparseable base URL)"}
+` + `  how this happens: a selector set at module scope (after the bun test preload ran), or \`bun test\` ` + `invoked from a directory with no bunfig.toml so the preload never loaded.
+` + "  fix            : build the child/process env via src/test-support/store-isolation.ts, or point the " + `suite at a loopback stub.
+` + `  override       : set ${ALLOW_REMOTE_API_IN_TESTS_ENV}=1 only for a test that must reach a remote endpoint.`);
 }
 function normalizeBase(raw) {
   let base = raw.trim().replace(/\/+$/, "");
@@ -955,9 +985,24 @@ function normalizeBase(raw) {
     return base;
   return `${base}/v1`;
 }
+function assertUnambiguousStoreEnv() {
+  if (firstEnvKey(DB_PATH_ENV_KEYS))
+    return;
+  if (hasDatabaseUrl())
+    return;
+  const urlKey = firstEnvKey(API_URL_ENV_KEYS);
+  const keyKey = firstEnvKey(API_KEY_ENV_KEYS);
+  if (urlKey && !keyKey) {
+    throw new MementosStoreConfigError(`${urlKey} points at the cloud memory store but ${API_KEY_ENV_KEYS[0]} is not set. ` + `Refusing to serve the on-box SQLite store in its place, because it holds a different ` + `dataset. Set ${API_KEY_ENV_KEYS[0]} to reach the cloud store. If you meant to use the ` + `on-box SQLite store, unset ${urlKey} or set ${DB_PATH_ENV_KEYS[0]} explicitly.`);
+  }
+  if (keyKey && !urlKey) {
+    throw new MementosStoreConfigError(`${keyKey} is set but ${API_URL_ENV_KEYS[0]} is not, so the cloud memory store cannot be ` + `reached. Refusing to serve the on-box SQLite store in its place, because it holds a ` + `different dataset. Set ${API_URL_ENV_KEYS[0]} to reach the cloud store. If you meant to ` + `use the on-box SQLite store, unset ${keyKey} or set ${DB_PATH_ENV_KEYS[0]} explicitly.`);
+  }
+}
 function getApiConfig() {
-  const rawBase = firstEnv("HASNA_MEMENTOS_API_URL", "MEMENTOS_API_URL");
-  const apiKey = firstEnv("HASNA_MEMENTOS_API_KEY", "MEMENTOS_API_KEY");
+  assertUnambiguousStoreEnv();
+  const rawBase = firstEnv(API_URL_ENV_KEYS);
+  const apiKey = firstEnv(API_KEY_ENV_KEYS);
   if (!rawBase || !apiKey)
     return null;
   return { baseUrl: normalizeBase(rawBase), apiKey };
@@ -971,6 +1016,7 @@ function apiRequestRaw(method, path, body) {
   const cfg = getApiConfig();
   if (!cfg)
     throw new Error("api-mode: not configured (HASNA_MEMENTOS_API_URL / HASNA_MEMENTOS_API_KEY)");
+  assertRequestAllowedUnderTest(cfg.baseUrl);
   const url = `${cfg.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
   const hasBody = body !== undefined && body !== null;
   const timeout = process.env["HASNA_MEMENTOS_API_TIMEOUT"] || DEFAULT_TIMEOUT_S;
@@ -1037,13 +1083,13 @@ x-api-key: ${cfg.apiKey}
   }
   return { status, body: respBody };
 }
-function apiJson(method, path, body) {
+function apiJson(method, path, body, options) {
   const raw = apiRequestRaw(method, path, body);
   if (raw.status >= 200 && raw.status < 300) {
     const data = raw.body.trim() ? JSON.parse(raw.body) : undefined;
     return { status: raw.status, data };
   }
-  if (raw.status === 404) {
+  if (raw.status === 404 && options?.allow404) {
     return { status: 404, data: undefined };
   }
   let msg = `mementos cloud ${method} ${path} \u2192 ${raw.status}`;
@@ -1075,8 +1121,19 @@ function toQuery(params) {
   const s = sp.toString();
   return s ? `?${s}` : "";
 }
-var ApiRequestError, DEFAULT_TIMEOUT_S = "45";
+var API_URL_ENV_KEYS, API_KEY_ENV_KEYS, DATABASE_URL_ENV_KEYS, ALLOW_REMOTE_API_IN_TESTS_ENV = "MEMENTOS_ALLOW_REMOTE_API_IN_TESTS", DB_PATH_ENV_KEYS, MementosStoreConfigError, ApiRequestError, DEFAULT_TIMEOUT_S = "45";
 var init_api_mode = __esm(() => {
+  API_URL_ENV_KEYS = ["HASNA_MEMENTOS_API_URL", "MEMENTOS_API_URL"];
+  API_KEY_ENV_KEYS = ["HASNA_MEMENTOS_API_KEY", "MEMENTOS_API_KEY"];
+  DATABASE_URL_ENV_KEYS = ["HASNA_MEMENTOS_DATABASE_URL", "MEMENTOS_DATABASE_URL"];
+  DB_PATH_ENV_KEYS = ["HASNA_MEMENTOS_DB_PATH", "MEMENTOS_DB_PATH"];
+  MementosStoreConfigError = class MementosStoreConfigError extends Error {
+    code = "MEMENTOS_STORE_CONFIG";
+    constructor(message) {
+      super(message);
+      this.name = "MementosStoreConfigError";
+    }
+  };
   ApiRequestError = class ApiRequestError extends Error {
     status;
     body;
@@ -49293,7 +49350,10 @@ function parseMemoryRow(row) {
 }
 function createMemory(input, dedupeMode = "merge", db) {
   if (!db && isApiMode()) {
-    const { data } = apiJson("POST", "/memories", { ...input, dedupe: dedupeMode });
+    const { status, data } = apiJson("POST", "/memories", { ...input, dedupe: dedupeMode });
+    if (!data || !data.id) {
+      throw new ApiRequestError(`mementos cloud POST /memories \u2192 ${status} but no memory was returned; the write did not persist (key: ${input.key})`, status, "");
+    }
     return data;
   }
   const d = db || getDatabase();
@@ -49450,7 +49510,7 @@ function listMemoriesByKey(key, db) {
 }
 function getMemory(id, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/memories/${encodeURIComponent(id)}`);
+    const { status, data } = apiJson("GET", `/memories/${encodeURIComponent(id)}`, undefined, { allow404: true });
     return status === 404 ? null : data ?? null;
   }
   const d = db || getDatabase();
@@ -49674,7 +49734,7 @@ function listMemories(filter, db) {
 }
 function updateMemory(id, input, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/memories/${encodeURIComponent(id)}`, input);
+    const { status, data } = apiJson("PATCH", `/memories/${encodeURIComponent(id)}`, input, { allow404: true });
     if (status === 404)
       throw new MemoryNotFoundError(id);
     return data;
@@ -49782,7 +49842,7 @@ function updateMemory(id, input, db) {
 }
 function deleteMemory(id, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/memories/${encodeURIComponent(id)}`);
+    const { status } = apiJson("DELETE", `/memories/${encodeURIComponent(id)}`, undefined, { allow404: true });
     return status !== 404;
   }
   const d = db || getDatabase();
@@ -49952,7 +50012,7 @@ function registerAgent(name, sessionId, description, role, projectId, db) {
 }
 function getAgent(idOrName, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/agents/${encodeURIComponent(idOrName)}`);
+    const { status, data } = apiJson("GET", `/agents/${encodeURIComponent(idOrName)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -50005,7 +50065,7 @@ function listAgentsByProject(projectId, db) {
 }
 function updateAgent(id, updates, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/agents/${encodeURIComponent(id)}`, updates);
+    const { status, data } = apiJson("PATCH", `/agents/${encodeURIComponent(id)}`, updates, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -50112,7 +50172,7 @@ function acquireLock(agentId, resourceType, resourceId, lockType = "exclusive",
 }
 function releaseLock(lockId, agentId, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/locks/${encodeURIComponent(lockId)}`, { agent_id: agentId });
+    const { status } = apiJson("DELETE", `/locks/${encodeURIComponent(lockId)}`, { agent_id: agentId }, { allow404: true });
     return status !== 404;
   }
   const d = db || getDatabase();
@@ -50321,7 +50381,7 @@ function registerProject(name, path, description, memoryPrefix, db) {
 }
 function getProject(idOrPath, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/projects/${encodeURIComponent(idOrPath)}`);
+    const { status, data } = apiJson("GET", `/projects/${encodeURIComponent(idOrPath)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -50514,7 +50574,7 @@ function createEntity(input, db) {
 }
 function getEntity(id, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/entities/${encodeURIComponent(id)}`);
+    const { status, data } = apiJson("GET", `/entities/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       throw new EntityNotFoundError(id);
     return data;
@@ -50597,7 +50657,7 @@ function listEntities(filter = {}, db) {
 }
 function updateEntity(id, input, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/entities/${encodeURIComponent(id)}`, input);
+    const { status, data } = apiJson("PATCH", `/entities/${encodeURIComponent(id)}`, input, { allow404: true });
     if (status === 404 || !data)
       throw new EntityNotFoundError(id);
     return data;
@@ -50630,7 +50690,7 @@ function updateEntity(id, input, db) {
 }
 function deleteEntity(id, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/entities/${encodeURIComponent(id)}`);
+    const { status } = apiJson("DELETE", `/entities/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404)
       throw new EntityNotFoundError(id);
     return;
@@ -52691,7 +52751,7 @@ function createRelation(input, db) {
 }
 function getRelation(id, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/relations/${encodeURIComponent(id)}`);
+    const { status, data } = apiJson("GET", `/relations/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       throw new Error(`Relation not found: ${id}`);
     return data;
@@ -52736,7 +52796,7 @@ function listRelations(filter, db) {
 }
 function deleteRelation(id, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/relations/${encodeURIComponent(id)}`);
+    const { status } = apiJson("DELETE", `/relations/${encodeURIComponent(id)}`, undefined, { allow404: true });
     if (status === 404)
       throw new Error(`Relation not found: ${id}`);
     return;

package/dist/lib/enum-validation.d.ts

@@ -0,0 +1,20 @@
+export interface EnumViolation {
+    field: string;
+    value: string;
+    allowed: readonly string[];
+}
+/** Human-readable, actionable rejection message naming the field and the accepted set. */
+export declare function formatEnumViolation(v: EnumViolation): string;
+/**
+ * Validate one enum-constrained field. Returns the violation, or `null` when
+ * the value is acceptable. `undefined`/`null` are acceptable — they mean "leave
+ * the column at its default", which is a separate concern from a bad value.
+ */
+export declare function validateEnumField(field: string, value: unknown): EnumViolation | null;
+/**
+ * Validate every enum-constrained field present on a create/update payload.
+ * Returns the first violation so the caller can fail fast with one clear
+ * message, or `null` when the payload is clean.
+ */
+export declare function validateMemoryEnums(input: Record<string, unknown>): EnumViolation | null;
+//# sourceMappingURL=enum-validation.d.ts.map

package/dist/lib/enum-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-validation.d.ts","sourceRoot":"","sources":["../../src/lib/enum-validation.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAMrF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,GAAG,IAAI,CAOxF"}