@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/components/Application.d.ts

@@ -11,6 +11,27 @@ interface ApplicationConfig {
         allowInstallScripts?: boolean;
     };
     credentials?: CredentialReference[];
+    /**
+     * Databases this application gets a private fork of (harper#642), declared HERE — on the
+     * application's root-config entry, alongside `host` and `urlPath` — because which databases an
+     * application forks is a deployment decision, not something the application checks in. Declaring
+     * it in the application's own config.yaml is refused rather than ignored.
+     *
+     * `true` forks every database on the instance except `system` -- a snapshot of what exists when
+     * this application loads, not a standing subscription: a database created afterward is not
+     * retroactively branched.
+     *
+     * The fork is durable: it lives at a path derived from the application and database names, is
+     * adopted again on restart, and is invisible to other applications.
+     *
+     * The application must reach its data through `import { databases } from 'harper'`. The bare
+     * `databases`/`tables` globals are shared process-wide by the default `vm-current-context` loader
+     * and cannot be scoped, so an application that uses them reads and writes the BASE — silently.
+     * Per-application globals are a property of thread-level isolation, not of branching.
+     */
+    branchedDatabases?: string[] | true;
+    /** Run in a worker thread of its own that loads no other application. */
+    isolated?: boolean;
     [key: string]: unknown;
 }
 export declare class InvalidPackageIdentifierError extends TypeError {
@@ -28,10 +49,19 @@ export declare class InvalidInstallTimeoutError extends TypeError {
 export declare class InvalidCredentialsPropertyError extends TypeError {
     constructor(applicationName: string, credentials: unknown);
 }
+export declare class InvalidBranchedDatabasesError extends TypeError {
+    constructor(applicationName: string, detail: string);
+}
 export declare class InvalidCredentialEntryError extends TypeError {
     constructor(applicationName: string);
 }
 export declare function assertApplicationConfig(applicationName: string, applicationConfig: Record<'package', unknown> & Record<string, unknown>): asserts applicationConfig is ApplicationConfig;
+export declare function assertIsolationConfig(applicationName: string, isolated: unknown): void;
+/**
+ * A branch that cannot be honoured fails the application's load: falling back would hand it the
+ * shared database it asked not to have, with no signal that it happened.
+ */
+export declare function assertBranchedDatabases(applicationName: string, value: unknown): void;
 /**
  * Returns true when npm/git stderr indicates an SSH authentication failure —
  * git exits 128 with the standard "could not read" message, or the SSH layer
@@ -58,6 +88,7 @@ interface GitReference {
  */
 export declare function parseGitReference(packageIdentifier: string): GitReference | null;
 export declare const ASIDE_STAGING_DIR = ".deploy-aside";
+export declare const DEPLOY_STAGING_DIR = ".deploy-staging";
 type ExtractionTransaction = {
     commit(): Promise<void>;
     rollback(): Promise<void>;
@@ -69,6 +100,8 @@ type InstalledPackageMetadata = {
     hasLockfile: boolean;
     hasInstallableDependencies: boolean;
 };
+export declare function packageHasProductionInstallWork(packageJSON: any): boolean;
+export declare function packageHasAutomaticInstallWork(packageJSON: any): boolean;
 export declare function readInstalledPackageMetadata(directory: string): Promise<InstalledPackageMetadata>;
 export declare function installedPackageMetadataEqual(previous: InstalledPackageMetadata, current: InstalledPackageMetadata): boolean;
 export declare function installedRuntimeChanged(previous: InstalledPackageMetadata, current: InstalledPackageMetadata, installationIsOpaque: boolean): boolean;
@@ -83,17 +116,153 @@ export declare function installedRuntimeChanged(previous: InstalledPackageMetada
  * threads by the preparation lock below.
  */
 export declare function extractApplication(application: Application, deferCommit?: boolean): Promise<ExtractionTransaction | undefined>;
+/** `deployment_stagingRetention_maxCount`; 0 keeps none. Only a number or numeric string counts, so `true`/`[]`/blank cannot become "keep nothing". */
+export declare function getStagingRetentionMaxCount(): number;
+type DormantBuild = {
+    deploymentDirPath: string;
+    deploymentId: string;
+    completedAt: number;
+};
+/**
+ * Remove the oldest dormant builds beyond `maxCount`. The caller must hold the component's preparation lock;
+ * every catalogued build is re-derived under it before the kept set is chosen, so a catalog read unlocked
+ * cannot hold or miss a slot. Never throws: a failure must neither fail a component closed nor replace a
+ * deploy's own error.
+ *
+ * `pinnedDeploymentId` is never evicted. A delayed activation runs this preamble under the same lock it is
+ * about to activate under, so without the pin retention would delete the artifact the request named —
+ * immediately, when the knob is `0`. The pin is applied after the kept set is chosen, so a pinned build in
+ * the eviction tail leaves `maxCount + 1` on disk for the life of the request; the next preamble that does
+ * not pin it brings the count back down.
+ */
+export declare function pruneDormantBuilds(componentName: string, builds: DormantBuild[], maxCount: number, pinnedDeploymentId?: string): Promise<void>;
+export type ArtifactDescriptor = {
+    v: number;
+    component: string;
+    /** The root-config entry to publish with the activation; `null` for a payload build, which owns none. */
+    rootConfig: Record<string, unknown> | null;
+    installationIsOpaque: boolean;
+    isolated: boolean;
+};
+/** Where a candidate build lives: `<root>/.deploy-staging/<deploymentId>/<component>`. */
+export declare function candidateApplicationPath(componentDirPath: string, deploymentId: string): string;
+export declare function makeRollbackPlaceholderMovable(applicationDirPath: string, placeholderIdentity: {
+    dev: bigint;
+    ino: bigint;
+} | undefined): Promise<void>;
+/**
+ * Name the component that owns a deployment directory THIS CALL created, and take the directory back if that
+ * cannot be recorded.
+ *
+ * Ownership is published as part of the claim rather than at certification, because resolving and packing can
+ * take minutes and until a tree exists to infer an owner from, a directory answering to nobody is one another
+ * component will take for abandoned. Unattributed is a permanent refusal, though, so a failure here — a full
+ * disk, an EIO on the temp write or its sync — would burn this deployment id for good, every retry refused by
+ * its own wreckage. The removal is scoped to the directory this invocation made, and deliberately not
+ * broadened to one found by EEXIST: that directory may be another claimant's, and removing it is the race the
+ * refusal exists to prevent. Best-effort, because the claim failure is what the caller needs to see.
+ *
+ * `write` is a parameter so the failure is testable without a filesystem that can be made to fail on exactly
+ * this write and nothing else.
+ */
+export declare function publishClaimOwnership(deploymentDirPath: string, componentName: string, write?: (filePath: string, contents: string) => Promise<void>): Promise<void>;
+/**
+ * The components a deployment's evidence implicates, when its journal and its ownership sidecar disagree
+ * about whose it is — or `undefined` when there is no disagreement to act on.
+ *
+ * A sidecar that cannot answer is NOT disagreement: the journal names its own component and can settle it,
+ * so an unreadable sidecar must not block that. Only a sidecar that reads and names something else is the
+ * wedge, and then BOTH names are returned, sidecar first, because both are stuck — see
+ * `splitAttributionError`.
+ *
+ * Separated from either call site so the decision is testable on its own: the paths that reach it include
+ * one that requires a journal to appear between two reads under a lock, which no test can stage.
+ */
+export declare function splitAttributionOwners(journalOwner: string, sidecarOwner: string | undefined): [string, string] | undefined;
+/**
+ * Components that on-disk evidence says were left in a state nobody settled — determined READ-ONLY, so any
+ * thread can reach the same verdict.
+ *
+ * Recovery runs on the main thread only, but the components it could not settle still have to be failed
+ * closed on the workers that actually serve them, and a worker cannot be handed main's verdict: it boots
+ * through its own `loadRootComponents(true)`, potentially before main finished. Recovery deliberately KEEPS
+ * the evidence for anything it could not settle, so a worker can read it instead of being told.
+ *
+ * Only unambiguous evidence counts. A well-formed journal is NOT evidence — every healthy deploy has one
+ * in flight — so this reports a journal that cannot be read at all (corrupt, unknown version, or naming
+ * something other than its own deployment), which no in-flight deploy ever produces.
+ */
+export declare function unsettleableComponentsFromDisk(componentsRootDirPath: string): Promise<Map<string, Error>>;
 /**
- * Install an application to its relative `application.dirPath` using either a
- * configured `application.install` command, a derived package manager from the
- * application's `package.json#devEngines`, or falling back to the default
- * package manager, `npm`.
+ * Settle activations a crash interrupted, before anything loads. Runs at startup on main and on every
+ * worker — a worker can be respawned mid-activation, long after main's pass.
  *
- * Will return early if `node_modules` already exists within the `application.dirPath`
+ * Returns failures keyed by COMPONENT so the caller can fail exactly those closed and still load every
+ * healthy sibling — a single unreadable journal must not take down the whole node, and must not let a
+ * component load over state nobody reconciled.
  *
- * This method may be called from any Harper thread as part of a serialized preparation.
  */
-export declare function installApplication(application: Application): Promise<void>;
+export declare function recoverInterruptedActivations(componentsRootDirPath: string): Promise<Map<string, Error>>;
+/**
+ * Finish one owner's catalogued dormant builds after the scan. The catalog was read without the lock, so a
+ * deploy may have published a journal into one of these directories since — and if it then died mid-swap,
+ * only settlement brings the component back. So: settle any journal that appeared, then bound what is still
+ * dormant. The lock is taken only when there is something to do; a lock a live deploy holds is the same
+ * deferral the residue branch records.
+ */
+export declare function reconcileDormantBuilds(componentsRootDirPath: string, owner: string, builds: DormantBuild[], maxCount: number): Promise<Map<string, Error>>;
+export declare function markCandidateComplete(componentDirPath: string, deploymentId: string, componentName: string): Promise<void>;
+/**
+ * Make a built and validated candidate live, as one compensating transaction over two effects: the live tree
+ * moves aside, then the candidate takes its place. Root config is NOT one of them — for an immediate deploy
+ * it is still published before the build, unchanged, and making it transactional is tracked separately
+ * (#2315). A delayed activation hands its artifact's recorded entry in as `afterJournal`, which publishes it
+ * from inside the window a crash rolls forward from — see that call site.
+ *
+ * The candidate must ALREADY be certified: `markCandidateComplete` is the caller's, so a delayed activation
+ * does not re-walk and re-fsync a whole dependency tree it certified when it was built. The activation
+ * journal is still written and fsynced BEFORE the first rename, so a crash anywhere below is recoverable —
+ * see `settleInterruptedActivation` for the state matrix. The second rename is the COMMIT POINT: nothing
+ * after it may compensate, because the live path holds the candidate and renaming the aside back over it
+ * cannot succeed.
+ */
+export declare function activateCandidateApplication(application: Application, deploymentId: string, options?: {
+    afterJournal?: () => Promise<(() => Promise<void>) | void>;
+}): Promise<void>;
+/**
+ * Build a deploy candidate at `.deploy-staging/<deploymentId>/<component>`, leaving the live tree
+ * completely untouched — this is what lets the previous version keep serving through the clone, the
+ * extraction and the dependency install.
+ *
+ * Failure needs no compensation, which is the whole point: nothing about the live component was modified,
+ * so the abandoned candidate is simply removed and the error propagates.
+ */
+export declare function buildCandidateApplication(application: Application, deploymentId: string, options?: {
+    rejectLinkSource?: boolean;
+}): Promise<string>;
+export declare function recoverInterruptedComponentExtractions(componentsRootDirPath: string): Promise<Map<string, Error>>;
+export declare function recoverInterruptedComponentExtraction(componentsRootDirPath: string, componentName: string, waitForPreparation?: boolean, waitTimeoutMs?: number): Promise<void>;
+export declare function retireComponentExtractionStaging(componentDirPath: string, componentName?: string, componentLogger?: Logger): Promise<void>;
+export declare function dropComponentDirectory(componentDirPath: string, componentName?: string, componentLogger?: Logger): Promise<void>;
+/**
+ * The one definition of how Harper invokes a package manager to install dependencies; every npm
+ * entry point composes its arguments here rather than assembling its own.
+ */
+export declare function packageManagerInstallArguments(packageManagerName: string, allowInstallScripts: boolean, force?: boolean): string[];
+/**
+ * Install a component's dependencies into `buildDirPath` — the live path, or a candidate under
+ * `.deploy-staging`. Explicit rather than repointing `application.dirPath`, which is read after preparation
+ * too and would name a vanished directory if any failure path skipped the restore.
+ *
+ * Uses a configured `application.install` command, a package manager derived from the application's
+ * `package.json#devEngines`, or the default, `npm`. Returns early when `node_modules` already exists or
+ * when the manifest has no automatic install work. An explicitly selected non-npm manager is always
+ * allowed to inspect its own workspace configuration, even when the root manifest has no production
+ * dependencies.
+ *
+ * May be called from any Harper thread as part of a serialized preparation.
+ */
+export declare function installApplication(application: Application, buildDirPath?: string): Promise<void>;
 /**
  * Callback invoked once per complete line of install stdout/stderr from
  * `nonInteractiveSpawn`. Threaded through `installApplication` to the underlying spawn
@@ -119,6 +288,7 @@ export declare class Application {
     name: string;
     payload?: Buffer | string | Readable;
     packageIdentifier?: string;
+    readonly packLocalDirectory: boolean;
     install?: {
         command?: string;
         timeout?: number;
@@ -141,12 +311,8 @@ export declare class Application {
     cleanupGitCredentialSession(): Promise<void>;
     cleanupTransientNpmrc(): Promise<void>;
 }
-/**
- * Based on an old implementation for a method called `getPkgPrefix()` that was used
- * during the installation process in order to actually resolve what the user specifies for a
- * component matching some of npm's package resolution rules.
- */
 export declare function derivePackageIdentifier(packageIdentifier: string): string;
+export declare function shouldPackLocalDirectory(packageIdentifier: string | undefined, platform?: NodeJS.Platform): boolean;
 /**
  * Extract and install the specified application.
  *
@@ -163,7 +329,48 @@ export declare function derivePackageIdentifier(packageIdentifier: string): stri
  * @param application The application to prepare.
  * @returns A promise that resolves when all preparation steps complete.
  */
-export declare function prepareApplication(application: Application): Promise<void>;
+export type PrepareApplicationOptions = {
+    beforePrepare?: () => Promise<void>;
+    /**
+     * Runs against the built candidate while the live version is still serving, and BEFORE the swap. A
+     * throw here means the candidate never goes live — which is the whole difference from the previous
+     * behavior, where the swap committed first and a load failure was reported over an already-live
+     * broken release.
+     */
+    validateCandidate?: (candidateDirPath: string) => Promise<void>;
+    /**
+     * Names `.deploy-staging/<artifactId>`, and is not the deploy-lifecycle token: that token de-duplicates
+     * overlapping deploys of one component and is released by the first matching end, so two activations of
+     * one artifact sharing it would resume watchers while the second is still swapping. Defaults to the
+     * lifecycle token, which is unique per invocation.
+     */
+    artifactId?: string;
+    /**
+     * `deploy` builds, certifies and activates. `stage` builds and certifies, then stops, leaving an
+     * artifact a later `activate` can address by `artifactId`. `activate` verifies an existing artifact
+     * and swaps it in, doing no resolution, no install and no network work at all.
+     */
+    mode?: 'deploy' | 'stage' | 'activate';
+    /**
+     * `stage` only: the build's declared intent, recorded with the artifact for whoever activates it.
+     * A callback rather than a value because `beforePrepare` is what determines it, and that runs after
+     * these options have been constructed.
+     */
+    describeArtifact?: () => {
+        rootConfig: Record<string, unknown> | null;
+        isolated: boolean;
+    };
+    /**
+     * `activate` only: publish the artifact's recorded root-config entry, immediately before the swap. May
+     * return an undo, run if the activation then fails before it commits — otherwise a failed activation
+     * leaves config naming a release that is not live, which the next boot install would resolve and build
+     * from scratch over a component whose certified artifact is sitting beside it.
+     */
+    publishRootConfig?: (entry: Record<string, unknown>) => Promise<(() => Promise<void>) | void>;
+    /** `activate` only: admit the artifact's isolation intent under the preparation lock, before the swap. */
+    admitIsolation?: (descriptor: ArtifactDescriptor) => Promise<void>;
+};
+export declare function prepareApplication(application: Application, options?: PrepareApplicationOptions): Promise<void>;
 /**
  * Install all applications specified in the root config.
  *
@@ -228,11 +435,22 @@ export declare function materializeGitSSH(): Promise<{
 } | undefined>;
 export declare function buildNpmrcContent(registryCredentials: ResolvedRegistryCredential[]): string;
 /**
- * Run a command with the deploy's SSH key material materialized only for the duration of the
- * spawn. The keys are decrypted to a transient 0700 dir (see `materializeGitSSH`) and removed as
- * soon as the process settles — on success, failure, and timeout alike.
+ * Execute a command (using `spawn`) with stdin ignored, with the deploy's SSH key material
+ * materialized only for the duration of the spawn. The keys are decrypted to a transient 0700 dir
+ * (see `materializeGitSSH`) and removed as soon as the process settles — on success, failure, and
+ * timeout alike.
+ *
+ * Stdout is logged chunk-by-chunk. Stderr is buffered and then logged line-by-line.
+ *
+ * Rejects with an error if the command fails or times out.
+ *
+ * @param command The command to run.
+ * @param args The arguments to pass to the command.
+ * @param cwd The working directory for the command.
+ * @param timeoutMs The timeout for the command in milliseconds. Defaults to DEFAULT_COMMAND_TIMEOUT_MS.
+ * @returns A promise that resolves when the command completes.
  */
-export declare function nonInteractiveSpawn(applicationName: string, command: string, args: string[], cwd: string, timeoutMs?: number, onLine?: (stream: 'stdout' | 'stderr', line: string) => void, npmUserconfigPath?: string, gitCredentialEnv?: Record<string, string>): Promise<{
+export declare function nonInteractiveSpawn(applicationName: string, command: string, args: string[], cwd: string, timeoutMs?: number, onLine?: (stream: 'stdout' | 'stderr', line: string) => void, npmUserconfigPath?: string, gitCredentialEnv?: Record<string, string>, ignoreNpmScripts?: boolean): Promise<{
     stdout: string;
     stderr: string;
     code: number;