@secondlayer/shared 8.0.0 → 10.0.0

package/dist/src/runtime/index.d.ts

@@ -155,13 +155,11 @@ declare function reportRuntimeStatus(input: {
 	coverage?: CoverageState | string
 }): RuntimeStatusReport;
 declare function actionFor(plane: StatusPlane, state: string): string;
-/**
-* Backup bundle — consistent DB, pinned config, encrypted keys, handler
-* manifests, and scope. Restore onto a wiped host must deep-verify green.
-*/
+declare const BACKUP_MANIFEST_VERSION = 1;
 declare const BACKUP_PARTS: readonly ["db", "config", "keys", "handlers", "scope"];
 type BackupPart = (typeof BACKUP_PARTS)[number];
 type BackupManifest = {
+	schema_version: number
 	created_at: string
 	network: string
 	parts: BackupPart[]
@@ -170,34 +168,141 @@ type BackupManifest = {
 		from_height: number
 		to_height: number | null
 	}
+	db: {
+		file: string
+		sha256: string
+		bytes: number
+		format: string
+	} | null
+	/** Never the secrets themselves — only how to check them. */
+	secrets: {
+		file: string
+		encrypted: boolean
+		canary: string
+	} | null
+	signature?: string
+	key_id?: string
 };
 type BackupPlan = {
-	ok: boolean
+	ok: true
 	manifest: BackupManifest
+} | {
+	ok: false
 	reason: string
 };
+/**
+* Validate a backup before any bytes are written. Refusing early is the whole
+* point: a bundle that omits the keys looks like a backup and is not one.
+*/
 declare function planBackup(input: {
 	network: string
-	encryptedKeys: boolean
 	fromHeight: number
 	toHeight?: number | null
+	includeSecrets: boolean
+	secretsEncrypted: boolean
+	canary?: string
 	now?: string
 }): BackupPlan;
-type RestoreResult = {
+/**
+* Seal the canary under an EXPLICIT key.
+*
+* Deliberately not reusing `crypto/secrets.ts`: that module resolves the key
+* from the ambient environment and, in OSS mode, generates and persists one as
+* a side effect when it is missing. Calling it here would mean a backup could
+* mint the very key it is supposed to be preserving.
+*/
+declare function sealKeyCanary(secretsKeyHex: string): string;
+/** True only when `secretsKeyHex` is the key the canary was sealed with. */
+declare function keyMatchesCanary(canaryBase64: string, secretsKeyHex: string): boolean;
+/**
+* Encrypt the secrets bundle under an operator passphrase.
+* Layout: `salt(16) || iv(12) || authTag(16) || ciphertext`.
+*/
+declare function encryptBundle(plaintext: string, passphrase: string): Buffer;
+declare function decryptBundle(envelope: Buffer, passphrase: string): string;
+type RestorePrecheck = {
 	ok: true
-	applied: boolean
-	deep_green: boolean
 } | {
 	ok: false
 	reason: string
+	fatal: boolean
 };
-declare function restoreBackup(plan: BackupPlan, opts?: {
-	apply?: boolean
-	deepVerify?: boolean
-}): RestoreResult;
+/**
+* Everything that must hold before a restore writes anything.
+*
+* `fatal` distinguishes "this bundle can never restore here" from "this needs
+* an explicit override" — the caller surfaces them differently.
+*/
+declare function precheckRestore(input: {
+	manifest: BackupManifest
+	targetNetwork: string
+	targetIsEmpty: boolean
+	force: boolean
+	secretsKeyHex?: string
+}): RestorePrecheck;
+/**
+* Uninstall with data preservation — tear the stack down without destroying
+* what cannot be rebuilt.
+*
+* The asymmetry that shapes this whole file: the index can be reconstructed
+* from the archive, and the chainstate can be re-synced, but the keys cannot be
+* recovered by any means. `SECONDLAYER_SECRETS_KEY` decrypts columns that are
+* otherwise permanently unreadable, and `STREAMS_SIGNING_PRIVATE_KEY` is the
+* identity anything this instance published was signed under.
+*
+* So the default removes containers and leaves every byte of data in place, and
+* the destructive path refuses unless the operator has said the words AND the
+* keys are demonstrably somewhere else. A teardown that silently takes the keys
+* with it is not an uninstall, it is data loss with a friendly name.
+*/
+declare const REMOVABLE: readonly ["containers", "networks", "handler-cache"];
+type Removable = (typeof REMOVABLE)[number];
+declare const PRESERVED: readonly ["index", "chainstate", "secrets", "backups"];
+type Preserved = (typeof PRESERVED)[number];
+type UninstallPlan = {
+	/** What the plan will actually delete. */
+	removes: Removable[]
+	/** What survives, and why it matters. */
+	preserves: {
+		what: Preserved
+		detail: string
+	}[]
+	/** Volumes destroyed only on the purge path. */
+	destroys: string[]
+	purge: boolean
+};
+type UninstallDecision = {
+	ok: true
+	plan: UninstallPlan
+	warnings: string[]
+} | {
+	ok: false
+	reason: string
+};
+declare function planUninstall(input: {
+	purge: boolean
+	/** The operator typed the confirmation. */
+	confirmed: boolean
+	/** A backup bundle exists that carries the keys. */
+	keysBackedUp: boolean
+	/** Secrets are currently present (there is something to lose). */
+	secretsPresent: boolean
+	dataDir: string
+}): UninstallDecision;
+/** The compose invocation a plan corresponds to. */
+declare function uninstallCommand(plan: UninstallPlan, composeFile: string): string[];
 /**
 * Upgrade contract — pin image, preflight schema/disk, backup first,
 * migrate, health/verify, document rollback limits.
+*
+* PLANNER ONLY — `applyUpgrade` returns `{applied:true}` without pulling an
+* image, running a preflight, or migrating anything. Nothing in the product
+* calls it. The upgrade operators actually perform is `docker compose pull &&
+* up -d`, with migrations applied at boot by the runtime entrypoint.
+*
+* Same caution as the sibling backup planner: this step list was published as
+* an operator procedure in the self-host docs until 2026-08-15. Make it do the
+* work before presenting it as one.
 */
 declare const UPGRADE_STEPS: readonly ["pin", "preflight", "backup", "migrate", "health", "verify"];
 type UpgradeStep = (typeof UPGRADE_STEPS)[number];
@@ -227,6 +332,13 @@ declare function applyUpgrade(plan: UpgradePlan, opts?: {
 /**
 * Resource guardrails — preflight RAM/disk/Postgres and estimate growth.
 * Constrained fixtures fail early.
+*
+* The disk numbers here were wrong by 3-6x until 2026-08-15: they promised a
+* full-history mainnet index would fit in 80 GB, and estimated growth at 1 GB
+* per 100k blocks. The reference index measured 504 GB at height 8,771,873.
+* An operator who sized a box from these figures would have filled the disk
+* partway through their first bootstrap, so every constant below now cites what
+* it was measured against.
 */
 type ResourceSnapshot = {
 	ramMb: number
@@ -234,23 +346,81 @@ type ResourceSnapshot = {
 	postgresMaxConnections: number
 	postgresSharedBuffersMb?: number
 };
+type DiskEstimates = {
+	/** blocks + transactions + events, no decoded plane. */
+	diskGbPer100kBlocks: number
+	/** Same, plus a broad decoder set writing `decoded_events`. */
+	diskGbPer100kBlocksDecoded: number
+};
 type GuardrailResult = {
 	ok: true
-	estimates: {
-		diskGbPer100kBlocks: number
-	}
+	estimates: DiskEstimates
 } | {
 	ok: false
 	errors: string[]
 };
+type GuardrailNetwork = "mainnet" | "testnet" | "devnet";
 declare const FLOORS: {
 	readonly appRamMb: 4096
 	readonly fullRamMb: 98304
+	/**
+	* Mainnet full history: 504 GB measured today, growing ~0.5 GB/day at the
+	* observed block rate. 600 leaves roughly six months of headroom, which is
+	* the point of a floor — a box that fits exactly today fails within weeks.
+	*/
+	readonly mainnetAppDiskGb: 600
+	/**
+	* Testnet/devnet carry a fraction of mainnet's history. Unmeasured; retained
+	* as the long-standing default rather than replaced with a fresh guess.
+	*/
 	readonly appDiskGb: 80
+	/**
+	* Bundled node on mainnet. The Stacks chainstate alone measured 1.3 TB on
+	* the reference node (2026-08-15), and the index adds ~500 GB; bitcoind is
+	* additional and not measured here. The previous 1.5 TB floor was below the
+	* two components we HAVE measured.
+	*/
+	readonly mainnetFullDiskGb: 2500
+	/** Bundled node, non-mainnet. Unmeasured; retained default. */
 	readonly fullDiskGb: 1500
 	readonly postgresMaxConnections: 50
 };
-declare function preflightResources(snap: ResourceSnapshot, mode: "external" | "stacks" | "full"): GuardrailResult;
+/** The disk floor that applies to a given mode and network. */
+declare function diskFloorGb(mode: "external" | "stacks" | "full", network: GuardrailNetwork): number;
+/**
+* A dimension the caller could not measure is absent, not zero. Skipping it
+* keeps an unreadable `statfs` from presenting as a 0 GB disk and refusing a
+* perfectly adequate box.
+*/
+declare function preflightResources(snap: Partial<ResourceSnapshot>, mode: "external" | "stacks" | "full", network?: GuardrailNetwork): GuardrailResult;
+type MeasuredResources = {
+	snapshot: Partial<ResourceSnapshot>
+	/** Dimensions we could not read, with why. Never guessed at. */
+	unknown: string[]
+};
+declare function measureResources(input: {
+	dataDir: string
+	query?: (sql: string) => Promise<Array<Record<string, unknown>>>
+}): Promise<MeasuredResources>;
+declare const UNDERSIZED_OVERRIDE = "SECONDLAYER_ALLOW_UNDERSIZED";
+type PreflightDecision = {
+	action: "pass" | "warn" | "refuse"
+	messages: string[]
+};
+declare function decidePreflight(input: {
+	measured: MeasuredResources
+	mode: "external" | "stacks" | "full"
+	network: GuardrailNetwork
+	env?: Record<string, string | undefined>
+}): PreflightDecision;
+/** Measure this box and decide. Returns the decision; the caller exits. */
+declare function runPreflight(input: {
+	dataDir: string
+	mode: "external" | "stacks" | "full"
+	network: GuardrailNetwork
+	query?: (sql: string) => Promise<Array<Record<string, unknown>>>
+	env?: Record<string, string | undefined>
+}): Promise<PreflightDecision>;
 declare const MODULE_COMMANDS: Record<ModuleId, readonly string[]>;
 declare function commandFor(id: ModuleId): readonly string[];
-export { restoreBackup, reportRuntimeStatus, preflightResources, planUpgrade, planBackup, parseRuntimeConfig, migrateEmbedded, isolateHandler, isModuleId, emptyHealth, createSupervisor, createMemoryModule, createMemoryMigrationRunner, commandFor, applyUpgrade, actionFor, UpgradeStep, UpgradePlan, UPGRADE_STEPS, SupervisorHealth, Supervisor, StatusPlane, STATUS_PLANES, SECRET_KEYS, RuntimeStatusReport, RuntimeNetwork, RuntimeModule, RuntimeConfig, RestoreResult, ResourceSnapshot, RequiredConfigKey, REQUIRED_KEYS, PlaneStatus, PUBLISHER_PROFILE, OPTIONAL_KEYS, NodeMode, NODE_MODES, NETWORKS, ModuleState, ModuleId, ModuleHealth, MigrationRunner, MODULE_STATES, MODULE_IDS, MODULE_COMMANDS, MIGRATION_LOCK_KEY, IsolationResult, IsolationOomError, IsolationNetworkError, IsolationLimits, IsolationKillError, IsolationFault, ISOLATION_FAULTS, GuardrailResult, FLOORS, EmbeddedMigration, DEFAULT_PROFILE, ConfigResult, BackupPlan, BackupPart, BackupManifest, BACKUP_PARTS };
+export { uninstallCommand, sealKeyCanary, runPreflight, reportRuntimeStatus, preflightResources, precheckRestore, planUpgrade, planUninstall, planBackup, parseRuntimeConfig, migrateEmbedded, measureResources, keyMatchesCanary, isolateHandler, isModuleId, encryptBundle, emptyHealth, diskFloorGb, decryptBundle, decidePreflight, createSupervisor, createMemoryModule, createMemoryMigrationRunner, commandFor, applyUpgrade, actionFor, UpgradeStep, UpgradePlan, UninstallPlan, UninstallDecision, UPGRADE_STEPS, UNDERSIZED_OVERRIDE, SupervisorHealth, Supervisor, StatusPlane, STATUS_PLANES, SECRET_KEYS, RuntimeStatusReport, RuntimeNetwork, RuntimeModule, RuntimeConfig, RestorePrecheck, ResourceSnapshot, RequiredConfigKey, Removable, REQUIRED_KEYS, REMOVABLE, Preserved, PreflightDecision, PlaneStatus, PUBLISHER_PROFILE, PRESERVED, OPTIONAL_KEYS, NodeMode, NODE_MODES, NETWORKS, ModuleState, ModuleId, ModuleHealth, MigrationRunner, MeasuredResources, MODULE_STATES, MODULE_IDS, MODULE_COMMANDS, MIGRATION_LOCK_KEY, IsolationResult, IsolationOomError, IsolationNetworkError, IsolationLimits, IsolationKillError, IsolationFault, ISOLATION_FAULTS, GuardrailResult, GuardrailNetwork, FLOORS, EmbeddedMigration, DiskEstimates, DEFAULT_PROFILE, ConfigResult, BackupPlan, BackupPart, BackupManifest, BACKUP_PARTS, BACKUP_MANIFEST_VERSION };