@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.2

package/dist/components/Application.d.ts

@@ -30,6 +30,8 @@ interface ApplicationConfig {
      * 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 {
@@ -54,6 +56,7 @@ 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.
@@ -113,12 +116,56 @@ 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.
@@ -156,18 +203,32 @@ export declare function unsettleableComponentsFromDisk(componentsRootDirPath: st
  *
  */
 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 — it is still published
- * before the build, unchanged, and making it transactional is tracked separately (#2315).
+ * 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 `complete` marker and the activation journal are 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.
+ * 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): Promise<void>;
+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
@@ -176,7 +237,9 @@ export declare function activateCandidateApplication(application: Application, d
  * 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): Promise<string>;
+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>;
@@ -267,6 +330,7 @@ export declare function shouldPackLocalDirectory(packageIdentifier: string | und
  * @returns A promise that resolves when all preparation steps complete.
  */
 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
@@ -274,6 +338,37 @@ export type PrepareApplicationOptions = {
      * 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>;
 /**
@@ -355,7 +450,7 @@ export declare function buildNpmrcContent(registryCredentials: ResolvedRegistryC
  * @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;