@omgbase/core 0.11.1 → 0.19.0

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

@@ -0,0 +1,210 @@
+import type { Store } from "../core/store/store.js";
+import { type ApplyRevision, type Op, type OpResult } from "./apply.js";
+import { type DocStore } from "./doc-store.js";
+import { type CreateEntry, type ResolvedEffect, type RetargetPreview } from "./effects.js";
+import type { IdentityPreview } from "./opset.js";
+import { type Selection } from "./select.js";
+export declare const PLAN_VERSION: 1;
+/** The lowering + conflict rules version (§11.4; the `matcher_v` precedent). */
+export declare const PLANNER_V: "p3";
+/** A kernel op as the plan spells it on the wire: the fixture spelling (`child_ids`). */
+export type WireOp = Exclude<Op, {
+    op: "update";
+}> | {
+    op: "update";
+    block: string;
+    markdown?: string;
+    attrs?: Record<string, unknown>;
+    expect?: {
+        content_hash?: string;
+        parent_children_hash?: string;
+    };
+    trivia?: string;
+    child_ids?: Record<string, string>;
+};
+/** The lowered form `execute` replays (§11.4): every key present, `[]` when empty. */
+export interface PlanOpset {
+    /** `create` → the composed file, its document symbol and the index of the first kernel op planned after it (3.0; a later `set frontmatter.<k>` on the symbol is a head below) */
+    creates: CreateEntry[];
+    /** `move document` → the row/file rename (its retarget updates are in `ops`) */
+    moves: {
+        id: string;
+        from: string;
+        to: string;
+    }[];
+    /** `remove document` */
+    tombstones: {
+        id: string;
+        path: string;
+    }[];
+    /** per document, the file head — everything before the first block (frontmatter incl. fences and separator) */
+    set_frontmatter: {
+        doc: string;
+        raw: string;
+    }[];
+    /** the kernel ops, in order; new structure is referenced by kernel placeholders `$k.ids[j]` */
+    ops: WireOp[];
+}
+export interface PlanPreconditions {
+    /** the row triples (`spec/mutate` §4 step 5) of every document the plan touches, loaded ones first in load order */
+    docs: {
+        id: string;
+        path: string;
+        base_revision: string | null;
+        hash: string | null;
+    }[];
+    /** every block content hash the plan pins (caller-given or pinned from the live row), first-pin order */
+    blocks: {
+        id: string;
+        content_hash: string;
+    }[];
+    /** the caller's destination-parent CAS pins */
+    parents: {
+        doc: string;
+        parent: string | null;
+        parent_children_hash: string;
+    }[];
+    /** paths that must have no live document and no file: `create` paths and move destinations */
+    absent_paths: string[];
+}
+export interface PlanPreview {
+    results: OpResult[];
+    revisions: ApplyRevision[];
+    diffs: Record<string, {
+        before: string;
+        after: string;
+    }>;
+    /** (3.0) per `set content` document: the whole-document planner's identity consequences; present when a plan has one */
+    identity?: Record<string, IdentityPreview>;
+    /** (3.0) per `retarget` effect: its hits and pair counts; present when a plan has one */
+    retarget?: RetargetPreview[];
+    /** (3.3, §11.9) one line in words per resolved effect, in order — the plan as a worked example; `[]` for a zero-hit selection */
+    summary: string[];
+}
+/** The executable core the digest covers. */
+export interface PlanCore {
+    version: typeof PLAN_VERSION;
+    planner_v: string;
+    effects: ResolvedEffect[];
+    opset: PlanOpset;
+    preconditions: PlanPreconditions;
+    new_ids: {
+        symbol: string;
+        kind: "block" | "document";
+    }[];
+    /** (3.1, §11.8) the selector, its templates and the hits it bound — present only for a selector plan */
+    selection?: Selection;
+}
+export interface Plan extends PlanCore {
+    plan_id: string;
+    diagnostics: string[];
+    /** (3.2, §11.8 "Sugar") a plain request's effects AS WRITTEN when one carried a `-> ` / `{ oqx }` expression;
+     *  not digested (the core already holds the concrete effects), recorded in the intent record as `templates` */
+    templates?: unknown[];
+    /** excluded from the digest; omittable on echo */
+    preview?: PlanPreview;
+}
+export interface Receipt {
+    plan_id: string;
+    /** the one `commits` row (`null` when the plan had nothing to commit) */
+    commit: string | null;
+    revisions: ApplyRevision[];
+    /** `$new.n` → the minted id */
+    new_ids: Record<string, string>;
+    committed: true;
+    /** (3.3, §11.9) the plan's `preview.summary` — what was committed, in words (`[]` when the plan was handed back without its preview) */
+    summary: string[];
+}
+export { canonicalJson } from "./canonical.js";
+/** The executable core of a plan — the six digested keys (seven with `selection`), nothing else. */
+export declare function planCore(p: PlanCore): PlanCore;
+/** `plan_id = hex(sha256(canonical(core)))` (§11.5). */
+export declare function planDigest(core: PlanCore): string;
+export interface PlanEffectsRequest {
+    repoId: string;
+    /** Working-tree root for the default doc store (the `path_taken` disk check; the move/remove previews). */
+    rootPath?: string;
+    docStore?: DocStore;
+    omgbaseDir?: string;
+    /** The effects as given (validated here: a shape error is `filter_invalid`); with `select`, the templates (§11.8). */
+    effects: unknown;
+    /** (3.1) an OQX selector: its hits × `effects` (templates) are the effects planned */
+    select?: unknown;
+    /** (3.1) `{ max }`: the bound on the selection (`selection_too_large` beyond it); the implicit ceiling without it */
+    expect?: unknown;
+}
+/** The kernel op as the plan carries it (`childIds` → `child_ids`). */
+export declare function wireOp(o: Op): WireOp;
+/** A plan's op back to the kernel's spelling. */
+export declare function kernelOp(o: WireOp): Op;
+/**
+ * Lower an ordered effect list into a frozen Plan (§11.6): under the symbolic
+ * minter, resolve and lower each effect in order (conflicts by focus kind,
+ * identical duplicates dropped with a diagnostic), render the touched documents,
+ * freeze the preconditions, digest the core. Reads only; mints no real id.
+ */
+export declare function planEffects(store: Store, req: PlanEffectsRequest): Plan;
+export interface ExecuteRequest {
+    repoId: string;
+    rootPath?: string;
+    docStore?: DocStore;
+    omgbaseDir?: string;
+    /** the commit's `actor` (null when the caller has none — a fixture step without one) and `reason` */
+    origin: {
+        actor: string | null;
+        reason?: string;
+    };
+    /** Commit timestamp (RFC 3339 UTC); defaults to now (see `ApplyRequest.ts`). */
+    ts?: string;
+}
+/**
+ * The plan form's admission (§11.7): `version` first — anything but 1 is
+ * `unsupported_plan_version { version, supported: [1] }` — then the core's keys
+ * must be present (`filter_invalid`), then the recomputed digest must equal the
+ * embedded `plan_id` (`plan_mismatch { expected, actual }`). `preview` and
+ * `diagnostics` are ignored.
+ */
+export declare function admitPlan(input: unknown): Plan;
+/** `execute { plan }` (§11.7): admit, then commit exactly that plan. */
+export declare function executePlan(store: Store, req: ExecuteRequest & {
+    plan: unknown;
+}): Receipt;
+/** `execute { plan_id, effects, select?, expect? }` (§11.7): re-plan (with the selector when one is given, §11.8); the digest must equal `plan_id`, else `plan_mismatch`. */
+export declare function executeByDigest(store: Store, req: ExecuteRequest & {
+    planId: string;
+    effects: unknown;
+    select?: unknown;
+    expect?: unknown;
+}): Receipt;
+/**
+ * `apply { effects }` with both halves kept (the sugar's seam — `sugar.ts`,
+ * the `omg` verbs, the whole-document update): the Plan always, and the
+ * Receipt when it committed (`dryRun` plans only — the CLI's `--dry-run`,
+ * spec/cli §3.6). Plan + execute run under one lock and one transaction,
+ * exactly as `applyEffects`.
+ */
+export declare function applyEffectsDetailed(store: Store, req: ExecuteRequest & {
+    effects: unknown;
+    select?: unknown;
+    expect?: unknown;
+    dryRun?: boolean;
+}): {
+    plan: Plan;
+    receipt?: Receipt;
+};
+/** `apply { effects, select?, expect? }` (§11.7): plan + execute under one lock and one transaction; `dryRun` returns the Plan. */
+export declare function applyEffects(store: Store, req: ExecuteRequest & {
+    effects: unknown;
+    select?: unknown;
+    expect?: unknown;
+    dryRun?: boolean;
+}): Plan | Receipt;
+/** Every string that is a key of `ids` replaced by its value, recursively (arrays and plain objects) — a plan's `$new.n` realized from a receipt's `new_ids`. */
+export declare function substituteSymbols<T>(value: T, ids: Record<string, string>): T;
+/**
+ * A planner error as the sugar reports it (`sugar.ts` `applySugar`): the
+ * `effect_index` the planner adds (§11.6) is dropped — the tool or verb built
+ * the effects itself, so the index names nothing the caller sent and the
+ * kernel's data (`op_index`, `block`, `current`, …) stays as pinned.
+ */
+export declare function stripEffectIndex(err: unknown): unknown;