@cavelang/cli 0.35.0 → 0.36.0

package/dist/internal/sync/sync.d.ts

@@ -3,8 +3,9 @@
  *
  * A row's UUIDv7 — one value serving as both `id` and `tx` — is its global
  * identity (§28.1): merging copies rows absent by id verbatim (side tables
- * included) and skips rows the target already has, which makes sync
- * idempotent, transitive and bidirectional, and can never conflict —
+ * included) and skips matching rows the target already has. A reused id
+ * with different content is rejected. Valid replicas are idempotent,
+ * transitive and bidirectional —
  * coexisting contradictions are legal data (§9.4), resolved at read time
  * (§26). Merged transaction ids feed the generator's receive rule (§28.2),
  * so everything appended after a merge sorts after everything merged,
@@ -34,6 +35,7 @@ export type SyncOptions = {
     readonly dryRun?: boolean;
 };
 export type SyncProblem = {
+    /** Source text line, or zero for a database-source problem. */
     readonly line: number;
     readonly message: string;
 };
@@ -47,12 +49,12 @@ export type SyncReport = {
     readonly dryRun: boolean;
     /** The §28.3 merge record appended, when the merge was effective and records are on. */
     readonly record?: string;
-    /** Text-source problems (spec §28.4 strictness); nothing merges when non-empty. */
+    /** Source identity or text-validation problems; nothing merges when non-empty. */
     readonly problems: readonly SyncProblem[];
 };
 /**
  * @returns text usable as one entity token in a §28.3 record subject:
- * whitespace and comment/metadata sigils normalized to `-`, never empty.
+ * whitespace, literal delimiters, attribute colons and comment/metadata sigils normalized to `-`, never empty.
  */
 export declare const sanitizeLabel: (text: string) => string;
 /**
@@ -66,7 +68,8 @@ export declare const labelOf: (path: string) => string;
  * tags, FTS — edges dedupe against stored edges, merged in-band
  * declarations reload the registry, and the generator observes the merged
  * transaction ids (§28.2). Idempotent: a re-run merges nothing and appends
- * no record.
+ * no record. Conflicting existing identities reject the whole source before
+ * copying, with database problems reported at line zero.
  */
 export declare const syncDb: (store: Store, sourcePath: string, options?: SyncOptions) => SyncReport;
 /**

package/dist/internal/sync/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,EAAsB,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAE7E,OAAO,EAAE,WAAW,EAAE,CAAA;AAEtB,MAAM,MAAM,WAAW,GAAG;IACxB,oHAAoH;IACpH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;CAC1C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAG5C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,MAGtC,CAAA;AA4CD;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,EAAE,YAAY,MAAM,EAAE,UAAS,WAAgB,KAAG,UAyIpF,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,KAAK,EAAE,MAAM,MAAM,EAAE,UAAS,WAAgB,KAAG,UAsEhF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,KAAK,EAAE,YAAY,MAAM,EAAE,UAAS,WAAgB,KAAG,UAKtF,CAAA"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,EAA2B,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAElF,OAAO,EAAE,WAAW,EAAE,CAAA;AAEtB,MAAM,MAAM,WAAW,GAAG;IACxB,oHAAoH;IACpH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;CAC1C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAG5C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,MAGtC,CAAA;AA+DD;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,EAAE,YAAY,MAAM,EAAE,UAAS,WAAgB,KAAG,UAmRpF,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,KAAK,EAAE,MAAM,MAAM,EAAE,UAAS,WAAgB,KAAG,UAOhF,CAAA;AAsID;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,KAAK,EAAE,YAAY,MAAM,EAAE,UAAS,WAAgB,KAAG,UAgBtF,CAAA"}

package/dist/internal/sync/sync.js

@@ -3,8 +3,9 @@
  *
  * A row's UUIDv7 — one value serving as both `id` and `tx` — is its global
  * identity (§28.1): merging copies rows absent by id verbatim (side tables
- * included) and skips rows the target already has, which makes sync
- * idempotent, transitive and bidirectional, and can never conflict —
+ * included) and skips matching rows the target already has. A reused id
+ * with different content is rejected. Valid replicas are idempotent,
+ * transitive and bidirectional —
  * coexisting contradictions are legal data (§9.4), resolved at read time
  * (§26). Merged transaction ids feed the generator's receive rule (§28.2),
  * so everything appended after a merge sorts after everything merged,
@@ -21,17 +22,18 @@
  * `store/<from> SYNCED-INTO store/<into> @src:sync` — whose belief series
  * is the sync log; a merge that changed nothing appends nothing.
  */
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { Uuidv7 } from '@cavelang/core';
+import { errorMessage } from "./error-message.js";
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { Claim, Key, Uuidv7 } from '@cavelang/core';
 import * as Canonical from '@cavelang/canonical';
-import { Provenance, Schema, isStoreFile } from '@cavelang/store';
+import { Provenance, Row, Schema, isStoreFile } from '@cavelang/store';
 export { isStoreFile };
 /**
  * @returns text usable as one entity token in a §28.3 record subject:
- * whitespace and comment/metadata sigils normalized to `-`, never empty.
+ * whitespace, literal delimiters, attribute colons and comment/metadata sigils normalized to `-`, never empty.
  */
 export const sanitizeLabel = (text) => {
-    const label = text.replaceAll(/[\s;@#]+/g, '-');
+    const label = text.replaceAll(/[\s;:@#"`]+/g, '-');
     return label === '' ? 'store' : label;
 };
 /**
@@ -65,7 +67,7 @@ const rolledBack = (store, body) => {
  * §9.5 path.
  */
 const appendRecord = (store, from, into, merged, edges) => {
-    const declared = store.db.prepare("SELECT 1 FROM cave_claim WHERE subject = 'SYNCED-INTO' AND verb = 'IS' AND object = 'verb' AND negated = 0 LIMIT 1").get() !== undefined;
+    const declared = Canonical.Registry.isDeclared(store.registry(), 'SYNCED-INTO');
     const line = `store/${sanitizeLabel(from)} SYNCED-INTO store/${sanitizeLabel(into)} ; +${merged} claim(s), +${edges} edge(s)`;
     const text = declared ?
         line :
@@ -80,40 +82,85 @@ const claimColumns = [
     'delta_text', 'delta_num', 'delta_unit', 'sigma_level',
     'conf', 'importance', 'comment', 'raw_line', 'claim_key'
 ].join(', ');
+/** Preserve operation failures when releasing a sync-owned SQL resource also fails. */
+const withSyncCleanup = (run, cleanup) => {
+    let result;
+    try {
+        result = run();
+    }
+    catch (error) {
+        try {
+            cleanup();
+        }
+        catch (cleanupError) {
+            const messages = [error, cleanupError].map(errorMessage);
+            throw new AggregateError([error, cleanupError], `database sync failed: ${messages[0]}; cleanup also failed: ${messages[1]}`, { cause: error });
+        }
+        throw error;
+    }
+    cleanup();
+    return result;
+};
+const booleanOption = (value, name, fallback) => {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw new TypeError(`${name} must be a boolean`);
+    return value;
+};
 /**
  * Merges another CAVE store file into `store` (spec §28.1): rows absent by
  * id are copied verbatim — `id`, `tx`, `claim_key`, `raw_line`, contexts,
  * tags, FTS — edges dedupe against stored edges, merged in-band
  * declarations reload the registry, and the generator observes the merged
  * transaction ids (§28.2). Idempotent: a re-run merges nothing and appends
- * no record.
+ * no record. Conflicting existing identities reject the whole source before
+ * copying, with database problems reported at line zero.
  */
 export const syncDb = (store, sourcePath, options = {}) => {
+    const dryRun = booleanOption(options.dryRun, 'dryRun', false);
+    const recordEnabled = booleanOption(options.record, 'record', true);
     if (!existsSync(sourcePath)) {
         // ATTACH would create an empty database at the missing path.
         throw new Error(`${sourcePath}: no such file`);
     }
     const db = store.db;
-    const dryRun = options.dryRun === true;
+    const from = options.from ?? 'origin';
+    const into = options.into ?? 'local';
     const mainFile = db.prepare("SELECT file FROM pragma_database_list WHERE name = 'main'").get().file;
-    if (mainFile !== '' && realpathSync(sourcePath) === realpathSync(mainFile)) {
+    const sameFile = () => {
+        if (mainFile === '')
+            return false;
+        if (realpathSync(sourcePath) === realpathSync(mainFile))
+            return true;
+        const source = statSync(sourcePath);
+        const main = statSync(mainFile);
+        return source.dev === main.dev && source.ino === main.ino;
+    };
+    if (sameFile()) {
         // Attaching the store to itself would deadlock on its own lock; a
         // store trivially holds every row it holds.
         return { merged: 0, skipped: 0, edges: 0, dryRun, problems: [] };
     }
+    // SQLite cannot detach an attachment read by an uncommitted outer transaction.
+    store.transaction(({ outermost }) => {
+        if (!outermost) {
+            throw new Error('database sync cannot run inside a caller-owned transaction; sync after it commits or use annotated-text sync');
+        }
+    });
     try {
         db.prepare('ATTACH DATABASE ? AS cave_sync_src').run(sourcePath);
     }
-    catch {
-        throw new Error(`${sourcePath}: not a CAVE store (not a SQLite database)`);
+    catch (cause) {
+        throw new Error(`${sourcePath}: cannot attach sync source: ${errorMessage(cause)}`, { cause });
     }
-    try {
+    return withSyncCleanup(() => {
         let isStore = false;
         try {
             isStore = db.prepare("SELECT 1 FROM cave_sync_src.sqlite_master WHERE type = 'table' AND name = 'cave_claim'").get() !== undefined;
         }
-        catch {
-            isStore = false;
+        catch (cause) {
+            throw new Error(`${sourcePath}: cannot inspect sync source: ${errorMessage(cause)}`, { cause });
         }
         if (!isStore) {
             throw new Error(`${sourcePath}: not a CAVE store (no cave_claim table)`);
@@ -123,20 +170,150 @@ export const syncDb = (store, sourcePath, options = {}) => {
             throw new Error(`${sourcePath}: schema version ${sourceVersion} is newer than this runtime supports ` +
                 `(${Schema.currentVersion}); upgrade CAVE`);
         }
-        if (sourceVersion === Schema.currentVersion) {
+        if (sourceVersion >= 1) {
             try {
                 Schema.validate(db, sourceVersion, 'cave_sync_src');
             }
             catch (error) {
-                throw new Error(`${sourcePath}: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`${sourcePath}: ${errorMessage(error)}`, { cause: error });
             }
         }
+        const hasProvenance = db.prepare(`
+      SELECT 1 FROM cave_sync_src.sqlite_master
+      WHERE type = 'table' AND name = 'cave_provenance'
+    `).get() !== undefined;
         const body = () => {
+            const references = [
+                ['cave_context', ['claim_id']], ['cave_tag', ['claim_id']],
+                ['cave_edge', ['parent_id', 'child_id']],
+                ...(hasProvenance ? [['cave_provenance', ['claim_id']]] : [])
+            ];
+            for (const [table, fields] of references) {
+                // Validate source relationships independently of what the target contains.
+                // Explicit queries also cover legacy tables without declared foreign keys.
+                const missing = fields.map(field => `NOT EXISTS (SELECT 1 FROM cave_sync_src.cave_claim c WHERE c.id = s.${field})`).join(' OR ');
+                if (db.prepare(`SELECT 1 FROM cave_sync_src.${table} s WHERE ${missing} LIMIT 1`).get() !== undefined) {
+                    return { merged: 0, skipped: 0, edges: 0, dryRun, problems: [{ line: 0,
+                                message: `source ${table} contains references to missing claims` }] };
+                }
+            }
+            if (db.prepare(`SELECT 1 FROM cave_sync_src.cave_edge
+        WHERE role IS NULL OR role NOT IN ('WHEN', 'VIA', 'BECAUSE', 'QUALIFIES') LIMIT 1`).get() !== undefined) {
+                return { merged: 0, skipped: 0, edges: 0, dryRun, problems: [{ line: 0,
+                            message: 'source contains an invalid edge role — expected WHEN, VIA, BECAUSE or QUALIFIES' }] };
+            }
+            const identities = db.prepare('SELECT id, tx FROM cave_sync_src.cave_claim ORDER BY id').all();
+            const invalid = identities.filter(row => !Uuidv7.is(row.id) || row.tx !== row.id);
+            if (invalid.length > 0) {
+                return { merged: 0, skipped: 0, edges: 0, dryRun, problems: invalid.map(row => ({
+                        line: 0,
+                        message: `row ${JSON.stringify(row.id)} has invalid transaction identity — expected id = tx as a canonical lowercase UUIDv7 (spec §28.1)`,
+                    })) };
+            }
+            if (hasProvenance) {
+                const malformed = db.prepare(`
+          SELECT DISTINCT claim_id AS id FROM cave_sync_src.cave_provenance
+          WHERE typeof(value) <> 'text' OR value = '' ORDER BY claim_id
+        `).all();
+                if (malformed.length > 0) {
+                    return { merged: 0, skipped: 0, edges: 0, dryRun, problems: malformed.map(row => ({
+                            line: 0,
+                            message: `row ${JSON.stringify(row.id)} has invalid stored provenance — values must be nonempty text`,
+                        })) };
+                }
+            }
+            // Compare persisted claim data under the same reservation as the copy.
+            // Raw spelling can change during text replay; metadata order is immaterial.
+            // Keep normalized value fields and claim_key in the comparison: divergent
+            // query data must not hide behind equal emitted text.
+            const columns = claimColumns.split(', ').filter(column => column !== 'raw_line');
+            const fieldsDiffer = columns.map(column => column === 'sigma_level' ?
+                'COALESCE(s.sigma_level, 2) IS NOT COALESCE(t.sigma_level, 2)' :
+                `s.${column} IS NOT t.${column}`).join(' OR ');
+            const setsDiffer = (table, fields) => `
+        EXISTS (SELECT ${fields} FROM cave_sync_src.${table} WHERE claim_id = s.id
+          EXCEPT SELECT ${fields} FROM main.${table} WHERE claim_id = t.id)
+        OR EXISTS (SELECT ${fields} FROM main.${table} WHERE claim_id = t.id
+          EXCEPT SELECT ${fields} FROM cave_sync_src.${table} WHERE claim_id = s.id)`;
+            const conflicts = db.prepare(`
+        SELECT s.id FROM cave_sync_src.cave_claim s
+        JOIN main.cave_claim t ON t.id = s.id
+        WHERE ${fieldsDiffer}
+          OR ${setsDiffer('cave_context', 'context')}
+          OR ${setsDiffer('cave_tag', 'key, value')}
+        ORDER BY s.id
+      `).all();
+            if (hasProvenance) {
+                // Sync/backfill can add safely inferred dimensions. Ignore only those
+                // differences; explicit provenance on the same identity must agree.
+                const differences = db.prepare(`
+          SELECT claim_id, dimension, value FROM (
+            SELECT p.claim_id, p.dimension, p.value FROM cave_sync_src.cave_provenance p
+            JOIN main.cave_claim t ON t.id = p.claim_id
+            EXCEPT SELECT claim_id, dimension, value FROM main.cave_provenance
+          )
+          UNION
+          SELECT claim_id, dimension, value FROM (
+            SELECT p.claim_id, p.dimension, p.value FROM main.cave_provenance p
+            JOIN cave_sync_src.cave_claim s ON s.id = p.claim_id
+            EXCEPT SELECT claim_id, dimension, value FROM cave_sync_src.cave_provenance
+          )
+          ORDER BY claim_id
+        `).all();
+                const contextsOf = db.prepare('SELECT context FROM main.cave_context WHERE claim_id = ?');
+                const inferred = new Map();
+                const ids = new Set(conflicts.map(row => row.id));
+                for (const difference of differences) {
+                    let entries = inferred.get(difference.claim_id);
+                    if (entries === undefined) {
+                        const contexts = contextsOf.all(difference.claim_id);
+                        entries = new Set(Provenance.entries(contexts.map(row => row.context))
+                            .map(entry => JSON.stringify([entry.dimension, entry.value])));
+                        inferred.set(difference.claim_id, entries);
+                    }
+                    if (!entries.has(JSON.stringify([difference.dimension, difference.value])) && !ids.has(difference.claim_id)) {
+                        ids.add(difference.claim_id);
+                        conflicts.push({ id: difference.claim_id });
+                    }
+                }
+            }
+            if (conflicts.length > 0) {
+                conflicts.sort((a, b) => a.id.localeCompare(b.id));
+                return { merged: 0, skipped: 0, edges: 0, dryRun, problems: conflicts.map(({ id }) => ({
+                        line: 0,
+                        message: `transaction id ${id} is already stored with different content — a row has one identity (spec §28.1)`,
+                    })) };
+            }
+            const sourceClaims = db.prepare('SELECT * FROM cave_sync_src.cave_claim WHERE id > ? ORDER BY id LIMIT 512');
+            const sourceContexts = db.prepare('SELECT context FROM cave_sync_src.cave_context WHERE claim_id = ?');
+            const sourceTags = db.prepare('SELECT key, value FROM cave_sync_src.cave_tag WHERE claim_id = ?');
+            let after = '';
+            for (;;) {
+                const batch = sourceClaims.all(after);
+                if (batch.length === 0)
+                    break;
+                const problems = [];
+                for (const row of batch) {
+                    const contexts = sourceContexts.all(row.id).map(entry => entry.context);
+                    const tags = sourceTags.all(row.id);
+                    try {
+                        const claim = Row.toClaim(row, contexts, tags);
+                        Canonical.emitClaim(claim);
+                        if (Key.of(claim) === row.claim_key)
+                            continue;
+                    }
+                    catch { /* Report malformed stored data without exposing claim contents. */ }
+                    problems.push({ line: 0, message: `row ${JSON.stringify(row.id)} has an invalid stored claim or inconsistent semantic key` });
+                }
+                if (problems.length > 0)
+                    return { merged: 0, skipped: 0, edges: 0, dryRun, problems };
+                after = batch[batch.length - 1].id;
+            }
             db.exec('DROP TABLE IF EXISTS temp.cave_sync_new');
             db.exec(`CREATE TEMP TABLE cave_sync_new AS
         SELECT id FROM cave_sync_src.cave_claim
         WHERE id NOT IN (SELECT id FROM main.cave_claim)`);
-            try {
+            return withSyncCleanup(() => {
                 const count = (sql) => db.prepare(sql).get().n;
                 const total = count('SELECT COUNT(*) AS n FROM cave_sync_src.cave_claim');
                 const merged = count('SELECT COUNT(*) AS n FROM temp.cave_sync_new');
@@ -146,26 +323,27 @@ export const syncDb = (store, sourcePath, options = {}) => {
                 db.exec(`INSERT INTO main.cave_context (claim_id, context)
           SELECT claim_id, context FROM cave_sync_src.cave_context
           WHERE claim_id IN (SELECT id FROM temp.cave_sync_new)`);
-                const hasProvenance = db.prepare(`
-          SELECT 1 FROM cave_sync_src.sqlite_master
-          WHERE type = 'table' AND name = 'cave_provenance'
-        `).get() !== undefined;
                 if (hasProvenance) {
                     db.exec(`INSERT OR IGNORE INTO main.cave_provenance (claim_id, dimension, value)
             SELECT claim_id, dimension, value FROM cave_sync_src.cave_provenance
             WHERE claim_id IN (SELECT id FROM temp.cave_sync_new)`);
                 }
-                // Older stores have no dimension table. Derive every safely
-                // inferable dimension from their compact contexts after copying;
-                // INSERT OR IGNORE also fills gaps in partially upgraded stores.
-                const contextRows = db.prepare(`
+                // Only legacy stores without a dimension table need inference.
+                // A present table is authoritative, including explicit empty sets.
+                const contextRows = hasProvenance ? [] : db.prepare(`
           SELECT n.id, ctx.context FROM temp.cave_sync_new n
           LEFT JOIN main.cave_context ctx ON ctx.claim_id = n.id
           ORDER BY n.id, ctx.rowid
         `).all();
                 const contexts = new Map();
                 for (const row of contextRows) {
-                    contexts.set(row.id, [...contexts.get(row.id) ?? [], ...row.context === null ? [] : [row.context]]);
+                    let values = contexts.get(row.id);
+                    if (values === undefined) {
+                        values = [];
+                        contexts.set(row.id, values);
+                    }
+                    if (row.context !== null)
+                        values.push(row.context);
                 }
                 const insertProvenance = db.prepare(`
           INSERT OR IGNORE INTO main.cave_provenance (claim_id, dimension, value) VALUES (?, ?, ?)
@@ -204,8 +382,8 @@ export const syncDb = (store, sourcePath, options = {}) => {
                 // dry runs and failures.
                 store.reloadRegistry();
                 const effective = merged + edges > 0;
-                const record = effective && options.record !== false ?
-                    appendRecord(store, options.from ?? 'origin', options.into ?? 'local', merged, edges) :
+                const record = effective && recordEnabled ?
+                    appendRecord(store, from, into, merged, edges) :
                     undefined;
                 return {
                     merged,
@@ -215,18 +393,12 @@ export const syncDb = (store, sourcePath, options = {}) => {
                     ...record === undefined ? {} : { record },
                     problems: []
                 };
-            }
-            finally {
-                db.exec('DROP TABLE IF EXISTS temp.cave_sync_new');
-            }
+            }, () => db.exec('DROP TABLE IF EXISTS temp.cave_sync_new'));
         };
         return dryRun ?
             Uuidv7.withStatePreserved(() => rolledBack(store, body)) :
             store.transaction(body);
-    }
-    finally {
-        db.exec('DETACH DATABASE cave_sync_src');
-    }
+    }, () => db.exec('DETACH DATABASE cave_sync_src'));
 };
 /**
  * Merges §28.4 transaction-annotated canonical text (`cave export --tx`)
@@ -243,25 +415,71 @@ export const syncDb = (store, sourcePath, options = {}) => {
  * row, contributing its edge.
  */
 export const syncText = (store, text, options = {}) => {
-    const dryRun = options.dryRun === true;
+    const dryRun = booleanOption(options.dryRun, 'dryRun', false);
+    const recordOptions = { record: booleanOption(options.record, 'record', true), from: options.from, into: options.into };
+    const body = () => syncTextReserved(store, text, recordOptions, dryRun);
+    return dryRun ?
+        Uuidv7.withStatePreserved(() => rolledBack(store, body)) :
+        store.transaction(body);
+};
+/** Compare canonical interchange content, independent of raw spelling and metadata order. */
+const identityContent = (claim) => Canonical.emitClaim({
+    ...claim,
+    contexts: [...claim.contexts].sort(),
+    tags: [...claim.tags].sort((a, b) => {
+        const left = JSON.stringify([a.key, a.value]);
+        const right = JSON.stringify([b.key, b.value]);
+        return left < right ? -1 : left > right ? 1 : 0;
+    }),
+});
+/** Validation and identity replay use the same reserved vocabulary snapshot. */
+const syncTextReserved = (store, text, options, dryRun) => {
     const problems = [];
     const txByLine = new Map();
+    const provenanceByLine = new Map();
     text.split(/\r?\n/).forEach((raw, at) => {
         const tx = Canonical.txOfLine(raw);
         if (tx === undefined) {
+            // A malformed annotation must not become comment prose merely because
+            // a later valid annotation supplies the claim's identity.
+            if (/^\s*;@/.test(raw)) {
+                problems.push({ line: at + 1, message: 'malformed transaction annotation — expected `;@ <uuidv7>` with optional provenance JSON (spec §28.4)' });
+            }
             return;
         }
         if (Uuidv7.is(tx)) {
             txByLine.set(at + 1, tx);
+            const data = Canonical.txDataOfLine(raw);
+            if (data !== undefined) {
+                let provenance;
+                try {
+                    const payload = JSON.parse(data);
+                    if (payload !== null && typeof payload === 'object' && !Array.isArray(payload) &&
+                        Object.keys(payload).length === 1 && Object.hasOwn(payload, 'provenance')) {
+                        provenance = Provenance.parse(payload.provenance);
+                    }
+                }
+                catch { /* Report malformed JSON alongside other source problems. */ }
+                if (provenance === undefined) {
+                    problems.push({ line: at + 1, message: 'malformed provenance annotation — expected a JSON object with complete provenance dimensions (spec §28.4)' });
+                }
+                else {
+                    provenanceByLine.set(at + 1, provenance);
+                }
+            }
         }
         else {
             problems.push({ line: at + 1, message: `malformed transaction annotation — expected \`;@ <uuidv7>\` (spec §28.4)` });
         }
     });
     const result = Canonical.canonicalizeText(text, store.registry());
-    problems.push(...result.problems);
+    for (const problem of result.problems)
+        problems.push(problem);
     const consumed = new Set();
     const seen = new Map();
+    const newProvenance = new Map();
+    const existingById = store.db.prepare('SELECT * FROM cave_claim WHERE id = ?');
+    const stored = new Map();
     const ids = result.claims.map(entry => {
         const line = entry.line - 1;
         const tx = txByLine.get(line);
@@ -277,13 +495,33 @@ export const syncText = (store, text, options = {}) => {
         // cited by several parents (§28.4) — and unions back into one row, the
         // same §28.1 rule that makes re-syncs idempotent. Only a repeat that
         // disagrees on content forks identity, and rejects.
-        const rendered = Canonical.emitClaim(entry.claim);
+        const rendered = identityContent(entry.claim);
+        const explicitProvenance = provenanceByLine.get(line);
+        const provenance = JSON.stringify(explicitProvenance ??
+            Provenance.normalize(Provenance.fromEntries(Provenance.entries(entry.claim.contexts))));
         const first = seen.get(tx);
-        if (first !== undefined && first.rendered !== rendered) {
+        if (first !== undefined && (first.rendered !== rendered || first.provenance !== provenance)) {
             problems.push({ line: entry.line, message: `transaction annotation repeats line ${first.line}'s id with different content — a row has one identity (spec §28.1)` });
         }
         else if (first === undefined) {
-            seen.set(tx, { line: entry.line, rendered });
+            seen.set(tx, { line: entry.line, rendered, provenance });
+        }
+        // Validation runs under one reservation and precedes all writes. Repeated
+        // graph references can reuse the stored identity, including absent rows.
+        let existing = stored.get(tx);
+        if (!stored.has(tx)) {
+            const row = existingById.get(tx);
+            existing = row === undefined ? undefined : { rendered: identityContent(store.toClaim(row)) };
+            stored.set(tx, existing);
+        }
+        if (existing === undefined && explicitProvenance !== undefined)
+            newProvenance.set(tx, explicitProvenance);
+        if (existing !== undefined && existing.rendered === rendered && explicitProvenance !== undefined && existing.provenance === undefined) {
+            existing.provenance = JSON.stringify(Provenance.normalize(store.provenanceOf(tx)));
+        }
+        if (existing !== undefined && (existing.rendered !== rendered ||
+            (explicitProvenance !== undefined && existing.provenance !== provenance))) {
+            problems.push({ line: entry.line, message: `transaction id ${tx} is already stored with different content — a row has one identity (spec §28.1)` });
         }
         return tx;
     });
@@ -295,25 +533,31 @@ export const syncText = (store, text, options = {}) => {
     if (problems.length > 0) {
         return { merged: 0, skipped: 0, edges: 0, dryRun, problems: problems.sort((a, b) => a.line - b.line) };
     }
-    const body = () => {
-        const outcome = store.insertResult(result, { ids });
-        const merged = result.claims.length - outcome.skipped;
-        const effective = merged + outcome.edges > 0;
-        const record = effective && options.record !== false ?
-            appendRecord(store, options.from ?? 'origin', options.into ?? 'local', merged, outcome.edges) :
-            undefined;
-        return {
-            merged,
-            skipped: outcome.skipped,
-            edges: outcome.edges,
-            dryRun,
-            ...record === undefined ? {} : { record },
-            problems: []
-        };
+    const outcome = store.insertResult(result, { ids });
+    // Explicit annotation dimensions replace legacy inference only for newly
+    // inserted identities. All validation above precedes any mutation.
+    const clearProvenance = store.db.prepare('DELETE FROM cave_provenance WHERE claim_id = ?');
+    const insertProvenance = store.db.prepare('INSERT INTO cave_provenance (claim_id, dimension, value) VALUES (?, ?, ?)');
+    for (const [id, value] of newProvenance) {
+        clearProvenance.run(id);
+        for (const [key, dimension] of [['actors', 'actor'], ['sources', 'source'], ['runs', 'run'], ['domains', 'domain']]) {
+            for (const entry of value[key])
+                insertProvenance.run(id, dimension, entry);
+        }
+    }
+    const merged = result.claims.length - outcome.skipped;
+    const effective = merged + outcome.edges > 0;
+    const record = effective && options.record !== false ?
+        appendRecord(store, options.from ?? 'origin', options.into ?? 'local', merged, outcome.edges) :
+        undefined;
+    return {
+        merged,
+        skipped: outcome.skipped,
+        edges: outcome.edges,
+        dryRun,
+        ...record === undefined ? {} : { record },
+        problems: []
     };
-    return dryRun ?
-        Uuidv7.withStatePreserved(() => rolledBack(store, body)) :
-        store.transaction(body);
 };
 /**
  * Merges a source file of either shape: a CAVE store (recognized by the
@@ -322,9 +566,22 @@ export const syncText = (store, text, options = {}) => {
  * basename stem.
  */
 export const syncFile = (store, sourcePath, options = {}) => {
-    const withLabel = { from: labelOf(sourcePath), ...options };
-    return isStoreFile(sourcePath) ?
-        syncDb(store, sourcePath, withLabel) :
-        syncText(store, readFileSync(sourcePath, 'utf8'), withLabel);
+    const withLabel = {
+        from: options.from ?? labelOf(sourcePath),
+        into: options.into,
+        record: booleanOption(options.record, 'record', true),
+        dryRun: booleanOption(options.dryRun, 'dryRun', false)
+    };
+    if (isStoreFile(sourcePath))
+        return syncDb(store, sourcePath, withLabel);
+    const bytes = readFileSync(sourcePath);
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new TypeError(`${sourcePath}: invalid UTF-8 sync text`, { cause });
+    }
+    return syncText(store, text, withLabel);
 };
 //# sourceMappingURL=sync.js.map