@cavelang/store 0.27.14 → 0.29.1

package/dist/src/schema.js

@@ -1,8 +1,7 @@
-/**
- * Storage schema (spec §13.1, §13.2) — verbatim from the specification,
- * with `IF NOT EXISTS` added so opening an existing database is idempotent.
- */
-export const ddl = `
+/** Ordered, transactional storage schema migrations (spec §13). */
+import * as Provenance from "./provenance.js";
+export const currentVersion = 1;
+const ddlBeforeFts = `
 CREATE TABLE IF NOT EXISTS cave_claim (
   id            TEXT PRIMARY KEY,      -- UUIDv7
   tx            TEXT NOT NULL,         -- UUIDv7, lexicographic = transaction order
@@ -47,6 +46,15 @@ CREATE TABLE IF NOT EXISTS cave_context (
 CREATE INDEX IF NOT EXISTS idx_cave_context ON cave_context (context);
 CREATE INDEX IF NOT EXISTS idx_cave_context_claim ON cave_context (claim_id, context);
 
+CREATE TABLE IF NOT EXISTS cave_provenance (
+  claim_id   TEXT NOT NULL,
+  dimension  TEXT NOT NULL CHECK (dimension IN ('actor', 'source', 'run', 'domain')),
+  value      TEXT NOT NULL,
+  PRIMARY KEY (claim_id, dimension, value),
+  FOREIGN KEY (claim_id) REFERENCES cave_claim(id)
+);
+CREATE INDEX IF NOT EXISTS idx_cave_provenance_lookup ON cave_provenance (dimension, value, claim_id);
+
 CREATE TABLE IF NOT EXISTS cave_tag (
   claim_id TEXT NOT NULL,
   key      TEXT NOT NULL,
@@ -67,12 +75,106 @@ CREATE INDEX IF NOT EXISTS idx_cave_edge_parent ON cave_edge (parent_id);
 CREATE INDEX IF NOT EXISTS idx_cave_edge_child  ON cave_edge (child_id);
 CREATE INDEX IF NOT EXISTS idx_cave_edge_role   ON cave_edge (role);
 
-CREATE VIRTUAL TABLE IF NOT EXISTS cave_fts USING fts5(
+`;
+const ftsDdl = (fullText) => `
+CREATE VIRTUAL TABLE IF NOT EXISTS cave_fts USING ${fullText}(
   claim_id, subject, verb, object, attribute, value_text, comment, raw_line
 );
 `;
-/** Creates all tables and indexes. */
-export const init = (db) => {
-    db.exec(ddl);
+/** Default Node/FTS5 schema SQL retained for callers that inspect the DDL. */
+export const ddl = ddlBeforeFts + ftsDdl('fts5');
+const ddlFor = (capabilities) => ddlBeforeFts + ftsDdl(capabilities.fullText);
+const migrations = [
+    {
+        version: 1,
+        up: (db, capabilities) => {
+            db.exec(ddlFor(capabilities));
+            Provenance.backfill(db);
+        }
+    }
+];
+const versionOf = (db) => db.prepare('PRAGMA user_version').get().user_version;
+const requiredTables = [
+    'cave_claim', 'cave_context', 'cave_provenance', 'cave_tag', 'cave_edge', 'cave_fts'
+];
+const requiredIndexes = [
+    'idx_cave_claim_key_tx', 'idx_cave_subject', 'idx_cave_verb', 'idx_cave_object',
+    'idx_cave_attribute', 'idx_cave_conf', 'idx_cave_context', 'idx_cave_context_claim',
+    'idx_cave_provenance_lookup', 'idx_cave_tag_key', 'idx_cave_tag_claim',
+    'idx_cave_edge_parent', 'idx_cave_edge_child', 'idx_cave_edge_role'
+];
+const requiredColumns = {
+    cave_claim: [
+        'id', 'tx', 'subject', 'verb', 'negated', 'object', 'attribute', 'value_text',
+        'value_num', 'value_unit', 'value_approx', 'delta_text', 'delta_num', 'delta_unit',
+        'sigma_level', 'conf', 'importance', 'comment', 'raw_line', 'claim_key'
+    ],
+    cave_context: ['claim_id', 'context'],
+    cave_provenance: ['claim_id', 'dimension', 'value'],
+    cave_tag: ['claim_id', 'key', 'value'],
+    cave_edge: ['parent_id', 'role', 'child_id'],
+    cave_fts: ['claim_id', 'subject', 'verb', 'object', 'attribute', 'value_text', 'comment', 'raw_line']
+};
+export const validate = (db, version, schema = 'main') => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(schema)) {
+        throw new Error(`CAVE: invalid SQLite schema name ${JSON.stringify(schema)}`);
+    }
+    const objects = new Map(db.prepare(`SELECT name, type FROM ${schema}.sqlite_schema WHERE name LIKE 'cave_%' OR name LIKE 'idx_cave_%'`)
+        .all().map(row => [row.name, row.type]));
+    const problems = [
+        ...requiredTables.flatMap(name => objects.has(name) ? [] : [`missing table ${name}`]),
+        ...requiredIndexes.flatMap(name => objects.get(name) === 'index' ? [] : [`missing index ${name}`]),
+        ...Object.entries(requiredColumns).flatMap(([table, required]) => {
+            if (!objects.has(table)) {
+                return [];
+            }
+            const columns = new Set(db.prepare(`PRAGMA ${schema}.table_info(${table})`).all().map(row => row.name));
+            return required.flatMap(column => columns.has(column) ? [] : [`missing column ${table}.${column}`]);
+        })
+    ];
+    if (problems.length > 0) {
+        throw new Error(`CAVE: schema version ${version} is incompatible: ${problems.join(', ')}`);
+    }
+};
+/**
+ * Upgrade every supported older version in order. Each step owns one SQLite
+ * transaction, including its `user_version` update, so interruption leaves
+ * either the old version or the complete next version and reopen can resume.
+ */
+export const init = (db, capabilities = {
+    transactions: { immediate: true, savepoints: true },
+    fullText: 'fts5',
+}) => {
+    let version = versionOf(db);
+    if (version > currentVersion) {
+        throw new Error(`CAVE: schema version ${version} is newer than this runtime supports (${currentVersion}); upgrade CAVE`);
+    }
+    for (const migration of migrations) {
+        if (migration.version <= version) {
+            continue;
+        }
+        if (migration.version !== version + 1) {
+            throw new Error(`CAVE: no schema migration path from version ${version} to ${migration.version}`);
+        }
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            migration.up(db, capabilities);
+            db.exec(`PRAGMA user_version = ${migration.version}`);
+            validate(db, migration.version);
+            db.exec('COMMIT');
+            version = migration.version;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch {
+                // SQLite may already have rolled back a failed statement.
+            }
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`CAVE: schema migration ${version} -> ${migration.version} failed: ${detail}`);
+        }
+    }
+    validate(db, version);
 };
 //# sourceMappingURL=schema.js.map

package/dist/src/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,CAAC,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoElB,CAAA;AAED,sCAAsC;AACtC,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EAAgB,EAAQ,EAAE;IAC7C,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACd,CAAC,CAAA"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/src/sensitivity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sensitivity labels and row visibility (spec §9.7).
+ *
+ * Claims opt into a level with `#sensitivity:<level>`. Unlabelled rows are
+ * `internal`; malformed, flat, or unknown labels fail closed as `restricted`.
+ * Several labels on one row resolve to the most restrictive one.
+ */
+export declare const levels: readonly ["public", "internal", "confidential", "restricted"];
+export type Level = (typeof levels)[number];
+export declare const defaultLevel: Level;
+export declare const defaultMaximum: Level;
+export declare const parse: (value: string) => undefined | Level;
+export declare const rank: (level: Level) => number;
+/**
+ * SQL predicate that allows rows at or below `maximum`. `alias` must be a
+ * trusted SQL identifier supplied by CAVE code, never user input.
+ */
+export declare const sql: (alias: string, maximum?: Level) => string;
+/** Most restrictive recognized label; malformed labels are `restricted`. */
+export declare const ofTags: (tags: readonly {
+    key: string;
+    value?: null | string;
+}[]) => Level;
+//# sourceMappingURL=sensitivity.d.ts.map

package/dist/src/sensitivity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitivity.d.ts","sourceRoot":"","sources":["../../src/sensitivity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,MAAM,+DAAgE,CAAA;AACnF,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3C,eAAO,MAAM,YAAY,EAAE,KAAkB,CAAA;AAC7C,eAAO,MAAM,cAAc,EAAE,KAAkB,CAAA;AAE/C,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,SAAS,GAAG,KACY,CAAA;AAE9D,eAAO,MAAM,IAAI,GAAI,OAAO,KAAK,KAAG,MAA+B,CAAA;AAEnE;;;GAGG;AACH,eAAO,MAAM,GAAG,GAAI,OAAO,MAAM,EAAE,UAAS,KAAsB,KAAG,MAGoD,CAAA;AAEzH,4EAA4E;AAC5E,eAAO,MAAM,MAAM,GAAI,MAAM,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;CAAE,EAAE,KAAG,KAYhF,CAAA"}

package/dist/src/sensitivity.js

@@ -0,0 +1,34 @@
+/**
+ * Sensitivity labels and row visibility (spec §9.7).
+ *
+ * Claims opt into a level with `#sensitivity:<level>`. Unlabelled rows are
+ * `internal`; malformed, flat, or unknown labels fail closed as `restricted`.
+ * Several labels on one row resolve to the most restrictive one.
+ */
+export const levels = ['public', 'internal', 'confidential', 'restricted'];
+export const defaultLevel = 'internal';
+export const defaultMaximum = 'internal';
+export const parse = (value) => levels.includes(value) ? value : undefined;
+export const rank = (level) => levels.indexOf(level);
+/**
+ * SQL predicate that allows rows at or below `maximum`. `alias` must be a
+ * trusted SQL identifier supplied by CAVE code, never user input.
+ */
+export const sql = (alias, maximum = defaultMaximum) => `COALESCE((SELECT MAX(CASE s.value ` +
+    `WHEN 'public' THEN 0 WHEN 'internal' THEN 1 WHEN 'confidential' THEN 2 WHEN 'restricted' THEN 3 ELSE 3 END) ` +
+    `FROM cave_tag s WHERE s.claim_id = ${alias}.id AND s.key = 'sensitivity'), ${rank(defaultLevel)}) <= ${rank(maximum)}`;
+/** Most restrictive recognized label; malformed labels are `restricted`. */
+export const ofTags = (tags) => {
+    let effective;
+    for (const tag of tags) {
+        if (tag.key !== 'sensitivity') {
+            continue;
+        }
+        const level = tag.value === undefined || tag.value === null ? 'restricted' : parse(tag.value) ?? 'restricted';
+        if (effective === undefined || rank(level) > rank(effective)) {
+            effective = level;
+        }
+    }
+    return effective ?? defaultLevel;
+};
+//# sourceMappingURL=sensitivity.js.map

package/dist/src/sensitivity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitivity.js","sourceRoot":"","sources":["../../src/sensitivity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,CAAU,CAAA;AAGnF,MAAM,CAAC,MAAM,YAAY,GAAU,UAAU,CAAA;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAU,UAAU,CAAA;AAE/C,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAa,EAAqB,EAAE,CACxD,MAAM,CAAC,QAAQ,CAAC,KAAc,CAAC,CAAC,CAAC,CAAC,KAAc,CAAC,CAAC,CAAC,SAAS,CAAA;AAE9D,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAY,EAAU,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAEnE;;;GAGG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,UAAiB,cAAc,EAAU,EAAE,CAC5E,oCAAoC;IACpC,8GAA8G;IAC9G,sCAAsC,KAAK,mCAAmC,IAAI,CAAC,YAAY,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,EAAE,CAAA;AAEzH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAuD,EAAS,EAAE;IACvF,IAAI,SAA4B,CAAA;IAChC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,GAAG,KAAK,aAAa,EAAE,CAAC;YAC9B,SAAQ;QACV,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,YAAY,CAAA;QAC7G,IAAI,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7D,SAAS,GAAG,KAAK,CAAA;QACnB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,IAAI,YAAY,CAAA;AAClC,CAAC,CAAA"}

package/dist/src/store.d.ts

@@ -1,15 +1,15 @@
 /**
  * The CAVE store (spec §13) — append-only claim persistence on the Node.js
- * builtin `node:sqlite`.
+ * through an explicit synchronous SQLite adapter.
  *
  * - one row per fact, canonical direction; inverses are query-time views
  *   over existing indexes, never materialized rows (spec §13.3);
  * - current belief = latest tx per claim key (spec §9.1, §13.5);
  * - the verb registry is rebuilt from stored in-band declaration claims on
- *   open, so a reopened database keeps its inverse vocabulary;
+ *   open, so a reopened database keeps its inverse and lifecycle vocabulary;
  * - full-text search over subjects, objects, values, comments and raw
  *   lines via FTS5;
- * - appends can stamp actor provenance (spec §9.5): pass `source` and every
+ * - appends record actor provenance and keep compatibility stamps (spec §9.5): pass `source` and every
  *   claim without a `src:` context gets `@src:<actor>` — applied before the
  *   claim key is computed, so different actors keep separate belief series;
  * - contradiction resolution (spec §26): coexisting series about one fact
@@ -17,11 +17,14 @@
  *   confidence and tx — `resolvedBeliefs`, `contested`, and the `resolve`
  *   traversal opt-in.
  */
-import { DatabaseSync } from 'node:sqlite';
-import { Claim } from '@cavelang/core';
+import { Claim, Context } from '@cavelang/core';
 import * as Canonical from '@cavelang/canonical';
+import type { Adapter } from './adapter.ts';
 import * as Resolve from './resolve.ts';
 import * as Row from './row.ts';
+import * as Sensitivity from './sensitivity.ts';
+import * as Provenance from './provenance.ts';
+import * as Record from './record.ts';
 export type IngestResult = {
     /** ids of the batch's claim rows, in document order — for a row skipped as already present (`ids` replay, spec §28.1), the existing id. */
     readonly ids: readonly string[];
@@ -33,7 +36,8 @@ export type IngestResult = {
 };
 export type AppendOptions = {
     /**
-     * Actor provenance (spec §9.5): stamp `@src:<source>` on every appended
+     * Actor provenance (spec §9.5): record actor `<source>` and stamp
+     * `@src:<source>` on every appended
      * claim that carries no `src:` context — e.g. `cli`, `agent/claude-code`,
      * `ingest/93a01c626b3f`. Applied before the claim key is computed, so the
      * stamp is part of claim identity; claims that already name a source keep
@@ -42,15 +46,23 @@ export type AppendOptions = {
      */
     readonly source?: string;
     /**
-     * Lifecycle stamping (spec §9.5): stamp `@src:<source>` even when the
+     * Lifecycle ownership (spec §9.5.1): record run `<source>` and stamp
+     * `@src:<source>` even when the
      * claim already names a source. Connect records, rule conclusions and
-     * action effects are found for retraction and attribution by their
-     * stamp, so an authored `src:` context must not displace it — both are
-     * kept (multi-source rows resolve per §26.3). The exact stamp context
+     * action effects are found for retraction and attribution by their run,
+     * so an authored `src:` context must not displace it — both contexts are
+     * kept for compatibility (multi-source rows resolve per §26.3). The exact stamp context
      * is never duplicated. Without this flag an authored source suppresses
      * the stamp.
      */
     readonly lifecycle?: boolean;
+    /**
+     * Additional structured contexts applied to every row before keying. Used
+     * by connectors to attach source spans without rewriting generated text.
+     */
+    readonly contexts?: readonly Context.t[];
+    /** Explicit provenance dimensions; compact contexts remain unchanged. */
+    readonly provenance?: Provenance.Input;
     /**
      * Explicit row identity (spec §28.1), index-aligned with the result's
      * claims: a claim with an id here is replayed under it — inserted with
@@ -109,13 +121,17 @@ export declare const defaultDbPath: () => string;
  * already stored; pass `Canonical.Registry.empty` for a declaration-free
  * start.
  */
-export declare const open: (path?: string, options?: {
+export declare const open: (adapter: Adapter, path?: string, options?: {
     registry?: Canonical.Registry.t;
 }) => {
-    /** Raw database handle — used by `@cavelang/query`; treat as read-only. */
-    db: DatabaseSync;
+    /** Adapter that owns this database connection and its capabilities. */
+    adapter: Adapter;
+    /** Raw adapter database handle — used by `@cavelang/query`; treat as read-only. */
+    db: import("./adapter.ts").Database;
     /** Current verb registry (input registry + stored + ingested declarations). */
     registry: () => Canonical.Registry.t;
+    /** Configured registry before any in-band declarations are applied. */
+    baseRegistry: () => Canonical.Registry.t;
     /**
      * Rebuilds the registry from the base plus stored declarations — after
      * rows arrive outside `ingest`/`insertResult` (a §28 merge writes
@@ -198,6 +214,12 @@ export declare const open: (path?: string, options?: {
     byTag(key: string, value?: string): Row.t[];
     /** Rows carrying a context (spec §13.5), newest first. */
     byContext(context: string): Row.t[];
+    /** Rows carrying one explicit provenance dimension, newest first. */
+    byProvenance(dimension: Provenance.Dimension, value: string): Row.t[];
+    /** Explicit actor, physical source, lifecycle run, and domain metadata. */
+    provenanceOf: (row: Row.t | string) => Provenance.t;
+    /** Map a database-shaped row to the stable `cave.claim/v1` contract. */
+    recordOf: (row: Row.t) => Record.t;
     /** Members of a topic — forward `CONTAINS` traversal (spec §11.2). */
     topicMembers(topic: string, options_?: TraverseOptions): string[];
     /** Topics containing an entity — the inverse `CONTAINS` read (spec §11.2). */
@@ -212,6 +234,7 @@ export declare const open: (path?: string, options?: {
     search(query: string, options_?: {
         raw?: boolean;
         limit?: number;
+        maxSensitivity?: Sensitivity.Level;
     }): Row.t[];
     /**
      * Appends edges between *existing* claim rows (spec §13.2) — the
@@ -249,6 +272,7 @@ export declare const open: (path?: string, options?: {
     exportText(options_?: {
         current?: boolean;
         tx?: boolean;
+        maxSensitivity?: Sensitivity.Level;
     }): string;
     close(): void;
 };

package/dist/src/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,KAAK,EAA8B,MAAM,gBAAgB,CAAA;AAClE,OAAO,KAAK,SAAS,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAwD/B,MAAM,MAAM,YAAY,GAAG;IACzB,2IAA2I;IAC3I,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,CAAC,OAAO,EAAE,CAAA;CAChD,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,SAAS,GAAG,MAAM,CAAC,EAAE,CAAA;CAC/C,CAAA;AAgBD,MAAM,MAAM,WAAW,GAAG;IACxB,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAA;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAO,MACI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,OAAM,MAAmB,EAAE,UAAS;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAA;CAAO;IAkM7F,2EAA2E;;IAG3E,+EAA+E;oBACjE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAElC;;;;;OAKG;sBACe,IAAI;IAKtB;;;;;OAKG;kBApJgB,CAAC,QAAQ,MAAM,CAAC,KAAG,CAAC;IAuJvC;;;;;OAKG;iBACU,MAAM,aAAY;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,aAAa,GAAQ,YAAY;IASvF,+CAA+C;2BA/InB,SAAS,CAAC,MAAM,aAAY,aAAa,KAAQ,YAAY;IAkJzF,2DAA2D;8BAClC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAQ,GAAG,CAAC,CAAC,EAAE;IAM5D,4EAA4E;4BACpD,MAAM,GAAG,SAAS,GAAG,GAAG,CAAC,CAAC;IAOlD,qEAAqE;sBACnD,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE;IAIlC;;;;OAIG;wBACiB,OAAO,CAAC,KAAK,EAAE;IAInC;;;;;;OAMG;+BACuB;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAQ,GAAG,CAAC,CAAC,EAAE;IAM9D;;;;;;OAMG;yBACiB;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAQ,OAAO,CAAC,SAAS,EAAE;IAkBpE;;;;;OAKG;sBACe,MAAM,GAAG,MAAM,EAAE;IAMnC,4EAA4E;wBACxD,MAAM,aAAY;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAQ,GAAG,CAAC,CAAC,EAAE;IAW1E,qFAAqF;oBACrE,MAAM,aAAY,eAAe,GAAQ,WAAW,EAAE;IAOtE;;;;OAIG;oBACa,MAAM,aAAY,eAAe,GAAQ,WAAW,EAAE;IAUtE,oFAAoF;eACzE,MAAM,UAAU,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE;IAU3C,0DAA0D;uBACvC,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE;IAMnC,sEAAsE;wBAClD,MAAM,aAAY,eAAe,GAAQ,MAAM,EAAE;IAOrE,8EAA8E;qBAC7D,MAAM,aAAY,eAAe,GAAQ,MAAM,EAAE;IAOlE;;;;;;OAMG;kBACW,MAAM,aAAY;QAAE,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAQ,GAAG,CAAC,CAAC,EAAE;IAUhF;;;;;;;OAOG;uBACgB,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI;IAQpG,4DAA4D;sBAC1C,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAA;KAAE,EAAE;IAO3D,6EAA6E;mBA7QzD,GAAG,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC;IAgRnC;;;;;;;;;;;;OAYG;0BACkB;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GAAQ,MAAM;aAsC7D,IAAI;CAIhB,CAAA"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"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"}