@happyvertical/smrt-app-shell 0.60.17 → 0.61.0

package/dist/engine/host.d.ts

@@ -1,12 +1,96 @@
 import { EventEmitter } from 'node:events';
 import { type Command, type ExecuteOptions, type Plan, type Template } from './commands.ts';
-import { type AppDefinition } from './definition.ts';
+import { type AppDefinition, type Step } from './definition.ts';
+import { type DraftMarker } from './draft.ts';
+import { type DefinitionDiff, type DraftChain, type PublishMethod } from './publish.ts';
 import type { VersionStore } from './store.ts';
 type Row = Record<string, unknown>;
 export interface HostOptions {
     store: VersionStore;
     /** The worker entry. Defaults to `./app-worker.ts` or `.js` next to this module. */
     workerUrl?: URL | string;
+    /**
+     * Start frozen: every structural command is refused (see
+     * {@link AppHost.setFrozen}). Records, reports, the app's own tools and REST
+     * routes, and `exportTemplate` keep working.
+     */
+    frozen?: boolean;
+    /**
+     * Approve risky commands, `_delete` tools and REST `DELETE` without being
+     * asked. For a DRAFT host only: `open` refuses it unless `dataDir` is a draft
+     * directory made by `forkDraft` (it holds the engine's marker, naming a
+     * different live directory). It is read once, here, into a private field:
+     * there is no setter, so it cannot be turned on later or for the live host.
+     */
+    autoApprove?: boolean;
+}
+export interface ForkDraftOptions {
+    /**
+     * The new draft's version store, EMPTY. `forkDraft` seeds it with a copy of
+     * the live current version (the draft's BASE record, same version number)
+     * and points `current` at it; every draft version after that has a higher
+     * number. The base record is not a draft version.
+     */
+    store: VersionStore;
+}
+/** Where a publish is, for `PublishOptions.onStage` (tests inject failures there). */
+export type PublishStage = 'copied' | 'rehearsed' | 'snapshotted' | 'journaled' | 'retired' | 'moved-aside' | 'swapped' | 'respawned' | 'committed';
+export interface PublishVersionPreview {
+    /** The number this version gets in live. */
+    version: number;
+    /** Its number in the draft. */
+    draftVersion: number;
+    author: string;
+    summary: string;
+    steps: Step[];
+    /** The SQL the rehearsal ran for it. */
+    statements: string[];
+}
+/** What a publish would do, from a rehearsal on a fresh copy of the current live data. */
+export interface PublishPreview {
+    /** Pass this as `PublishOptions.expect`; publish refuses if the draft's chain no longer matches. */
+    digest: string;
+    risky: true;
+    fromVersion: number;
+    toVersion: number;
+    versions: PublishVersionPreview[];
+    /** Live's current definition against the draft's final one. */
+    definition: DefinitionDiff;
+    /** Archived values and tables the changes create (what undo restores from). */
+    archives: {
+        values: number;
+        tables: number;
+    };
+    /** EVERY method of the final definition, in full, marked added/changed/unchanged. */
+    methods: PublishMethod[];
+}
+export interface PublishOptions {
+    author: string;
+    /** Required: a publish is always risky. Only the shell's approval sets it. */
+    approved?: boolean;
+    /** The `digest` of the preview the owner saw. */
+    expect: string;
+    /** Tags the history summaries: "[draft: <name>] <summary>". */
+    draftName?: string;
+    /**
+     * Called after each stage; throwing aborts and rolls back as if that stage
+     * had failed. For tests. After `committed` the publish is final: errors are ignored.
+     */
+    onStage?: (stage: PublishStage) => void | Promise<void>;
+}
+export interface PublishResult {
+    /** The version live is on now. */
+    version: number;
+    /** The versions the publish added, oldest first. */
+    versions: number[];
+    summary: string;
+    /** The retained copy of the data as it was before (snapshots/…-migrate-prepublish.db). */
+    snapshot: string;
+    archives: {
+        values: number;
+        tables: number;
+    };
+    appRestartMs: number;
 }
 export interface ChangeResult {
     version: number;
@@ -53,6 +137,7 @@ export interface VersionSummary {
     current: boolean;
 }
 export declare class AppHost extends EventEmitter {
+    #private;
     def: AppDefinition;
     version: number;
     readonly dataDir: string;
@@ -61,6 +146,14 @@ export declare class AppHost extends EventEmitter {
     private workerUrl;
     private app;
     private closed;
+    private frozenNow;
+    /** What boot did about an interrupted publish: `rolled-back` put the old data back. */
+    recovery: 'none' | 'rolled-forward' | 'rolled-back';
+    /** Set when this host is a draft copy (its directory holds the draft marker). */
+    readonly draft: DraftMarker | null;
+    /** Record/tool/REST calls currently inside the worker (see {@link drainInflight}). */
+    private inflight;
+    private idleWaiters;
     /** Changes are applied one at a time. Work inside the queue must not wait on it. */
     private queue;
     private constructor();
@@ -84,6 +177,15 @@ export declare class AppHost extends EventEmitter {
     private applyChange;
     /** What a command would do, without changing anything. */
     plan(cmd: Command): Promise<Plan>;
+    /** True while structural commands are refused. */
+    get frozen(): boolean;
+    /**
+     * Freeze or thaw the host. Frozen, every command in `STRUCTURAL_COMMANDS`
+     * (and `plan` of it) is refused with code `refused`; nothing about records
+     * changes. The shell freezes the live host while a draft is open.
+     */
+    setFrozen(frozen: boolean): void;
+    private refuseIfFrozen;
     /**
      * Apply a command. A risky one throws {@link ApprovalRequiredError} unless
      * `approved` is true, and then nothing has changed.
@@ -98,6 +200,13 @@ export declare class AppHost extends EventEmitter {
     private analyse;
     private assertValid;
     private analyseUndo;
+    /**
+     * Undo back to `target`: the same step as `undo`, repeated newest first, as
+     * one command with one decision. Each step is its own consistent state (its
+     * own swap and store write), so a failure part-way leaves the app at the
+     * version it had reached, and says so.
+     */
+    private analyseUndoTo;
     /** The model and field stored in `table.column` under `def`. */
     private locate;
     /** The chain from the current version back to the root, newest first. */
@@ -108,6 +217,71 @@ export declare class AppHost extends EventEmitter {
     /** Talk to the app. Callers inside the change queue use this; others use onApp. */
     private callApp;
     private onApp;
+    /**
+     * Wait for the calls already inside the worker to finish. Used inside the
+     * change queue, where no new call can start (see {@link onApp}), before a
+     * consistent copy of the data is taken.
+     */
+    private drainInflight;
+    /**
+     * Start a draft: copy the live data into `draftDir` (a directory that must
+     * not exist yet; this call creates it) and return a second host over the
+     * copy, with `autoApprove` on. The copy is a `VACUUM INTO` taken in the
+     * change queue with no call in flight, so it is one consistent state; live is
+     * only read. If anything fails, the directory this call created is removed.
+     * Only an ordinary (live) host can fork. Live may keep serving records while
+     * the draft is open; the caller freezes live structure with `setFrozen`.
+     */
+    forkDraft(draftDir: string, opts: ForkDraftOptions): Promise<AppHost>;
+    /**
+     * Throw this draft away: stop its app and delete its directory (only a
+     * directory holding the draft marker is ever deleted). The caller discards
+     * the draft's version store.
+     */
+    discard(): Promise<void>;
+    /**
+     * This draft's versions since its base, oldest first, with the base record.
+     * What a publish takes from the draft.
+     */
+    draftChain(): Promise<DraftChain>;
+    /** Checks shared by preview and publish; runs inside the change queue. */
+    private publishInputs;
+    /** The version numbers a publish of `chain` would give: after everything live's store holds. */
+    private nextNumbers;
+    /**
+     * Replay the draft's versions, in order, onto the copy of live in `dir`: one
+     * short worker per version, with that version's stored definition and steps
+     * and the number it will have in live (archives are keyed by it). Ends by
+     * writing the result as one standalone file, `dir/final/app.db`. Touches
+     * nothing but `dir`.
+     */
+    private replay;
+    /**
+     * What publishing `draft` would do: the draft's versions replayed on a fresh
+     * copy of the CURRENT live data (the live app is not touched and only waits
+     * while the copy is taken). `digest` pins the answer for `publishDraft`.
+     */
+    previewPublish(draft: AppHost): Promise<PublishPreview>;
+    /**
+     * Publish `draft` into live. Always needs `approved: true` and the `expect`
+     * digest of a preview; refuses if the draft's chain, or the app it started
+     * from, is not what that preview was of.
+     *
+     * It rehearses on a fresh copy of the current live data (so records added
+     * since the fork are kept and draft records are not), then swaps the file:
+     * the old data is first copied to snapshots/<ts>-0-migrate-prepublish.db,
+     * live's files are renamed aside and the rehearsed file renamed into place.
+     * The versions land in live as N ordinary versions (numbers after live's
+     * highest, summaries tagged with `draftName`), so `undo` / `undoTo` work.
+     * Any failure before the store is written puts the old files back (live's
+     * `app.db` is byte-for-byte what it was) and leaves the version unchanged.
+     * Live records wait (not fail) while this runs. The caller discards the draft.
+     */
+    publishDraft(draft: AppHost, opts: PublishOptions): Promise<PublishResult>;
+    private persistVersions;
+    private doPublish;
+    /** Undo a failed publish: put live back exactly as it was and start it again. */
+    private abortPublish;
     list(model: string, limit?: number): Promise<Row[]>;
     get(model: string, id: string): Promise<Row>;
     create(model: string, data: Row): Promise<Row>;