@sensigo/realm 0.23.0 → 0.24.0

package/dist/store/fs-io.d.ts

@@ -0,0 +1,65 @@
+import type { Stats } from 'node:fs';
+import { WorkflowError } from '../types/workflow-error.js';
+/**
+ * Thrown by the fs-io primitives for any non-ENOENT errno. Callers map this to a typed,
+ * domain-specific `WorkflowError` (e.g. `ENGINE_ARTIFACT_DELETE_FAILED` via
+ * {@link toArtifactDeleteFailedError} below) at the aggregate layer — this class exists only to
+ * carry the raw path + errno + cause across that boundary without losing information.
+ */
+export declare class FsIoError extends Error {
+    readonly path: string;
+    readonly code: string;
+    constructor(op: string, path: string, cause: unknown);
+}
+/**
+ * Exported ONLY so the retry policy itself can be unit-tested directly with an injected fake
+ * `op` (mocking `node:fs/promises`'s real `unlink`/`readFile`/`stat` under Vitest+ESM is brittle —
+ * "Cannot spy on export ... Module namespace is not configurable in ESM" — so the policy is
+ * decoupled from any specific fs call and tested in isolation instead). Not part of the module's
+ * intended per-call public surface (`deleteIfExists`/`readIfExists`/`statIfExists` are).
+ */
+export declare function withWin32Retry<T>(op: () => Promise<T>): Promise<T>;
+/**
+ * Deletes `path`. ENOENT → `false` (already gone — success, idempotent). Any other errno → throws
+ * {@link FsIoError}. Returns `true` if this call actually deleted the file.
+ */
+export declare function deleteIfExists(path: string): Promise<boolean>;
+/**
+ * Reads `path` as utf8. ENOENT → `undefined` (absent). Any other errno → throws {@link FsIoError}.
+ * Parsing is the CALLER's job — this returns raw bytes only.
+ */
+export declare function readIfExists(path: string): Promise<string | undefined>;
+/**
+ * Stats `path`. ENOENT → `undefined` (absent). Any other errno → throws {@link FsIoError}.
+ */
+export declare function statIfExists(path: string): Promise<Stats | undefined>;
+/**
+ * Retryable classification for the `ENGINE_ARTIFACT_DELETE_FAILED` aggregate error (issue #183):
+ * `EACCES`/`EISDIR`/`EPERM`/`EROFS` are permanent (retrying won't help — same permission/mount
+ * state); `EBUSY`/`EIO` are transient (a lock held elsewhere, a flaky disk read) — worth
+ * retrying. Any other or unknown errno defaults to `false` — conservative, since advertising a
+ * retry that might not help is worse than not advertising one that would have.
+ */
+export declare function isRetryableArtifactErrno(code: string): boolean;
+/** One artifact this store failed to delete, at the aggregate layer. */
+export interface ArtifactDeleteFailure {
+    artifact: string;
+    code: string;
+    message: string;
+}
+/**
+ * Builds the aggregate `ENGINE_ARTIFACT_DELETE_FAILED` `WorkflowError` every
+ * `PerRunArtifactStore.deleteAllForRun` implementation throws on a genuine (non-ENOENT) failure —
+ * the single typed shape `purge` (and any other caller) can rely on regardless of which store, or
+ * which internal read/delete step, actually failed. `retryable` is true iff ANY listed failure is
+ * itself retryable (a partial success followed by one transient failure is worth retrying as a
+ * whole).
+ */
+export declare function artifactDeleteFailedError(runId: string, store: string, deleted: string[], failures: ArtifactDeleteFailure[]): WorkflowError;
+/**
+ * Convenience for the common single-failure case: extracts the errno (from an {@link FsIoError}
+ * or a raw `NodeJS.ErrnoException`) and message from `err`, then wraps it via
+ * {@link artifactDeleteFailedError}.
+ */
+export declare function toArtifactDeleteFailedError(runId: string, store: string, deleted: string[], artifact: string, err: unknown): WorkflowError;
+//# sourceMappingURL=fs-io.d.ts.map

package/dist/store/fs-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-io.d.ts","sourceRoot":"","sources":["../../src/store/fs-io.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAkB3D;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CASrD;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAgBxE;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnE;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO5E;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAO3E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,qBAAqB,EAAE,GAChC,aAAa,CASf;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,OAAO,GACX,aAAa,CAIf"}

package/dist/store/fs-io.js

@@ -0,0 +1,159 @@
+// fs-io.ts — the ENOENT-discriminating filesystem primitive (issue #183).
+//
+// Every store I/O site must distinguish three outcomes, never conflate them:
+//   1. ENOENT → absence → success (idempotent: a delete of a missing file succeeds; a read of a
+//      missing file returns "absent").
+//   2. Any OTHER errno (EACCES/EPERM/EIO/EROFS/EBUSY/EISDIR/ENOTDIR/…) → THROW a typed error.
+//      ENOTDIR is corruption, not absence — it must be loud.
+//   3. Parse/JSON corruption → RECOVER (per-line skip / self-heal) + a loud structured warning.
+//      Never silence, never throw. This is the CALLER's job — these primitives return raw
+//      bytes/booleans/stats only, never parse.
+//
+// A `process.platform === 'win32'`-gated bounded retry absorbs transient EBUSY/EPERM/ENOTEMPTY —
+// the same shape Node's own `fs.rm` uses (`maxRetries`/`retryDelay`) — because Windows
+// file-locking (an antivirus scan, an open handle from another process) can make a delete/read
+// transiently fail where POSIX would succeed immediately. No retry/delay on POSIX: a genuine
+// EACCES there is not transient, and retrying would only slow down a real permission failure.
+import { unlink, readFile, stat } from 'node:fs/promises';
+import { WorkflowError } from '../types/workflow-error.js';
+const WIN32_RETRY_COUNT = 3;
+const WIN32_RETRY_DELAY_MS = 50;
+const WIN32_RETRYABLE_CODES = new Set(['EBUSY', 'EPERM', 'ENOTEMPTY']);
+/** Errno classified as transient (worth retrying) for the ENGINE_ARTIFACT_DELETE_FAILED
+ *  aggregate's `retryable` field — a lock held elsewhere, a flaky disk read. */
+const RETRYABLE_ARTIFACT_ERRNO = new Set(['EBUSY', 'EIO']);
+/** Errno classified as permanent (retrying will not help — same permission/mount state). Listed
+ *  explicitly (rather than "everything else") so the default for an unrecognized/unknown errno
+ *  stays the conservative `false` — never advertise a retry that might not help. */
+const NON_RETRYABLE_ARTIFACT_ERRNO = new Set(['EACCES', 'EISDIR', 'EPERM', 'EROFS']);
+function errnoCode(err) {
+    return err?.code;
+}
+/**
+ * Thrown by the fs-io primitives for any non-ENOENT errno. Callers map this to a typed,
+ * domain-specific `WorkflowError` (e.g. `ENGINE_ARTIFACT_DELETE_FAILED` via
+ * {@link toArtifactDeleteFailedError} below) at the aggregate layer — this class exists only to
+ * carry the raw path + errno + cause across that boundary without losing information.
+ */
+export class FsIoError extends Error {
+    path;
+    code;
+    constructor(op, path, cause) {
+        const code = errnoCode(cause) ?? 'UNKNOWN';
+        const causeMessage = cause instanceof Error ? cause.message : String(cause);
+        super(`${op} failed for '${path}' (${code}): ${causeMessage}`);
+        this.name = 'FsIoError';
+        this.path = path;
+        this.code = code;
+        if (cause instanceof Error)
+            this.cause = cause;
+    }
+}
+/**
+ * Exported ONLY so the retry policy itself can be unit-tested directly with an injected fake
+ * `op` (mocking `node:fs/promises`'s real `unlink`/`readFile`/`stat` under Vitest+ESM is brittle —
+ * "Cannot spy on export ... Module namespace is not configurable in ESM" — so the policy is
+ * decoupled from any specific fs call and tested in isolation instead). Not part of the module's
+ * intended per-call public surface (`deleteIfExists`/`readIfExists`/`statIfExists` are).
+ */
+export async function withWin32Retry(op) {
+    if (process.platform !== 'win32')
+        return op();
+    let lastErr;
+    for (let attempt = 0; attempt <= WIN32_RETRY_COUNT; attempt++) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            lastErr = err;
+            const code = errnoCode(err);
+            if (code === undefined || !WIN32_RETRYABLE_CODES.has(code))
+                throw err;
+            if (attempt < WIN32_RETRY_COUNT) {
+                await new Promise((resolve) => setTimeout(resolve, WIN32_RETRY_DELAY_MS));
+            }
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Deletes `path`. ENOENT → `false` (already gone — success, idempotent). Any other errno → throws
+ * {@link FsIoError}. Returns `true` if this call actually deleted the file.
+ */
+export async function deleteIfExists(path) {
+    try {
+        await withWin32Retry(() => unlink(path));
+        return true;
+    }
+    catch (err) {
+        if (errnoCode(err) === 'ENOENT')
+            return false;
+        throw new FsIoError('unlink', path, err);
+    }
+}
+/**
+ * Reads `path` as utf8. ENOENT → `undefined` (absent). Any other errno → throws {@link FsIoError}.
+ * Parsing is the CALLER's job — this returns raw bytes only.
+ */
+export async function readIfExists(path) {
+    try {
+        return await withWin32Retry(() => readFile(path, 'utf8'));
+    }
+    catch (err) {
+        if (errnoCode(err) === 'ENOENT')
+            return undefined;
+        throw new FsIoError('readFile', path, err);
+    }
+}
+/**
+ * Stats `path`. ENOENT → `undefined` (absent). Any other errno → throws {@link FsIoError}.
+ */
+export async function statIfExists(path) {
+    try {
+        return await withWin32Retry(() => stat(path));
+    }
+    catch (err) {
+        if (errnoCode(err) === 'ENOENT')
+            return undefined;
+        throw new FsIoError('stat', path, err);
+    }
+}
+/**
+ * Retryable classification for the `ENGINE_ARTIFACT_DELETE_FAILED` aggregate error (issue #183):
+ * `EACCES`/`EISDIR`/`EPERM`/`EROFS` are permanent (retrying won't help — same permission/mount
+ * state); `EBUSY`/`EIO` are transient (a lock held elsewhere, a flaky disk read) — worth
+ * retrying. Any other or unknown errno defaults to `false` — conservative, since advertising a
+ * retry that might not help is worse than not advertising one that would have.
+ */
+export function isRetryableArtifactErrno(code) {
+    return RETRYABLE_ARTIFACT_ERRNO.has(code) && !NON_RETRYABLE_ARTIFACT_ERRNO.has(code);
+}
+/**
+ * Builds the aggregate `ENGINE_ARTIFACT_DELETE_FAILED` `WorkflowError` every
+ * `PerRunArtifactStore.deleteAllForRun` implementation throws on a genuine (non-ENOENT) failure —
+ * the single typed shape `purge` (and any other caller) can rely on regardless of which store, or
+ * which internal read/delete step, actually failed. `retryable` is true iff ANY listed failure is
+ * itself retryable (a partial success followed by one transient failure is worth retrying as a
+ * whole).
+ */
+export function artifactDeleteFailedError(runId, store, deleted, failures) {
+    const summary = failures.map((f) => `${f.artifact} (${f.code})`).join(', ');
+    return new WorkflowError(`${store} failed to delete artifact(s) for run '${runId}': ${summary}`, {
+        code: 'ENGINE_ARTIFACT_DELETE_FAILED',
+        category: 'ENGINE',
+        agentAction: 'report_to_user',
+        retryable: failures.some((f) => isRetryableArtifactErrno(f.code)),
+        details: { runId, store, deleted, failures },
+    });
+}
+/**
+ * Convenience for the common single-failure case: extracts the errno (from an {@link FsIoError}
+ * or a raw `NodeJS.ErrnoException`) and message from `err`, then wraps it via
+ * {@link artifactDeleteFailedError}.
+ */
+export function toArtifactDeleteFailedError(runId, store, deleted, artifact, err) {
+    const code = err instanceof FsIoError ? err.code : (errnoCode(err) ?? 'UNKNOWN');
+    const message = err instanceof Error ? err.message : String(err);
+    return artifactDeleteFailedError(runId, store, deleted, [{ artifact, code, message }]);
+}
+//# sourceMappingURL=fs-io.js.map

package/dist/store/fs-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-io.js","sourceRoot":"","sources":["../../src/store/fs-io.ts"],"names":[],"mappings":"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"}

package/dist/store/json-file-store.d.ts

@@ -27,6 +27,17 @@ export interface ReconcileSummary {
         extra_live_run_ids: string[];
     }>;
 }
+/**
+ * GLOBAL LOCK ORDER (issue #184): run-file lock BEFORE key lock, never the reverse.
+ * `deleteAllForRun` is the only site that nests them (run-file lock held, key lock acquired
+ * inside it, key lock released, then the run file is deleted and the run-file lock released).
+ * Every other method that touches both takes them SEQUENTIALLY, never nested: `save()` releases
+ * its run-file lock before `registerImportedKey()` acquires the key lock; `create()` only ever
+ * takes the key lock (the run file it writes under that lock is a fresh path, not yet lockable
+ * meaningfully — no run-file lock is held during `create()`). Violating this order (acquiring a
+ * key lock and THEN a run-file lock while still holding the key lock) is the classic two-lock
+ * deadlock shape and must never be introduced.
+ */
 export declare class JsonFileStore implements RunStore, PerRunArtifactStore {
     private readonly runsDir;
     /** This store round-trips the per-claim `claims` liveness clock (issue #101). */
@@ -41,7 +52,14 @@ export declare class JsonFileStore implements RunStore, PerRunArtifactStore {
     private keyPath;
     private ensureDir;
     private ensureKeysDir;
-    /** Read a pointer file; returns undefined if absent or unparseable (self-heals via reclaim/fallback). */
+    /**
+     * Read a pointer file. Absence (ENOENT) → undefined. A genuine I/O failure (permissions, a
+     * torn mount, …) THROWS — issue #183: previously any error here, I/O or parse alike, silently
+     * self-healed to "absent," which let a real read failure masquerade as a missing pointer. Parse
+     * corruption (a torn/garbage pointer file) still self-heals to undefined — `create()` and
+     * `reconcileKeys()` both depend on that recovery — but is no longer SILENT: a loud, structured
+     * warning is emitted so an operator/log consumer can see the corruption happened.
+     */
     private readPointer;
     /** Write (or overwrite) a pointer file for `run` under `key`. params_hash is derived from the owned run. */
     private writePointer;
@@ -88,6 +106,34 @@ export declare class JsonFileStore implements RunStore, PerRunArtifactStore {
      */
     reconcileKeys(workflowId?: string, dryRun?: boolean): Promise<ReconcileSummary>;
     list(workflowId?: string): Promise<RunRecord[]>;
+    /**
+     * The raw set of run IDs present in `runsDir` (issue #163) — every `<id>.json` BASENAME, with
+     * NO record parse. Deliberately NOT `list()`: `list()` parses each file as a `RunRecord`
+     * (`JSON.parse(raw) as RunRecord`, uncaught) — a syntactically corrupt-but-PRESENT `<id>.json`
+     * would throw there, whereas here it correctly still counts as a live run (the file exists on
+     * disk; whatever reads it later is a separate concern from whether `realm run gc`'s orphan
+     * sweep should treat this run's WAL/sidecar as run-less). Using `list()` for the orphan sweep's
+     * `liveRunIds` would wrongly orphan — and reap — a live-but-corrupt run's artifacts.
+     *
+     * Concrete method, NOT on the `RunStore` interface (issue #163) — `gc` constructs a concrete
+     * `JsonFileStore` directly (as it already does for `runsDirPath`), so no external `RunStore`
+     * implementer is forced to add this.
+     *
+     * FAIL-CLOSED, load-bearing: `ENOENT` (no `runsDir` at all — nothing has ever been created) is
+     * the ONLY tolerated case, yielding an empty set (no runs exist, so nothing is "wrongly" live or
+     * orphaned). Any OTHER `readdir` error (permissions, a torn mount) THROWS — a fabricated empty
+     * set here would make the orphan sweep believe NO runs exist, and reap every live run's
+     * artifacts as "run-less." This is the single most dangerous failure mode in the whole feature;
+     * see `orphan-sweepable-store.ts`'s own doc for the matching contract on the artifact-store side.
+     */
+    listRunIds(): Promise<ReadonlySet<string>>;
+    /**
+     * Builds the `STATE_RUN_BUSY` error thrown when `deleteAllForRun` cannot proceed because
+     * another writer holds the run-file (or key) lock, or because the run is no longer terminal
+     * (issue #184). Retryable: a live writer self-heals (the lock is released), and a genuinely
+     * stale lock is eventually stolen by the next contender.
+     */
+    private runBusyError;
     /**
      * Deletes every artifact this store owns for `runId` (issue #107): the idempotency-key
      * pointer (conditionally) and the run file itself. Exact-path — ignores `dirEntries` (this
@@ -95,6 +141,15 @@ export declare class JsonFileStore implements RunStore, PerRunArtifactStore {
      *
      * Idempotent: if the run file is already gone (a concurrent purge, or a double-invocation),
      * this is a no-op, not an error.
+     *
+     * issue #184 — the resurrect-race fix: the WHOLE body runs under the run-file lock (matching
+     * `update()`/`claimStep()`), and the run's terminal state is RE-VERIFIED under that lock, not
+     * just at selection time. `RESUMABLE_PHASES ⊂ TERMINAL_PHASES` and `resume.ts` sets
+     * `terminal_state: false`, and `atomicWriteFile` (a temp write + `rename`) recreates a
+     * deleted target on `rename` — so, unlocked, a concurrent `realm resume` racing a batch purge
+     * could resurrect the run file as a LIVE run with its WAL/sidecar/pointer already gone, while
+     * purge still reported `purged`. Re-checking terminal state under the SAME lock `update()`
+     * uses closes that window: `deleteAllForRun` now unconditionally refuses a non-terminal run.
      */
     deleteAllForRun(runId: string, _dirEntries?: readonly string[]): Promise<void>;
 }

package/dist/store/json-file-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-file-store.d.ts","sourceRoot":"","sources":["../../src/store/json-file-store.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAyBvE,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,eAAe,EAAE,KAAK,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC,CAAC;IACH,mFAAmF;IACnF,kBAAkB,EAAE,KAAK,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,gBAAgB,EAAE,MAAM,CAAC;QACzB,kBAAkB,EAAE,MAAM,EAAE,CAAC;KAC9B,CAAC,CAAC;CACJ;AA2BD,qBAAa,aAAc,YAAW,QAAQ,EAAE,mBAAmB;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,iFAAiF;IACjF,QAAQ,CAAC,cAAc,QAAQ;gBAEnB,OAAO,CAAC,EAAE,MAAM;IAI5B,qDAAqD;IACrD,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,OAAO,CAAC,QAAQ;IAIhB,sGAAsG;IACtG,OAAO,CAAC,OAAO;IAIf,wDAAwD;IACxD,OAAO,CAAC,OAAO;YAKD,SAAS;YAIT,aAAa;IAI3B,yGAAyG;YAC3F,WAAW;IASzB,4GAA4G;YAC9F,YAAY;IAW1B,6EAA6E;YAC/D,aAAa;IAwB3B,wGAAwG;YAC1F,sBAAsB;IAS9B,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,SAAS,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IA6DtF;;;;;OAKG;YACW,SAAS;IAUvB,2GAA2G;IAC3G,OAAO,CAAC,gBAAgB;IAUlB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAoCtC,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAuD7C,SAAS,CACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,SAAS,CAAC;IA0ErB;;;;;;;OAOG;IAIG,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAyC5C;;;;OAIG;YACW,mBAAmB;IA8BjC;;;;;OAKG;IACG,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA4D7E,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAiCrD;;;;;;;OAOG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA2BrF"}
+{"version":3,"file":"json-file-store.d.ts","sourceRoot":"","sources":["../../src/store/json-file-store.ts"],"names":[],"mappings":"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"}