videobook-engine 2.0.1 → 5.0.1

package/dist/fork.d.ts

@@ -0,0 +1,148 @@
+import type { CatalogBackupConfig, ContentStore, EngineIdentity } from "./engine-types.js";
+import { type Engine } from "./engine.js";
+/**
+ * Fork bootstrap and merge-back integration (ve-mim.7; see
+ * docs/engine-layout.md "Forks and merge-back integration").
+ *
+ * A fork is, from the engine's point of view:
+ *
+ * 1. a platform fork — creating the hosted copy of the catalog and giving it
+ *    a URL is the hosting layer's job, out of engine scope;
+ * 2. a clone of the catalog into a local engine root (`bootstrapFork`);
+ * 3. a public-read object store keyed by SHA-256. `ContentStore` stays the
+ *    abstraction; the existing `ensureLocal` lazy fetch in src/cas.ts makes
+ *    upstream objects readable to forkers on first touch. Whether the
+ *    fork's store proxies to upstream's is a hosting concern — the engine
+ *    only ever sees one `ContentStore` per engine root.
+ *
+ * The live-engine never-pulls rule stands: an open engine never fetches,
+ * pulls, or merges. Integration happens in a DEDICATED merge-back flow
+ * (`mergeBack`) that runs on a throwaway copy of a closed catalog database
+ * in a temp directory, never on the user's open live catalog.
+ *
+ * ve-wsu routing (doltlite 0.11.37, verified empirically):
+ *
+ * - `dolt_clone` of the full 28-table catalog produces a malformed database
+ *   (`invalid rootpage` on a secondary autoindex; the file cannot even be
+ *   opened for reads). `bootstrapFork` therefore bootstraps from a byte
+ *   snapshot of a healthy catalog database; a URL clone is attempted and
+ *   health-validated, and surfaces a typed FEATURE_UNAVAILABLE error while
+ *   the upstream bug stands.
+ * - `dolt_merge`'s uncommitted-changes guard misfires on the full catalog
+ *   (every table reports phantom `modified` status with zero row diffs).
+ *   Committing the phantom dirt passes the guard, but the merge then dies
+ *   in schema loading (`schema conflict on table 'sqlite_autoindex_*'`),
+ *   and `dolt_checkout` corrupts the working set, so no branch dance can
+ *   produce a true two-parent merge commit either. `mergeBack` therefore
+ *   performs the same three-way merge at the projection layer
+ *   (`dolt_merge_base` + `dolt_at_<table>` snapshots, which are unaffected)
+ *   under the exact src/merge-policy.ts policy, and lands a forward
+ *   integration commit on main that records the integrated fork head in a
+ *   `merged-revision` trailer. When ve-wsu is fixed, the projection merge
+ *   in `mergeRefs` is the single swap point for `mergeWithPolicy` +
+ *   `dolt_merge`.
+ */
+export interface ForkBootstrapOptions {
+    dataDir: string;
+    workspaceDir: string;
+    /**
+     * Byte snapshot of a healthy upstream catalog database (a copy of its
+     * `videobook.db` taken while the upstream engine was closed). This is the
+     * bootstrap that works with doltlite 0.11.37; the hosting layer provides
+     * the snapshot when it creates the platform fork.
+     */
+    snapshotPath?: string;
+    /**
+     * Upstream catalog remote URL to `dolt_clone`. Currently blocked by
+     * ve-wsu for full engine catalogs; the clone is attempted and the result
+     * health-validated so this path starts working unchanged once doltlite
+     * is fixed. Mutually exclusive with `snapshotPath`.
+     */
+    upstreamUrl?: string;
+    remoteObjects?: ContentStore;
+    objectPrefix?: string;
+    /** Remote registration for the fork's own catalog remote (push target). */
+    catalogBackup?: CatalogBackupConfig;
+    identity?: EngineIdentity;
+}
+export interface MergeBackOptions {
+    /**
+     * Path to a healthy upstream catalog database file (its `videobook.db`).
+     * The file is only read — it is copied into a temp workspace and all
+     * merging happens there. The upstream engine must be closed (or pass a
+     * snapshot taken while it was closed) so the copy is consistent.
+     */
+    upstreamDbPath: string;
+    /**
+     * Upstream catalog remote to push the integration commit to. Defaults to
+     * the `origin` remote already registered in the upstream database.
+     */
+    upstreamRemote?: CatalogBackupConfig;
+    /** Fork catalog remote to fetch the fork's commits from. */
+    forkRemote: {
+        name?: string;
+        url: string;
+    };
+    forkBranch?: string;
+    /** Upstream object store: fork objects are uploaded here before push. */
+    upstreamObjects?: ContentStore;
+    /** Fork object store (public-read): source of the fork's new objects. */
+    forkObjects?: ContentStore;
+    objectPrefix?: string;
+    /** Commit author for the integration commit. */
+    author?: string;
+    /** Directory for the throwaway merge workspace (defaults to a temp dir). */
+    workDir?: string;
+    /** Keep the merge workspace for inspection instead of deleting it. */
+    keepWorkDir?: boolean;
+}
+export interface MergeBackResult {
+    /** HEAD of upstream main after the flow (the integration commit). */
+    integrationCommit: string;
+    /** Merge base used for the three-way merge. */
+    baseRevision: string;
+    /** Upstream main head before the merge. */
+    oursRevision: string;
+    /** Integrated fork head, recorded in the commit's merged-revision trailer. */
+    theirsRevision: string;
+    /** True when the fork was already fully integrated (no commit minted). */
+    alreadyIntegrated: boolean;
+    /** Fork object hashes uploaded to the upstream object store. */
+    uploadedObjects: string[];
+    reconciledTranscripts: number;
+    reconciledSequences: number;
+    /** Merge workspace path when `keepWorkDir` was set. */
+    workDir?: string;
+}
+export interface RowConflict {
+    table: string;
+    key: Record<string, unknown>;
+    reason: string;
+}
+/**
+ * Bootstraps a fork: clones the upstream catalog into a new local engine
+ * root and opens it as a normal engine. The fork is a full citizen from
+ * there — it commits on its own main, backs up to its own catalog remote,
+ * and reads upstream objects lazily through its configured `ContentStore`.
+ * It never pulls; integration is the merge-back flow's job.
+ */
+export declare function bootstrapFork(options: ForkBootstrapOptions): Promise<Engine>;
+/**
+ * Integrates a fork back into upstream main.
+ *
+ * Runs entirely in a throwaway copy of the upstream catalog inside a temp
+ * directory: fetches the fork, merges under the engine merge policy
+ * (same-schema precondition, constraint verification, deterministic
+ * singleton reconcile; artifact identity is artifact_id, so there is no
+ * name-conflict class to check), uploads the fork's new
+ * objects to the upstream object store BEFORE the catalog ref moves — the
+ * same objects-before-push ordering as engine.storage.backup — lands one
+ * forward integration commit on main, and pushes it.
+ *
+ * The caller's open engines are never touched: the upstream database file
+ * is only read (copied), and the fork is only fetched from. Conflicts and
+ * violations surface as the typed MERGE_CONFLICT / MERGE_VIOLATION /
+ * SCHEMA_INCOMPATIBLE errors from src/merge-policy.ts.
+ */
+export declare function mergeBack(options: MergeBackOptions): Promise<MergeBackResult>;
+//# sourceMappingURL=fork.d.ts.map

package/dist/fork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../src/fork.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AASxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,4DAA4D;IAC5D,UAAU,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,eAAe,CAAC,EAAE,YAAY,CAAC;IAC/B,yEAAyE;IACzE,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IAChE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAoDjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAc1B"}