renor-engine 0.0.0-stage → 1.0.0

package/dist/importing/bundle-write.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeBundle = writeBundle;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const types_1 = require("./types");
+/**
+ * Write a bundle as `renor-memory-export/v1` JSONL.
+ *
+ * This is the seam that lets an import run where the workspace lives: a source that is
+ * only reachable read-only can be exported once, and the resulting file is the whole
+ * input the importer needs. It is also the documented interface a third-party provider
+ * can implement directly instead of shipping an adapter.
+ *
+ * The file contains memory content, so it is written `0600` and must be treated as
+ * private material — never committed, never a fixture.
+ */
+function writeBundle(bundle, filePath) {
+    const dir = path_1.default.dirname(path_1.default.resolve(filePath));
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const lines = [];
+    lines.push(JSON.stringify({
+        type: 'meta',
+        format: types_1.BUNDLE_FORMAT,
+        source: bundle.sourceLabel,
+        notes: bundle.notes.length,
+        facts: bundle.facts.length,
+    }));
+    for (const note of bundle.notes) {
+        lines.push(JSON.stringify({
+            type: 'note',
+            path: note.sourcePath,
+            relPath: note.relPath,
+            title: note.title,
+            kind: note.kind,
+            modifiedAt: note.modifiedAt,
+            frontmatter: note.frontmatter,
+            chunks: note.chunks.map(chunk => ({
+                headingPath: chunk.headingPath,
+                text: chunk.text,
+                tokenCount: chunk.tokenCount,
+                startLine: chunk.startLine,
+                endLine: chunk.endLine,
+            })),
+            entities: note.entities,
+            // Carried when present so the importer can prefer the original bytes.
+            originalContent: note.originalContent,
+        }));
+    }
+    for (const fact of bundle.facts) {
+        lines.push(JSON.stringify({
+            type: 'fact',
+            subject: fact.subject,
+            predicate: fact.predicate,
+            object: fact.object,
+            scope: fact.scope,
+            validFrom: fact.validFrom,
+            sourcePath: fact.sourcePath,
+            origin: fact.origin,
+            ledgerSource: fact.ledgerSource,
+        }));
+    }
+    const body = lines.join('\n') + '\n';
+    // `mode` is only honoured when the file is created, so an export over an existing
+    // path (or one a shell redirect created) would keep whatever permissions it already
+    // had — while this command claims the bundle is 0600. Create, write and chmod so the
+    // guarantee holds on overwrite too.
+    const fd = fs_1.default.openSync(filePath, 'w', 0o600);
+    try {
+        fs_1.default.writeFileSync(fd, body, { encoding: 'utf8' });
+        fs_1.default.fchmodSync(fd, 0o600);
+    }
+    finally {
+        fs_1.default.closeSync(fd);
+    }
+    return { bytes: Buffer.byteLength(body, 'utf8'), records: lines.length };
+}

package/dist/importing/cli.js

@@ -0,0 +1,407 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgv = parseArgv;
+exports.run = run;
+const path_1 = __importDefault(require("path"));
+const plan_1 = require("./plan");
+const existing_1 = require("./existing");
+const apply_1 = require("./apply");
+const source_1 = require("./source");
+const bundle_write_1 = require("./bundle-write");
+const markdown_1 = require("./markdown");
+const USAGE = `renor-import — import existing memory into a Renor workspace
+
+Usage:
+  renor-import --from <source> --to <workspace-memory-dir> [--apply] [options]
+
+Source spec:
+  markdown:<folder>               an Obsidian vault or Markdown folder; no source index needed.
+                                   Uses the normal vault ignore rules and .semanticignore.
+                                   Only lowercase .md files; no attachments or symlinks.
+                                   A file or folder name that is not valid UTF-8 cannot be imported:
+                                   such files are listed, not imported; every other note still is.
+  renor-index:<path-to-index.db>   a Renor-shaped index (another workspace, or a personal
+                                   brain). Opened READ-ONLY. Combine with --source-root.
+  bundle:<path-to.jsonl>           a renor-memory-export/v1 bundle, so any provider can
+                                   produce the input for this command.
+
+Destination:
+  --source-root <dir>              directory the index's stored absolute paths live under
+                                   (used to build the relative path).
+  --content-root <dir>             tree holding the source's original Markdown (defaults to
+                                   --source-root). Originals are carried byte-for-byte when
+                                   present; a missing file falls back to reconstruction.
+
+  --to <memory-dir>                the workspace's memory directory (its canonical store).
+  --db <path>                      derived index path (default <memory-dir>/.memory-index/index.db)
+  --ledger-rel <rel>               ledger path relative to the memory dir
+                                   (default System/Memory Events Ledger.md)
+
+Selection (both repeatable; applied to every source kind, by each record's own
+relative path — for renor-index: that is relative to --source-root, for bundle: it is
+the record's relPath):
+  --include <prefix>               include only this prefix (paths are relative to the source
+                                   root and must be matched by the note to be carried).
+  --exclude <prefix>               exclude this prefix. Applied after --include.
+
+Ledger-derived facts (the owner-stated memory, source path '_mcp_') are carried by default
+because they are the smallest and highest-value set. Exclude them with --exclude _mcp_.
+  --limit <n>                      cap the number of selected notes.
+
+Writing:
+  --namespace <rel>                additive destination subdirectory under Imported/
+                                   (default Imported/<source>)
+  --apply                          perform the writes (default: plan only)
+  --canonical-only                 write Markdown + ledger events only; copy no index rows
+
+Other:
+  --event-source <label>           provenance recorded in the ledger (default import:<source>)
+  --emit-bundle <file>             write the selected source as a renor-memory-export/v1
+                                   JSONL bundle and exit. This is how an import runs where
+                                   the workspace lives: export once from a source you can
+                                   only read, then import the file next to the workspace.
+  --json                           emit the machine-readable plan/summary only
+  --help                           show this message
+`;
+function parseArgv(argv) {
+    const options = {
+        namespace: '',
+        ledgerRel: 'System/Memory Events Ledger.md',
+        apply: false,
+        canonicalOnly: false,
+        json: false,
+    };
+    const include = [];
+    const exclude = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const value = () => {
+            const next = argv[i + 1];
+            if (next === undefined)
+                throw new Error(`${arg} requires a value`);
+            i += 1;
+            return next;
+        };
+        switch (arg) {
+            case '--help':
+            case '-h': return { help: true };
+            case '--from':
+                options.from = value();
+                break;
+            case '--to':
+                options.to = value();
+                break;
+            case '--source-root':
+                options.sourceRoot = value();
+                break;
+            case '--content-root':
+                options.contentRoot = value();
+                break;
+            case '--namespace':
+                options.namespace = value();
+                break;
+            case '--include':
+                include.push(value());
+                break;
+            case '--exclude':
+                exclude.push(value());
+                break;
+            case '--limit':
+                options.limit = Number(value());
+                break;
+            case '--ledger-rel':
+                options.ledgerRel = value();
+                break;
+            case '--db':
+                options.dbPath = value();
+                break;
+            case '--event-source':
+                options.eventSource = value();
+                break;
+            case '--apply':
+                options.apply = true;
+                break;
+            case '--canonical-only':
+                options.canonicalOnly = true;
+                break;
+            case '--json':
+                options.json = true;
+                break;
+            case '--emit-bundle':
+                options.emitBundle = value();
+                break;
+            default:
+                throw new Error(`unknown argument ${arg}`);
+        }
+    }
+    if (options.namespace)
+        (0, plan_1.assertImportNamespace)(options.namespace);
+    if (!options.from)
+        throw new Error('--from is required (see --help)');
+    if (!options.to)
+        throw new Error('--to is required (see --help)');
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 0)) {
+        throw new Error('--limit must be a non-negative integer');
+    }
+    return { ...options, include, exclude };
+}
+/** Source label used in the default namespace and provenance label. */
+function sourceKindAndLabel(from) {
+    const separator = from.indexOf(':');
+    const kind = separator < 0 ? from : from.slice(0, separator);
+    const target = separator < 0 ? '' : from.slice(separator + 1);
+    const base = path_1.default.basename(target || kind).replace(/\.(db|jsonl|json)$/i, '');
+    return { kind, label: base || kind };
+}
+/** The Markdown files a source could not carry because a file or folder name is not valid UTF-8. */
+function printNotImported(names, labelWidth) {
+    if (names.length === 0)
+        return;
+    console.log(`  ${'not imported'.padEnd(labelWidth)}: ${names.length} Markdown file(s) whose file or folder name is not valid UTF-8`
+        + ' (bad bytes are shown as \\xNN); rename them to UTF-8 names, then run the import again');
+    for (const name of names.slice(0, 10))
+        console.log(`      ! ${name}`);
+    if (names.length > 10)
+        console.log(`      ! …and ${names.length - 10} more (--json lists them all)`);
+}
+/**
+ * What the secret guard left out of the plan (RENOR_SECRET_GUARD is on): a path or a fact id and the field that
+ * looked like a secret, never text. A path that itself looks like a secret is withheld.
+ */
+function printGuardSkips(skips, labelWidth) {
+    if (!skips || skips.notes.length + skips.events.length === 0)
+        return;
+    console.log(`  ${'secret guard'.padEnd(labelWidth)}: ${skips.notes.length} note(s) and ${skips.events.length} fact(s) not imported: they appear to`
+        + ' contain a credential or personal identifier (RENOR_SECRET_GUARD is on); every other note still is');
+    const lines = [
+        ...skips.notes.map(skip => `${skip.ref ?? '(path withheld)'} (${skip.field}: ${skip.reason})`),
+        ...skips.events.map(skip => `fact ${skip.ref} (${skip.field}: ${skip.reason})`),
+    ];
+    for (const line of lines.slice(0, 10))
+        console.log(`      ! ${line}`);
+    if (lines.length > 10)
+        console.log(`      ! …and ${lines.length - 10} more (--json lists them all)`);
+}
+async function run(argv) {
+    let options;
+    try {
+        options = parseArgv(argv);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        console.error(USAGE);
+        return 2;
+    }
+    if ('help' in options) {
+        console.log(USAGE);
+        return 0;
+    }
+    const { label } = sourceKindAndLabel(options.from);
+    const include = options.include ?? [];
+    const exclude = options.exclude ?? [];
+    const namespace = options.namespace || path_1.default.posix.join('Imported', label);
+    const memoryDir = path_1.default.resolve(options.to);
+    const dbPath = options.dbPath ?? path_1.default.join(memoryDir, '.memory-index', 'index.db');
+    const ledgerPath = path_1.default.join(memoryDir, ...options.ledgerRel.split('/'));
+    const eventSource = options.eventSource || `import:${label}`;
+    let bundle;
+    try {
+        const filter = {
+            include,
+            exclude,
+            limit: options.limit,
+            sourceRoot: options.sourceRoot,
+            contentRoot: options.contentRoot,
+            label,
+        };
+        if (options.from.startsWith('markdown:')) {
+            const root = path_1.default.resolve(options.from.slice('markdown:'.length));
+            // Do not recursively import the destination on a later run. Use real paths
+            // for the source and nearest existing destination ancestor (including links).
+            const fs = await import('fs');
+            let ancestor = memoryDir;
+            while (!fs.existsSync(ancestor) && path_1.default.dirname(ancestor) !== ancestor)
+                ancestor = path_1.default.dirname(ancestor);
+            const destination = path_1.default.resolve(fs.realpathSync(ancestor), path_1.default.relative(ancestor, memoryDir));
+            const source = fs.realpathSync(root);
+            const contains = (parent, child) => {
+                const rel = path_1.default.relative(parent, child);
+                return rel === '' || (rel !== '..' && !rel.startsWith(`..${path_1.default.sep}`) && !path_1.default.isAbsolute(rel));
+            };
+            if (contains(source, destination) || contains(destination, source)) {
+                throw new Error('Markdown source and destination must be separate folders');
+            }
+        }
+        bundle = options.from.startsWith('markdown:')
+            ? await (0, markdown_1.readMarkdownSource)(options.from.slice('markdown:'.length), filter)
+            : (0, source_1.readSource)(options.from, filter);
+    }
+    catch (err) {
+        console.error(`source read failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    const nonUtf8Names = bundle.nonUtf8Names ?? [];
+    if (options.emitBundle) {
+        const written = (0, bundle_write_1.writeBundle)(bundle, options.emitBundle);
+        if (options.json) {
+            console.log(JSON.stringify({
+                mode: 'emit-bundle',
+                source: { spec: options.from, label: bundle.sourceLabel, format: bundle.format },
+                bundle: { file: options.emitBundle, bytes: written.bytes, records: written.records },
+                counts: {
+                    notes: bundle.notes.length,
+                    chunks: bundle.stats.chunksSelected,
+                    facts: bundle.facts.length,
+                    notesWithOriginalBytes: bundle.stats.notesWithOriginalBytes,
+                    notesSkippedNonUtf8Name: nonUtf8Names.length,
+                },
+                skipped: { nonUtf8Names },
+                warning: 'the bundle contains memory content; it is written 0600 and must not be committed',
+            }, null, 2));
+        }
+        else {
+            console.log('renor-import: EMIT BUNDLE');
+            console.log(`  source      : ${options.from}`);
+            console.log(`  bundle      : ${options.emitBundle} (${written.bytes} bytes, ${written.records} records)`);
+            console.log(`  counts      : notes ${bundle.notes.length} (${bundle.stats.notesWithOriginalBytes} with original bytes), chunks ${bundle.stats.chunksSelected}, facts ${bundle.facts.length}`);
+            printNotImported(nonUtf8Names, 12);
+            console.log('  note        : the bundle contains memory content; it is written 0600 and must not be committed');
+        }
+        return 0;
+    }
+    const plan = (0, plan_1.buildImportPlan)(bundle, {
+        namespace,
+        label,
+        eventSource,
+        existingStreams: (0, existing_1.readExistingStreams)(dbPath, ledgerPath),
+    });
+    const warnings = [];
+    if (options.from.startsWith('markdown:')) {
+        warnings.push('Only lowercase .md files are imported. Attachments and symlinks are not imported; '
+            + 'vault ignore rules and .semanticignore apply. Markdown is preserved, but this import '
+            + 'creates no extracted entities or structured facts, and makes no embedding call itself. '
+            + 'Use search_text with an exact phrase from a note to verify recall.');
+    }
+    if (plan.counts.multiValuedFactsDropped > 0) {
+        warnings.push(`${plan.counts.multiValuedFactsDropped} fact row(s) belong to multi-valued streams: the `
+            + `lifecycle layer holds at most one current value per subject+predicate, so they are `
+            + `carried as notes only and not as current facts.`);
+    }
+    warnings.push('Embeddings are not transferred: a vector is bound to the model that produced it, so a vector from '
+        + 'another model would be silent garbage rather than a saving. Imported notes are lexically '
+        + '(full-text) searchable at once. Applied to a workspace with semantic search, the import marks '
+        + 'its index unfinished: the workspace service embeds the imported notes with its own model, once, '
+        + 'when it next starts, and its semantic search is off until they are embedded.');
+    warnings.push('Each imported note row carries the hash of the exact bytes written, which is the indexer\'s own '
+        + '"unchanged" condition. With no extraction lane armed (this workspace\'s configuration) a later '
+        + 'index pass is therefore a no-op for imported notes: no re-chunk, no re-embed, no re-extract. '
+        + 'If a fact/chronicle/preference extraction lane is armed later, its cache key is that same hash '
+        + 'and the lane has no rows for these notes yet, so that pass would re-extract and re-embed them. '
+        + 'Content is durable in Markdown and the ledger; the indexed rows are derived and a rebuild would '
+        + 're-derive them.');
+    const summary = {
+        mode: options.apply ? 'apply' : 'plan',
+        source: { spec: options.from, label: bundle.sourceLabel, format: bundle.format },
+        destination: { memoryDir, dbPath, ledgerRel: options.ledgerRel, namespace },
+        selection: {
+            include,
+            exclude,
+            limit: options.limit ?? null,
+        },
+        counts: {
+            ...plan.counts,
+            // What the selection actually removed, measured by the adapter rather than echoed
+            // back from the flags. A filter that is silently ignored is indistinguishable from
+            // a filter that matched nothing, and `--exclude` failing quietly is a privacy bug.
+            notesFilteredOut: bundle.stats.notesFilteredOut,
+            factsFilteredOut: Math.max(0, bundle.stats.factsAvailable - bundle.stats.factsSelected),
+            eventsAlreadyInDestination: 0,
+            notesSkippedNonUtf8Name: nonUtf8Names.length,
+        },
+        skipped: { ...plan.skipped, nonUtf8Names },
+        warnings,
+    };
+    let exitCode = 0;
+    if (options.apply) {
+        const result = await (0, apply_1.applyImportPlan)(plan, bundle, {
+            memoryDir,
+            dbPath,
+            ledgerRelPath: options.ledgerRel,
+            canonicalOnly: options.canonicalOnly,
+        });
+        summary.applied = result;
+        summary.counts = {
+            ...summary.counts,
+            eventsAlreadyInDestination: result.eventsAlreadyPresent,
+        };
+        summary.after = result.destination;
+    }
+    else {
+        summary.after = null;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(summary, null, 2));
+    }
+    else {
+        const mode = options.apply ? 'APPLIED' : 'PLAN (dry run — pass --apply to write)';
+        console.log(`renor-import: ${mode}`);
+        console.log(`  source        : ${options.from} (label ${bundle.sourceLabel})`);
+        console.log(`  destination   : ${memoryDir}`);
+        console.log(`  namespace     : ${namespace}`);
+        console.log(`  notes         : ${plan.counts.selectedNotes} selected of ${plan.counts.notesInBundle} in bundle`
+            + ` (${plan.skipped.duplicateNotePath} duplicate path, ${plan.skipped.emptyNoteBody} empty)`);
+        if (bundle.stats.notesFilteredOut > 0 || bundle.stats.factsAvailable > bundle.stats.factsSelected) {
+            console.log(`  selection     : ${bundle.stats.notesFilteredOut} note(s) and `
+                + `${bundle.stats.factsAvailable - bundle.stats.factsSelected} fact(s) left out by --include/--exclude/--limit`);
+        }
+        printNotImported(nonUtf8Names, 14);
+        printGuardSkips(plan.skipped.secretGuard, 14);
+        console.log(`  chunks        : ${plan.counts.selectedChunks} from the source parse (no re-chunking)`);
+        console.log(`  note bytes    : ${plan.counts.notesFromOriginalBytes} carried verbatim, ${plan.counts.notesReconstructed} reconstructed from chunks`);
+        if (plan.counts.chunksNotLocated > 0) {
+            console.log(`      ! ${plan.counts.chunksNotLocated} chunk(s) not locatable in the carried bytes; ${plan.counts.chunksSpanInherited} inherited the source span, the rest have an unknown span`);
+        }
+        console.log(`  ledger events : ${plan.counts.eventsToAppend} new`
+            + (options.apply ? ` (${summary.applied.eventsAppended} appended, ${summary.applied.eventsAlreadyPresent} already present)` : ''));
+        console.log(`  facts         : ${plan.counts.factsInBundle} current in source, ${plan.counts.eventsToAppend} carried, `
+            + `${plan.counts.multiValuedFactsDropped} multi-valued dropped, ${plan.counts.factsSkipped} other skips`);
+        for (const skip of plan.skipped.events) {
+            console.log(`      - ${skip.count} × ${skip.reason}`);
+        }
+        if (options.apply) {
+            const applied = summary.applied;
+            console.log(`  files         : ${applied.notesWritten} written, ${applied.notesUnchanged} already identical, ${applied.notesConflicting} conflicting (never overwritten or indexed)`);
+            for (const conflict of (applied.conflicts ?? []).slice(0, 10)) {
+                console.log(`      ! conflict (left as-is, not indexed): ${conflict}`);
+            }
+            if ((applied.conflicts ?? []).length > 10) {
+                console.log(`      ! …and ${applied.conflicts.length - 10} more`);
+            }
+            console.log(`  index rows    : ${applied.indexRows.notesInserted} notes, ${applied.indexRows.chunksInserted} chunks, ${applied.indexRows.entitiesInserted} entities inserted`);
+            console.log(`  replayed      : ${applied.ledgerReplayed} ledger event(s) applied to the index`);
+            console.log(`  workspace now : notes ${applied.destination.notes} · chunks ${applied.destination.chunks} · entities ${applied.destination.entities} · facts ${applied.destination.facts} (${applied.destination.currentFacts} current)`);
+        }
+        for (const warning of warnings)
+            console.log(`  note          : ${warning}`);
+    }
+    if (options.apply && summary.applied.notesConflicting > 0)
+        exitCode = 3;
+    // Like a conflict, a note the guard left out is something the operator asked for that was not imported.
+    const guardSkips = plan.skipped.secretGuard;
+    if (options.apply && guardSkips && guardSkips.notes.length + guardSkips.events.length > 0)
+        exitCode = 3;
+    return exitCode;
+}
+/* c8 ignore start — process wiring; `run` above holds the testable behavior. */
+if (require.main === module) {
+    run(process.argv.slice(2))
+        .then(code => { process.exitCode = code; })
+        .catch(err => {
+        console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+        process.exitCode = 1;
+    });
+}
+/* c8 ignore stop */

package/dist/importing/existing.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readExistingStreams = readExistingStreams;
+const fs_1 = __importDefault(require("fs"));
+const client_1 = require("../db/client");
+const lifecycle_1 = require("../memory/lifecycle");
+const plan_1 = require("./plan");
+/**
+ * Fact streams a destination already represents.
+ *
+ * Two sources, because they disagree in a way that matters: the **ledger** is canonical
+ * and the index is derived. A stream a ledger event already declares is represented even
+ * when the projection has not caught up — and importing an older value for it would not
+ * merely duplicate, it would fail the engine's per-stream monotonicity check during
+ * replay, which runs at service STARTUP and refuses to serve. Skipping it is the only
+ * safe move, and the skip is counted and reported rather than silent.
+ */
+function readExistingStreams(dbPath, ledgerPath) {
+    const streams = new Set();
+    let db = null;
+    try {
+        db = (0, client_1.openReadOnlyDb)(dbPath);
+        const rows = db.prepare(`SELECT e.canonical_name AS subject, f.predicate AS predicate, f.scope AS scope
+         FROM facts f JOIN entities e ON e.id = f.subject_entity_id
+        WHERE f.valid_to IS NULL AND f.source_path = '_mcp_'`).all();
+        for (const row of rows)
+            streams.add((0, plan_1.streamKey)(row.subject, row.predicate, row.scope ?? 'global'));
+    }
+    catch {
+        // A destination with no index yet simply has no indexed streams.
+    }
+    finally {
+        db?.close();
+    }
+    try {
+        const content = fs_1.default.readFileSync(ledgerPath, 'utf8');
+        for (const event of (0, lifecycle_1.parseLedgerEvents)(content)) {
+            streams.add((0, plan_1.streamKey)(event.subject, event.predicate, event.scope ?? 'global'));
+        }
+    }
+    catch {
+        // No ledger yet, or an unreadable one: nothing declared that this read can vouch for.
+        // Replay still fails closed on the real content, so this cannot launder a bad ledger.
+    }
+    return streams;
+}

package/dist/importing/facts.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_ID_RE = void 0;
+exports.deterministicEventId = deterministicEventId;
+exports.toCanonicalInstant = toCanonicalInstant;
+exports.tryNormalizeScope = tryNormalizeScope;
+exports.validateCarriedFact = validateCarriedFact;
+const crypto_1 = __importDefault(require("crypto"));
+const scope_1 = require("../mvp/scope");
+/**
+ * Identity and validation rules for carried facts.
+ *
+ * A carried fact becomes a canonical ledger event, because the engine's lifecycle
+ * layer (and therefore the dashboard's fact list and graph) reads only facts whose
+ * `source_path` is the lifecycle sentinel — facts derived from notes are invisible
+ * to those readers.
+ *
+ * Two hard requirements come from `engine/src/memory/lifecycle.ts`:
+ *  - event `id` and `at` decide replay idempotency (`applied_ledger_events`), so a
+ *    re-run must produce a byte-identical event or replay either duplicates it or
+ *    fails with "reused with a conflicting payload" — and replay runs at service
+ *    STARTUP, so a mutated payload would break the workspace's readiness gate;
+ *  - `at` must be the canonical instant form and ids must match `^mem_[A-Za-z0-9]+$`.
+ *
+ * Scope and field limits are therefore imported from the engine rather than mirrored
+ * here: a validator that drifts looser fails at boot, and one that drifts stricter
+ * silently loses memory.
+ */
+exports.EVENT_ID_RE = /^mem_[A-Za-z0-9]+$/;
+/** Field limits as enforced by `lifecycle.ts` `validateField`. */
+const FIELD_LIMITS = { subject: 512, predicate: 256, object: 8192, source: 256 };
+const CONTROL_CHARS = /[\u0000-\u001F\u007F]/;
+const CANONICAL_TS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+/** The instant forms the engine's own normalizer accepts: an explicit zone, or date-only. */
+const ZONED_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Deterministic event id for a carried fact.
+ *
+ * It is a function of **everything replay compares** — source label, subject,
+ * predicate, scope, object and `at` — because the id's only job is to make a re-run a
+ * no-op. A narrower key would mint the same id for a different payload when the source
+ * changed between runs, which replay rejects as corruption.
+ */
+function deterministicEventId(input) {
+    const digest = crypto_1.default
+        .createHash('sha256')
+        .update([
+        'renor-memory-import/v1',
+        input.label,
+        input.subject,
+        input.predicate,
+        input.scope,
+        input.object,
+        input.at,
+    ].join('\u0000'))
+        .digest('hex')
+        .slice(0, 40);
+    return `mem_imp${digest}`;
+}
+/**
+ * Canonical instant, or null when the input cannot be one. Mirrors the engine's
+ * accepted inputs (an ISO instant with an explicit timezone, or date-only) and rejects
+ * timezone-less datetimes, which the engine treats as ambiguous.
+ */
+function toCanonicalInstant(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (CANONICAL_TS.test(trimmed) || ZONED_INSTANT.test(trimmed) || DATE_ONLY.test(trimmed)) {
+        const parsed = new Date(trimmed);
+        if (Number.isNaN(parsed.getTime()))
+            return null;
+        const year = parsed.getUTCFullYear();
+        if (year < 1970 || year > 2999)
+            return null;
+        return parsed.toISOString();
+    }
+    return null;
+}
+/** `normalizeScope` from the engine, or null when it rejects the value. */
+function tryNormalizeScope(raw) {
+    try {
+        return (0, scope_1.normalizeScope)(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate a fact once, before anything is written, and normalize its scope and
+ * instant. A rejection is counted by reason rather than surfacing at the destination's
+ * readiness gate.
+ */
+function validateCarriedFact(fact) {
+    if (!fact.subject.trim())
+        return { ok: false, reason: 'empty subject' };
+    if (!fact.predicate.trim())
+        return { ok: false, reason: 'empty predicate' };
+    if (!fact.object.trim())
+        return { ok: false, reason: 'empty object' };
+    if (CONTROL_CHARS.test(fact.subject) || CONTROL_CHARS.test(fact.predicate)
+        || CONTROL_CHARS.test(fact.object) || CONTROL_CHARS.test(fact.scope)) {
+        return { ok: false, reason: 'control character in a lifecycle field' };
+    }
+    if (fact.subject.length > FIELD_LIMITS.subject)
+        return { ok: false, reason: 'subject exceeds 512 characters' };
+    if (fact.predicate.length > FIELD_LIMITS.predicate)
+        return { ok: false, reason: 'predicate exceeds 256 characters' };
+    if (fact.object.length > FIELD_LIMITS.object)
+        return { ok: false, reason: 'object exceeds 8192 characters' };
+    const scope = tryNormalizeScope(fact.scope);
+    if (scope === null)
+        return { ok: false, reason: 'scope is not a valid scope, scope:<slug> or project:<slug>' };
+    const at = toCanonicalInstant(fact.validFrom);
+    if (at === null) {
+        return { ok: false, reason: 'valid_from is not an ISO instant with an explicit timezone' };
+    }
+    return { ok: true, scope, at };
+}