@cavelang/cli 0.27.14 → 0.29.1

package/dist/internal/connect/run.js

@@ -0,0 +1,242 @@
+/**
+ * The connect pass (spec §23.2) — instantiate the mapping per record, append
+ * through the standard pipeline with record provenance, and keep re-runs
+ * row-level incremental via per-record digest claims:
+ *
+ * ```cave
+ * connect/people/42 HAS connect-digest: 93a01c626b3f @src:cave-connect
+ * ```
+ *
+ * Every claim a record produces is auto-stamped `@src:connect/<name>/<key>`
+ * (spec §9.5), so a changed record diffs against itself: current claims
+ * still carrying the record's stamp but no longer produced by it are
+ * retracted (`@ 0%`). `--prune` extends the diff to records that vanished
+ * from the source. Explicit `run` provenance is the lifecycle identity;
+ * the compatibility stamp is also applied when a template names its own
+ * `@src:` context (both are kept).
+ */
+import { createHash } from 'node:crypto';
+import { Claim, Key, SourceSpan, Value } from '@cavelang/core';
+import { query as caveQuery } from '@cavelang/query';
+import * as Template from "./template.js";
+export const digestAttribute = 'connect-digest';
+export const provenanceContext = 'src:cave-connect';
+/** First 12 hex chars of SHA-256, mirroring `@cavelang/cli/ingest` (spec §9.5). */
+export const digestOf = (content) => createHash('sha256').update(content).digest('hex').slice(0, 12);
+/**
+ * Claim key of a unit's digest claim. The value is excluded from keys
+ * (spec §9.2), so the key is stable while the digest evolves.
+ */
+const digestKey = (subject) => Key.of(Claim.of({
+    subject: Claim.entity(subject),
+    verb: 'HAS',
+    payload: Claim.attribute(digestAttribute, Value.parse('x')),
+    contexts: [provenanceContext]
+}));
+/** @returns `true` when the unit's current digest claim matches `digest`. */
+export const isConnected = (store, subject, digest) => {
+    const known = store.currentBelief(digestKey(subject));
+    return known !== undefined && known.value_text === digest && known.conf > 0;
+};
+const recordDigest = (store, subject, digest) => {
+    store.ingest(`${subject} HAS ${digestAttribute}: ${digest} @${provenanceContext}`);
+};
+const recordFailure = Symbol('cave-connect record failure');
+const failRecord = (problems) => {
+    throw { [recordFailure]: true, problems };
+};
+const isRecordError = (error) => typeof error === 'object' && error !== null && recordFailure in error;
+/**
+ * Context-safe record key from a field value: runs of characters outside
+ * `A-Za-z0-9._-` collapse to `-` (the key rides in an entity name and a
+ * `@src:` context — reserved characters would change the line's meaning).
+ * Casing is preserved; keys needing exact identity should be shaped in the
+ * source.
+ */
+const keyOf = (value) => {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const text = String(value).trim().replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return text === '' ? undefined : text;
+};
+/** In-band vocabulary declarations are append-only and never lifecycle-retracted. */
+const isDeclaration = (row) => row.verb === 'REVERSE' || row.verb === 'RENAMED-TO' ||
+    (row.verb === 'IS' && row.object === 'verb');
+/**
+ * Retracts current claims carrying `context` that were not (re-)appended in
+ * this pass (spec §23.2). Contexts are part of claim identity, so every row
+ * of a stamped series carries the stamp — the latest row per key among the
+ * stamped rows *is* the series' current belief.
+ */
+const retractStale = (store, run, keepIds) => {
+    const latest = new Map();
+    for (const row of store.byProvenance('run', run)) {
+        const seen = latest.get(row.claim_key);
+        if (seen === undefined || seen.tx < row.tx) {
+            latest.set(row.claim_key, row);
+        }
+    }
+    const stale = [...latest.values()]
+        .filter(row => row.conf > 0 && !keepIds.has(row.id) && !isDeclaration(row));
+    if (stale.length === 0) {
+        return 0;
+    }
+    store.insertResult({
+        claims: stale.map(row => ({
+            claim: { ...store.toClaim(row), conf: 0, raw: '', comment: 'retracted: no longer in source' },
+            line: 0
+        })),
+        edges: [],
+        registry: store.registry(),
+        problems: []
+    });
+    return stale.length;
+};
+/**
+ * One connect pass: prelude (digest-skipped as a unit under
+ * `connect/<name>`), then each record (digest-skipped under
+ * `connect/<name>/<key>`), then optional pruning. Each unit appends inside
+ * its own transaction — a failing record rolls back cleanly and never
+ * poisons the rest of the run.
+ */
+export const connect = (store, mapping, records, options) => {
+    const force = options.force === true;
+    // The name rides in entity names and @src: contexts, like record keys.
+    const name = keyOf(options.name);
+    if (name === undefined) {
+        throw new Error(`cave connect: unusable source name ${JSON.stringify(options.name)} — pass --name`);
+    }
+    const failures = [];
+    const notes = [];
+    const seen = new Set();
+    let mapped = 0;
+    let skipped = 0;
+    let added = 0;
+    let retracted = 0;
+    let pruned = 0;
+    let dropped = 0;
+    const ingestUnit = (subject, text, digest, sourceContext) => {
+        store.transaction(() => {
+            const result = store.ingest(text, {
+                source: subject,
+                lifecycle: true,
+                ...sourceContext === undefined ? {} : { contexts: [sourceContext] }
+            });
+            if (result.problems.length > 0) {
+                failRecord(result.problems.map(problem => `line ${problem.line}: ${problem.message}`));
+            }
+            added += result.ids.length;
+            retracted += retractStale(store, subject, new Set(result.ids));
+            recordDigest(store, subject, digest);
+        });
+    };
+    if (mapping.prelude !== '') {
+        const subject = `connect/${name}`;
+        const digest = digestOf(mapping.prelude);
+        if (force || !isConnected(store, subject, digest)) {
+            store.transaction(() => {
+                const result = store.ingest(mapping.prelude, { source: subject });
+                if (result.problems.length > 0) {
+                    // The prelude was linted with the mapping; a problem here aborts the run.
+                    const detail = result.problems.map(problem => `prelude line ${problem.line}: ${problem.message}`).join('\n');
+                    throw new Error(`cave connect: prelude failed to ingest\n${detail}`);
+                }
+                added += result.ids.length;
+                recordDigest(store, subject, digest);
+            });
+        }
+        else {
+            notes.push('prelude unchanged, skipped');
+        }
+    }
+    records.forEach((record, at) => {
+        const instantiation = Template.instantiate(mapping.templates, name => Template.fieldOf(record, name));
+        dropped += instantiation.dropped;
+        const key = options.key === undefined ?
+            digestOf(instantiation.text) :
+            keyOf(Template.fieldOf(record, options.key));
+        if (key === undefined) {
+            failures.push({ record: `record ${at + 1}`, problems: [`--key field ${JSON.stringify(options.key)} is missing or empty`] });
+            return;
+        }
+        if (seen.has(key)) {
+            notes.push(`duplicate record key ${JSON.stringify(key)} — last record wins`);
+        }
+        // Failed records still count as seen — pruning must never mistake a
+        // transient failure for a record that left the source.
+        seen.add(key);
+        if (instantiation.problems.length > 0) {
+            failures.push({ record: `record ${at + 1} (${key})`, problems: instantiation.problems });
+            return;
+        }
+        const subject = `connect/${name}/${key}`;
+        const sourceContext = options.source === undefined ? undefined :
+            SourceSpan.context(options.source, options.spans?.[at]);
+        const digest = digestOf(`${instantiation.text}\0${sourceContext ?? ''}`);
+        if (!force && isConnected(store, subject, digest)) {
+            skipped += 1;
+            return;
+        }
+        try {
+            ingestUnit(subject, instantiation.text, digest, sourceContext);
+            mapped += 1;
+        }
+        catch (error) {
+            if (!isRecordError(error)) {
+                throw error;
+            }
+            failures.push({ record: `record ${at + 1} (${key})`, problems: error.problems });
+        }
+    });
+    if (options.prune === true) {
+        const prefix = `connect/${name}/`;
+        const latest = new Map();
+        for (const row of store.byContext(provenanceContext)) {
+            const current = latest.get(row.claim_key);
+            if (current === undefined || current.tx < row.tx) {
+                latest.set(row.claim_key, row);
+            }
+        }
+        for (const row of latest.values()) {
+            if (row.conf <= 0 || !row.subject.startsWith(prefix) || seen.has(row.subject.slice(prefix.length))) {
+                continue;
+            }
+            store.transaction(() => {
+                retracted += retractStale(store, row.subject, new Set());
+                store.insertResult({
+                    claims: [{ claim: { ...store.toClaim(row), conf: 0, raw: '', comment: 'retracted: record left the source' }, line: 0 }],
+                    edges: [],
+                    registry: store.registry(),
+                    problems: []
+                });
+                pruned += 1;
+            });
+        }
+    }
+    return { records: records.length, mapped, skipped, added, retracted, pruned, dropped, failures, notes };
+};
+const rollback = Symbol('cave-connect query rollback');
+/**
+ * Federation-lite (spec §23.3): appends the mapped claims inside a
+ * transaction, runs the CAVE-Q pattern over the union of store and source,
+ * and rolls back — external data is consulted at query time, nothing
+ * persists (digest bookkeeping included).
+ */
+export const federatedQuery = (store, mapping, records, options, pattern, queryOptions = {}) => {
+    let outcome;
+    try {
+        store.transaction(() => {
+            const report = connect(store, mapping, records, { ...options, force: true, prune: false });
+            outcome = { matches: caveQuery(store, pattern, queryOptions), report };
+            throw rollback;
+        });
+    }
+    catch (error) {
+        if (error !== rollback) {
+            throw error;
+        }
+    }
+    return outcome;
+};
+//# sourceMappingURL=run.js.map

package/dist/internal/connect/run.js.map

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

package/dist/internal/connect/source.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Record sources (spec §23) — CSV/TSV files, JSON documents, JSONL streams,
+ * SQLite databases (read-only), and http(s) URLs serving JSON or CSV. Every
+ * source loads to the same shape: an array of flat-ish records the template
+ * layer resolves fields from (`fieldOf` handles nested JSON by dot path).
+ */
+import type { LineSpan } from '@cavelang/core';
+export type Format = 'csv' | 'tsv' | 'json' | 'jsonl' | 'sqlite';
+/** Injection point for tests; the built-in fetch otherwise. */
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export type Options = {
+    /** Explicit format; inferred from the extension when omitted. */
+    readonly format?: Format;
+    /** CSV delimiter (default `,`; `\t` for tsv). */
+    readonly delimiter?: string;
+    /** SQLite table to read (`SELECT *`). */
+    readonly table?: string;
+    /** SQLite query — the alternative to `table`. */
+    readonly sql?: string;
+    /** Dot path to the record array inside a JSON document. */
+    readonly records?: string;
+    /** URL fetch timeout in seconds (default 60). */
+    readonly timeoutSeconds?: number;
+    /** Injection point for tests; the built-in fetch otherwise. */
+    readonly fetchImpl?: FetchLike;
+};
+export type Loaded = {
+    readonly records: readonly Record<string, unknown>[];
+    readonly format: Format;
+    /** Record-aligned source line spans when the format has stable lines. */
+    readonly spans?: readonly LineSpan[];
+};
+export declare const isUrl: (source: string) => boolean;
+/** Infers the source format from an explicit option or the file/URL extension. */
+export declare const formatOf: (source: string, options?: Options) => Format;
+/**
+ * Default source name for record identity (spec §23.2): the file/URL
+ * basename without extension, whitespace and path noise normalized to `-`.
+ */
+export declare const nameOf: (source: string) => string;
+export declare const parseCsv: (text: string, delimiter?: string) => Record<string, string>[];
+/** Loads a source to records. Local files read synchronously; URLs fetch. */
+export declare const load: (source: string, options?: Options) => Promise<Loaded>;
+//# sourceMappingURL=source.d.ts.map

package/dist/internal/connect/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/source.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAG9C,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEhE,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE7E,MAAM,MAAM,OAAO,GAAG;IACpB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,iDAAiD;IACjD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,iDAAiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAC/B,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;CACrC,CAAA;AAED,eAAO,MAAM,KAAK,GAAI,QAAQ,MAAM,KAAG,OACT,CAAA;AAa9B,kFAAkF;AAClF,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,EAAE,UAAS,OAAY,KAAG,MAUhE,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,MAAM,KAAG,MAOvC,CAAA;AAqED,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,kBAAe,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,CAAA;AA0E1C,6EAA6E;AAC7E,eAAO,MAAM,IAAI,GAAU,QAAQ,MAAM,EAAE,UAAS,OAAY,KAAG,OAAO,CAAC,MAAM,CAiBhF,CAAA"}

package/dist/internal/connect/source.js

@@ -0,0 +1,215 @@
+/**
+ * Record sources (spec §23) — CSV/TSV files, JSON documents, JSONL streams,
+ * SQLite databases (read-only), and http(s) URLs serving JSON or CSV. Every
+ * source loads to the same shape: an array of flat-ish records the template
+ * layer resolves fields from (`fieldOf` handles nested JSON by dot path).
+ */
+import { readFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { fieldOf } from "./template.js";
+export const isUrl = (source) => /^https?:\/\//i.test(source);
+const extensionFormats = {
+    '.csv': 'csv',
+    '.tsv': 'tsv',
+    '.json': 'json',
+    '.jsonl': 'jsonl',
+    '.ndjson': 'jsonl',
+    '.db': 'sqlite',
+    '.sqlite': 'sqlite',
+    '.sqlite3': 'sqlite'
+};
+/** Infers the source format from an explicit option or the file/URL extension. */
+export const formatOf = (source, options = {}) => {
+    if (options.format !== undefined) {
+        return options.format;
+    }
+    const path = isUrl(source) ? new URL(source).pathname : source;
+    const format = extensionFormats[extname(path).toLowerCase()];
+    if (format === undefined) {
+        throw new Error(`cannot infer format of ${JSON.stringify(source)} — pass --format csv|tsv|json|jsonl|sqlite`);
+    }
+    return format;
+};
+/**
+ * Default source name for record identity (spec §23.2): the file/URL
+ * basename without extension, whitespace and path noise normalized to `-`.
+ */
+export const nameOf = (source) => {
+    const path = isUrl(source) ?
+        new URL(source).hostname + decodeURIComponent(new URL(source).pathname) :
+        source;
+    const base = basename(path, extname(path));
+    const name = base.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return name === '' ? 'source' : name;
+};
+/**
+ * RFC 4180 CSV: quoted fields (with `""` escapes) may contain delimiters and
+ * newlines; records split on LF or CRLF. The first row names the fields.
+ */
+const parseCsvLocated = (text, delimiter = ',') => {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    let line = 1;
+    let rowStart = 1;
+    const body = text.startsWith('\uFEFF') ? text.slice(1) : text;
+    const endField = () => {
+        row.push(field);
+        field = '';
+    };
+    const endRow = () => {
+        endField();
+        rows.push({ cells: row, span: { startLine: rowStart, endLine: line } });
+        row = [];
+        rowStart = line + 1;
+    };
+    for (let i = 0; i < body.length; i++) {
+        const char = body[i];
+        if (quoted) {
+            if (char === '"') {
+                if (body[i + 1] === '"') {
+                    field += '"';
+                    i += 1;
+                }
+                else {
+                    quoted = false;
+                }
+            }
+            else if (char === '\r' && body[i + 1] === '\n') {
+                // CRLF normalizes to LF inside quoted fields too.
+            }
+            else {
+                field += char;
+            }
+        }
+        else if (char === '"' && field === '') {
+            quoted = true;
+        }
+        else if (char === delimiter) {
+            endField();
+        }
+        else if (char === '\n') {
+            endRow();
+        }
+        else if (char !== '\r' || body[i + 1] !== '\n') {
+            field += char;
+        }
+        if (char === '\n') {
+            line += 1;
+        }
+    }
+    if (field !== '' || row.length > 0) {
+        endRow();
+    }
+    const [headerRow, ...dataRows] = rows;
+    const header = headerRow?.cells;
+    if (header === undefined) {
+        return { records: [], spans: [] };
+    }
+    const present = dataRows.filter(row_ => row_.cells.length > 1 || row_.cells[0] !== '');
+    return {
+        records: present.map(row_ => Object.fromEntries(header.map((name, at) => [name.trim(), row_.cells[at] ?? '']))),
+        spans: present.map(row_ => row_.span)
+    };
+};
+export const parseCsv = (text, delimiter = ',') => parseCsvLocated(text, delimiter).records;
+const asRecords = (value, source) => {
+    if (!Array.isArray(value)) {
+        throw new Error(`${source}: expected an array of records${value !== null && typeof value === 'object' ? ' — pass --records <dot.path> to the array' : ''}`);
+    }
+    return value.map((item, at) => {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            throw new Error(`${source}: record ${at + 1} is not an object`);
+        }
+        return item;
+    });
+};
+const parseJson = (text, source, options) => {
+    const parsed = JSON.parse(text);
+    const picked = options.records === undefined ? parsed : fieldOf(parsed, options.records);
+    if (options.records !== undefined && picked === undefined) {
+        throw new Error(`${source}: --records ${JSON.stringify(options.records)} not found`);
+    }
+    return asRecords(picked, source);
+};
+const parseJsonlLocated = (text, source) => {
+    const located = text.split(/\r?\n/)
+        .map((line, at) => ({ line, lineNo: at + 1 }))
+        .filter(entry => entry.line.trim() !== '');
+    return {
+        records: located.map(entry => {
+            const parsed = JSON.parse(entry.line);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error(`${source}: line ${entry.lineNo} is not a JSON object`);
+            }
+            return parsed;
+        }),
+        spans: located.map(entry => ({ startLine: entry.lineNo, endLine: entry.lineNo }))
+    };
+};
+/** node:sqlite values → template-substitutable values. */
+const sqliteValue = (value) => typeof value === 'bigint' ?
+    (Number.isSafeInteger(Number(value)) ? Number(value) : value.toString()) :
+    value;
+const readSqlite = (path, options) => {
+    if ((options.table === undefined) === (options.sql === undefined)) {
+        throw new Error(`${path}: a SQLite source needs exactly one of --table or --sql`);
+    }
+    const sql = options.sql ?? `SELECT * FROM "${options.table.replaceAll('"', '""')}"`;
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+        const rows = db.prepare(sql).all();
+        return rows.map(row => Object.fromEntries(Object.entries(row).map(([key, value]) => [key, sqliteValue(value)])));
+    }
+    finally {
+        db.close();
+    }
+};
+const fetchText = async (url, options) => {
+    const response = await (options.fetchImpl ?? fetch)(url, {
+        headers: {
+            'user-agent': 'cave-connect',
+            accept: 'application/json, text/csv;q=0.9, */*;q=0.8'
+        },
+        redirect: 'follow',
+        signal: AbortSignal.timeout((options.timeoutSeconds ?? 60) * 1000)
+    });
+    if (!response.ok) {
+        throw new Error(`${url}: HTTP ${response.status}`);
+    }
+    return { text: await response.text(), contentType: response.headers.get('content-type') ?? '' };
+};
+/** Loads a source to records. Local files read synchronously; URLs fetch. */
+export const load = async (source, options = {}) => {
+    if (isUrl(source)) {
+        const { text, contentType } = await fetchText(source, options);
+        const format = options.format ??
+            (contentType.includes('json') ? 'json' :
+                contentType.includes('csv') ? 'csv' :
+                    formatOf(source, options));
+        if (format === 'sqlite') {
+            throw new Error(`${source}: SQLite sources must be local files`);
+        }
+        return { ...parseLocated(format, text, source, options), format };
+    }
+    const format = formatOf(source, options);
+    if (format === 'sqlite') {
+        return { records: readSqlite(source, options), format };
+    }
+    return { ...parseLocated(format, readFileSync(source, 'utf8'), source, options), format };
+};
+const parseLocated = (format, text, source, options) => {
+    switch (format) {
+        case 'csv':
+            return parseCsvLocated(text, options.delimiter ?? ',');
+        case 'tsv':
+            return parseCsvLocated(text, options.delimiter ?? '\t');
+        case 'json':
+            return { records: parseJson(text, source, options) };
+        case 'jsonl':
+            return parseJsonlLocated(text, source);
+    }
+};
+//# sourceMappingURL=source.js.map

package/dist/internal/connect/source.js.map

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

package/dist/internal/connect/template.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Mapping templates (spec §23.1) — an ordinary CAVE document whose `?field`
+ * variables stand for record fields.
+ *
+ * Top-level blocks (a line plus its indented children) split by whether they
+ * contain a variable: variable-free blocks form the **prelude** (verb
+ * declarations, static claims — appended once per run), blocks with
+ * variables are **record templates**, instantiated once per record.
+ *
+ * A variable is a whole whitespace-delimited token beginning with `?`;
+ * tokens inside `"…"` and `` `…` `` literals are never substituted. A claim
+ * line whose record lacks a referenced field is dropped together with its
+ * indented children — optional fields simply yield fewer claims.
+ */
+export type Mapping = {
+    /** Variable-free blocks plus leading comments, joined — appended once per run. */
+    readonly prelude: string;
+    /** Record templates: raw lines of each variable-bearing top-level block. */
+    readonly templates: readonly (readonly string[])[];
+    /** Distinct variable names referenced by the templates, sorted. */
+    readonly variables: readonly string[];
+};
+export type t = Mapping;
+/** A field value substituted into one template slot. */
+export type Formatted = {
+    readonly kind: 'ok';
+    readonly text: string;
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'problem';
+    readonly message: string;
+};
+/** One record's instantiation of every template block. */
+export type Instantiation = {
+    /** Ready-to-ingest CAVE text; empty when every line dropped. */
+    readonly text: string;
+    /** Claim lines dropped because a referenced field was missing/empty. */
+    readonly dropped: number;
+    /** Formatting errors — a non-empty list fails the whole record (spec §23.2). */
+    readonly problems: readonly string[];
+};
+/**
+ * Parses a mapping document: lints it (variables parse as ordinary terms, so
+ * diagnostics are real syntax problems), rejects variables in attribute
+ * position (`?attr: …` would silently name an attribute `?attr`), and splits
+ * top-level blocks into prelude and record templates.
+ */
+export declare const parse: (text: string) => {
+    mapping?: Mapping;
+    problems: readonly string[];
+};
+/**
+ * Formats one field value for one template slot (spec §23.1). Deterministic
+ * and exact — values insert verbatim when already token-safe, or as quoted
+ * literals; formatting never invents names (no slugification).
+ */
+export declare const formatValue: (value: unknown, position: "subject" | "payload") => Formatted;
+/**
+ * Resolves a field by name: exact key first, then a dot path into nested
+ * JSON (`address.city`, `items.0.sku`).
+ */
+export declare const fieldOf: (record: unknown, name: string) => unknown;
+/**
+ * Instantiates every template block for one record. Lines without variables
+ * pass through verbatim; a dropped line takes its indented children with it.
+ */
+export declare const instantiate: (templates: readonly (readonly string[])[], lookup: (name: string) => unknown) => Instantiation;
+//# sourceMappingURL=template.d.ts.map

package/dist/internal/connect/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,MAAM,OAAO,GAAG;IACpB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;IAClD,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CACtC,CAAA;AAED,MAAM,MAAM,CAAC,GAAG,OAAO,CAAA;AAEvB,wDAAwD;AACxD,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1D,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC,CAAA;AAkBD;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAgDpF,CAAA;AAID;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,EAAE,UAAU,SAAS,GAAG,SAAS,KAAG,SAqC7E,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,QAAQ,OAAO,EAAE,MAAM,MAAM,KAAG,OAYvD,CAAA;AA0CD;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,WAAW,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,KAChC,aAsCF,CAAA"}