@omgbase/core 0.11.1 → 0.19.0

package/dist/src/mutate/effects.d.ts

@@ -0,0 +1,363 @@
+import type { Store } from "../core/store/store.js";
+import { type IdMinter } from "../core/ids.js";
+import { type InboundLink } from "../graph/inbound-links.js";
+import type { ChangesetPlanner, Op } from "./apply.js";
+import { type DocBase } from "./commit.js";
+import type { DocStore } from "./doc-store.js";
+import { type LinkRepairCount, type RetargetHit } from "./macros.js";
+import type { At, Expect } from "./ops.js";
+import type { IdentityPreview } from "./opset.js";
+import { MutationError } from "./tree.js";
+/** What an effect addresses. `section` is a derived range (ADR-005), never a stored id.
+ *  `symbol` (3.2, §11.8 "Sugar"): a bare `"$new.n"` target whose kind — document or block — the
+ *  symbol table decides when the effect is resolved; it never reaches a resolved effect. */
+export type EffectTarget = {
+    kind: "document";
+    id?: string;
+    path?: string;
+} | {
+    kind: "block";
+    id: string;
+} | {
+    kind: "node";
+    id: string;
+} | {
+    kind: "section";
+    heading_id: string;
+} | {
+    kind: "symbol";
+    id: string;
+};
+export type EffectAt = At;
+/** Guards: the kernel's two CAS fields plus the document's `current_rev` at plan time. */
+export interface EffectExpect {
+    content_hash?: string;
+    parent_children_hash?: string;
+    revision?: string;
+}
+/** Per-block guards for `remove`/`merge` (the kernel's `expect[id]`), keyed by block id. */
+export type EffectExpectMap = Record<string, Expect>;
+export type Effect = {
+    op: "create";
+    path: string;
+    markdown: string;
+    frontmatter?: Record<string, unknown>;
+} | {
+    op: "insert";
+    into: EffectTarget;
+    at?: EffectAt;
+    markdown: string;
+    expect?: EffectExpect;
+} | {
+    op: "set";
+    target: EffectTarget;
+    field: string;
+    value: unknown;
+    expect?: EffectExpect;
+} | {
+    op: "unset";
+    target: EffectTarget;
+    field: string;
+    expect?: EffectExpect;
+} | {
+    op: "move";
+    target: EffectTarget;
+    to: string;
+    retarget_inbound?: boolean;
+} | {
+    op: "move";
+    targets: EffectTarget[];
+    into: EffectTarget;
+    at?: EffectAt;
+    expect?: EffectExpect;
+} | {
+    op: "remove";
+    target: EffectTarget;
+} | {
+    op: "remove";
+    targets: EffectTarget[];
+    expect?: EffectExpectMap;
+} | {
+    op: "split";
+    target: EffectTarget;
+    at: number[];
+    expect?: EffectExpect;
+} | {
+    op: "merge";
+    targets: EffectTarget[];
+    separator?: string;
+    expect?: EffectExpectMap;
+} | {
+    op: "retarget";
+    repairs: {
+        from: string;
+        to: string;
+    }[];
+    path_glob?: string;
+};
+export declare const EFFECT_OPS: readonly ["create", "insert", "set", "unset", "move", "remove", "split", "merge", "retarget"];
+/** `$new.<n>`: an identity an earlier effect of the same request creates (§11.1). */
+export declare const NEW_SYMBOL_RE: RegExp;
+export declare function isNewSymbol(s: string): boolean;
+/** A target with its document resolved to `{ id, path }` (path in the storage form; a `$new.n` document keeps its symbol). */
+export type ResolvedTarget = {
+    kind: "document";
+    id: string;
+    path: string;
+} | {
+    kind: "block";
+    id: string;
+} | {
+    kind: "node";
+    id: string;
+} | {
+    kind: "section";
+    heading_id: string;
+};
+export type ResolvedEffect = {
+    op: "create";
+    path: string;
+    markdown: string;
+    frontmatter?: Record<string, unknown>;
+} | {
+    op: "insert";
+    into: ResolvedTarget;
+    at: EffectAt;
+    markdown: string;
+    expect?: EffectExpect;
+} | {
+    op: "set";
+    target: ResolvedTarget;
+    field: string;
+    value: unknown;
+    expect?: EffectExpect;
+} | {
+    op: "unset";
+    target: ResolvedTarget;
+    field: string;
+    expect?: EffectExpect;
+} | {
+    op: "move";
+    target: ResolvedTarget;
+    to: string;
+    retarget_inbound: boolean;
+} | {
+    op: "move";
+    targets: ResolvedTarget[];
+    into: ResolvedTarget;
+    at: EffectAt;
+    expect?: EffectExpect;
+} | {
+    op: "remove";
+    target: ResolvedTarget;
+} | {
+    op: "remove";
+    targets: ResolvedTarget[];
+    expect?: EffectExpectMap;
+} | {
+    op: "split";
+    target: ResolvedTarget;
+    at: number[];
+    expect?: EffectExpect;
+} | {
+    op: "merge";
+    targets: ResolvedTarget[];
+    separator: string;
+    expect?: EffectExpectMap;
+} | {
+    op: "retarget";
+    repairs: {
+        from: string;
+        to: string;
+    }[];
+    path_glob?: string;
+};
+/** The argument-shape error of the surface, thrown from the planner: `filter_invalid { reason, hint: "arguments" }`. */
+export declare function effectInvalid(message: string): MutationError;
+/** The `-> ` leader (3.2, §11.8 "Sugar"): a string beginning exactly so is an OQX expression, the rest of the string. */
+export declare const EXPRESSION_LEADER = "-> ";
+/** A path-looking string: contains `/` or ends `.md` (the bare document target of §11.8 "Sugar"). */
+export declare function looksLikePath(s: string): boolean;
+/** A bare id of the three target kinds (§11.8 "Sugar"). */
+export declare function isTargetId(s: string): boolean;
+/**
+ * A bare string where a target object is expected (3.2, §11.8 "Sugar"): a
+ * path-looking string → `{ kind: "document", path }`; a `b_`/`d_`/`n_` id →
+ * that kind; `$new.n` → `{ kind: "symbol", id }` (its kind is the symbol
+ * table's at resolution); a `#` locator → `filter_invalid` with a `fix`;
+ * anything else is no target. A `-> ` leader never reaches here from the
+ * planner (`select.ts` desugars it first); as a library input it is refused
+ * the same way, naming the planner.
+ */
+export declare function bareTarget(ref: string, here: string): EffectTarget;
+export declare function validateTarget(v: unknown, here: string, kinds: readonly EffectTarget["kind"][]): EffectTarget;
+/** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`). */
+export declare function validateEffect(v: unknown, i: number): Effect;
+/** The whole list; a non-array or an empty list is a shape error too. */
+export declare function validateEffects(v: unknown): Effect[];
+export declare const FRONTMATTER_FIELD: RegExp;
+/** The focus a conflict names: `{ kind, target, field? }`. */
+export interface Focus {
+    kind: "scalar" | "positional" | "identity";
+    target: {
+        kind: "document" | "block" | "node" | "path";
+        id?: string;
+        path?: string;
+    };
+    field?: string;
+}
+export declare function conflictingEffects(effects: [number, number], focus: Focus): MutationError;
+/**
+ * What one effect addresses and retires, for the conflict rules. `scalar` is a
+ * value write to one key; `docs`/`blocks`/`paths` are everything the effect
+ * addresses (an earlier retirement of any of them is a conflict); `retires*`
+ * is what later effects may no longer address.
+ */
+export interface FocusInfo {
+    scalar?: {
+        key: string;
+        target: Focus["target"];
+        field: string;
+        op: "set" | "unset";
+        value: unknown;
+    };
+    /** every scalar (block, markdown) focus of a retarget */
+    scalars?: {
+        key: string;
+        target: Focus["target"];
+        field: string;
+    }[];
+    docs: string[];
+    blocks: string[];
+    paths: string[];
+    retiresDocs?: string[];
+    retiresBlocks?: string[];
+    retiresPaths?: string[];
+    /** `set document.content`: the whole document is rewritten */
+    wholeDoc?: string;
+}
+/** The focus bookkeeping over an ordered effect list (§11.3). */
+export declare class ConflictTracker {
+    private readonly canonical;
+    private readonly scalar;
+    private readonly retiredDocs;
+    private readonly retiredBlocks;
+    private readonly retiredPaths;
+    private readonly touchedDocs;
+    readonly diagnostics: string[];
+    constructor(canonical: (v: unknown) => string);
+    /** Check effect `i`; returns `false` when it is an identical duplicate to drop. Throws `conflicting_effects`. */
+    check(i: number, info: FocusInfo, describe: string): boolean;
+}
+/** `$new.n` symbols in allocation order (§11.4 `new_ids`). */
+export declare class SymbolTable {
+    readonly entries: {
+        symbol: string;
+        kind: "block" | "document";
+    }[];
+    alloc(kind: "block" | "document"): string;
+    kindOf(symbol: string): "block" | "document" | undefined;
+}
+/** A `create` as the plan carries it (§11.4 `opset.creates[]`, 3.0): its document symbol, path, the
+ *  composed bytes, and the index of the first kernel op planned after it (`ops.length` when none) —
+ *  where `execute` adopts it again so the replay mints its block ids in the plan's order. */
+export interface CreateEntry {
+    symbol: string;
+    path: string;
+    source: string;
+    before_op: number;
+}
+/** `preview.retarget[]` (§11.4, 3.0): what a `retarget` effect found — the `links_repair` hits and pair counts. */
+export interface RetargetPreview {
+    effect_index: number;
+    hits: RetargetHit[];
+    pairs: LinkRepairCount[];
+}
+export interface MoveDraft {
+    id: string;
+    from: string;
+    to: string;
+    currentRev: string | null;
+    /** read at plan time for the move's own preview; `execute` re-reads */
+    inbound: InboundLink[];
+    retargeted: {
+        blocks: string[];
+        docs: string[];
+    } | null;
+}
+export interface TombstoneDraft {
+    id: string;
+    path: string;
+    currentRev: string | null;
+}
+export interface LoweringContext {
+    store: Store;
+    repoId: string;
+    docStore: DocStore;
+    planner: ChangesetPlanner;
+    symbols: SymbolTable;
+    /** `$new.n` (a block an op minted) → the kernel placeholder `$k.ids[j]` that names it */
+    blockSymbols: Map<string, string>;
+    /** the created documents, in effect order (`opset.creates`) */
+    creates: CreateEntry[];
+    /** `preview.identity`: per `set content` document, the whole-document planner's identity consequences */
+    identity: Map<string, IdentityPreview>;
+    /** `preview.retarget`: per `retarget` effect, its hits and pair counts */
+    retargets: RetargetPreview[];
+    moves: MoveDraft[];
+    tombstones: TombstoneDraft[];
+    /** doc id → the file head (`set_frontmatter[].raw`), last write per document */
+    heads: Map<string, string>;
+    /** the kernel ops pushed, in order (`opset.ops`) */
+    ops: Op[];
+    /** `preconditions.blocks`: every pinned content hash, in first-pin order */
+    pins: Map<string, string>;
+    /** `preconditions.parents` */
+    parents: {
+        doc: string;
+        parent: string | null;
+        parent_children_hash: string;
+    }[];
+    /** `preconditions.absent_paths` */
+    absentPaths: string[];
+    /** docs addressed by a move/remove document effect, in effect order (`preconditions.docs` after the loaded ones) */
+    docBases: Map<string, DocBase>;
+    tracker: ConflictTracker;
+    canonical: (v: unknown) => string;
+    /** the resolved effects kept (dropped duplicates excluded) */
+    resolved: ResolvedEffect[];
+    /** `preview.summary` (3.3, §11.9): one line in words per resolved effect, in order */
+    summary: string[];
+}
+/** Resolve a document target: an existing document's `{ id, path }`, or a `$new.n` document this plan creates. */
+export declare function resolveDocumentTarget(ctx: LoweringContext, t: Extract<EffectTarget, {
+    kind: "document";
+}>): Extract<ResolvedTarget, {
+    kind: "document";
+}>;
+/** An existing document's `{ id, path }` for a literal document target (`doc_missing`; `filter_invalid` when `id` and `path` disagree). */
+export declare function findDocumentTarget(store: Store, repoId: string, t: Extract<EffectTarget, {
+    kind: "document";
+}>): Extract<ResolvedTarget, {
+    kind: "document";
+}>;
+/** `1 block` / `2 blocks` (an `s` on every noun of the table). */
+export declare function plural(n: number, noun: string): string;
+/** Resolve one validated effect's targets (§11.4): documents to `{ id, path }`, defaults made explicit; `i` names the effect in messages. */
+export declare function resolveEffect(ctx: LoweringContext, e: Effect, i?: number): ResolvedEffect;
+/** Shift a kernel op's `$n.ids[i]` placeholders by `offset` (an opset planned alone, spliced into a longer op list). */
+export declare function shiftPlaceholders(op: Op, offset: number): Op;
+/**
+ * Lower effect `i` (already validated): resolve its targets, classify its
+ * focus (throwing `conflicting_effects`, or dropping an identical duplicate
+ * with a diagnostic), then push its kernel ops / document drafts. Returns the
+ * resolved effect, or null when it was dropped.
+ */
+export declare function lowerEffect(ctx: LoweringContext, i: number, effect: Effect): ResolvedEffect | null;
+/**
+ * The symbolic minter (§11.4): `b` and `d` mints yield `$new.0, $new.1, …`
+ * from `symbols`, so a plan consumes no real id and the kernel (id-agnostic
+ * for rendering, ADR-002) renders exact bytes. Planning mints nothing else —
+ * `c`/`r`/`x`/`e` are minted inside the commit transaction.
+ */
+export declare function symbolicMinter(symbols: SymbolTable): IdMinter;