@secondlayer/shared 7.11.2 → 9.0.0

package/dist/src/mode.d.ts

@@ -10,14 +10,28 @@
 *   2026-05-14 shared-rip this also serves subgraphs + subscriptions.
 */
 type InstanceMode = "oss" | "platform";
+/** What the operator wrote in the env — `archive` is the honest name for the
+*  metered public-archive deployment and aliases `platform` behaviorally. */
+type DeclaredInstanceMode = InstanceMode | "archive";
 /**
 * Resolve the active instance mode from `process.env.INSTANCE_MODE`.
 * Defaults to `"oss"` — the safest default for self-hosters who deploy
-* without setting the variable.
+* without setting the variable. `archive` normalizes to `platform` here so
+* every behavioral branch stays a two-way choice; use
+* `getDeclaredInstanceMode()` for display surfaces.
 */
 declare function getInstanceMode(): InstanceMode;
+/** The mode as declared in the env, for status/identity surfaces. */
+declare function getDeclaredInstanceMode(): DeclaredInstanceMode;
+/**
+* True when public reads are credit-metered (the free window, retention, and
+* credits gates arm). Platform/archive deployments meter by default;
+* self-host never does unless the operator explicitly sets
+* `METERED_READS=true`. `METERED_READS=false` disarms a metered deployment.
+*/
+declare function isMeteredReads(): boolean;
 /** True when the active mode is `"platform"` (shared multi-tenant). */
 declare function isPlatformMode(): boolean;
 /** True when the active mode is `"oss"` (self-hosted). */
 declare function isOssMode(): boolean;
-export { isPlatformMode, isOssMode, getInstanceMode, InstanceMode };
+export { isPlatformMode, isOssMode, isMeteredReads, getInstanceMode, getDeclaredInstanceMode, InstanceMode, DeclaredInstanceMode };

package/dist/src/mode.js

@@ -15,14 +15,33 @@ var __export = (target, all) => {
 };
 
 // src/mode.ts
-var VALID_MODES = ["oss", "platform"];
-function getInstanceMode() {
+var VALID_MODES = [
+  "oss",
+  "platform",
+  "archive"
+];
+function declaredMode() {
   const raw = process.env.INSTANCE_MODE?.trim().toLowerCase();
   if (raw && VALID_MODES.includes(raw)) {
     return raw;
   }
   return "oss";
 }
+function getInstanceMode() {
+  const declared = declaredMode();
+  return declared === "archive" ? "platform" : declared;
+}
+function getDeclaredInstanceMode() {
+  return declaredMode();
+}
+function isMeteredReads() {
+  const override = process.env.METERED_READS?.trim().toLowerCase();
+  if (override === "true")
+    return true;
+  if (override === "false")
+    return false;
+  return getInstanceMode() === "platform";
+}
 function isPlatformMode() {
   return getInstanceMode() === "platform";
 }
@@ -32,8 +51,10 @@ function isOssMode() {
 export {
   isPlatformMode,
   isOssMode,
-  getInstanceMode
+  isMeteredReads,
+  getInstanceMode,
+  getDeclaredInstanceMode
 };
 
-//# debugId=B04DA9673CE8B2EF64756E2164756E21
+//# debugId=F90A93497EE7AEC664756E2164756E21
 //# sourceMappingURL=mode.js.map

package/dist/src/mode.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/mode.ts"],
   "sourcesContent": [
-    "/**\n * Instance modes for the Secondlayer platform.\n *\n * - `oss`: self-hosted, single-tenant. No auth middleware, no platform routes\n *   (projects, admin). Everything runs against a single `DATABASE_URL`.\n *   Intended for `docker compose up`.\n *\n * - `platform`: control-plane mode. Magic-link auth, API keys, projects,\n *   admin. Serves the dashboard + CLI against a single shared DB. Post\n *   2026-05-14 shared-rip this also serves subgraphs + subscriptions.\n */\n\nexport type InstanceMode = \"oss\" | \"platform\";\n\nconst VALID_MODES: readonly InstanceMode[] = [\"oss\", \"platform\"];\n\n/**\n * Resolve the active instance mode from `process.env.INSTANCE_MODE`.\n * Defaults to `\"oss\"` — the safest default for self-hosters who deploy\n * without setting the variable.\n */\nexport function getInstanceMode(): InstanceMode {\n\tconst raw = process.env.INSTANCE_MODE?.trim().toLowerCase();\n\tif (raw && (VALID_MODES as readonly string[]).includes(raw)) {\n\t\treturn raw as InstanceMode;\n\t}\n\treturn \"oss\";\n}\n\n/** True when the active mode is `\"platform\"` (shared multi-tenant). */\nexport function isPlatformMode(): boolean {\n\treturn getInstanceMode() === \"platform\";\n}\n\n/** True when the active mode is `\"oss\"` (self-hosted). */\nexport function isOssMode(): boolean {\n\treturn getInstanceMode() === \"oss\";\n}\n"
+    "/**\n * Instance modes for the Secondlayer platform.\n *\n * - `oss`: self-hosted, single-tenant. No auth middleware, no platform routes\n *   (projects, admin). Everything runs against a single `DATABASE_URL`.\n *   Intended for `docker compose up`.\n *\n * - `platform`: control-plane mode. Magic-link auth, API keys, projects,\n *   admin. Serves the dashboard + CLI against a single shared DB. Post\n *   2026-05-14 shared-rip this also serves subgraphs + subscriptions.\n */\n\nexport type InstanceMode = \"oss\" | \"platform\";\n\n/** What the operator wrote in the env — `archive` is the honest name for the\n *  metered public-archive deployment and aliases `platform` behaviorally. */\nexport type DeclaredInstanceMode = InstanceMode | \"archive\";\n\nconst VALID_MODES: readonly DeclaredInstanceMode[] = [\n\t\"oss\",\n\t\"platform\",\n\t\"archive\",\n];\n\nfunction declaredMode(): DeclaredInstanceMode {\n\tconst raw = process.env.INSTANCE_MODE?.trim().toLowerCase();\n\tif (raw && (VALID_MODES as readonly string[]).includes(raw)) {\n\t\treturn raw as DeclaredInstanceMode;\n\t}\n\treturn \"oss\";\n}\n\n/**\n * Resolve the active instance mode from `process.env.INSTANCE_MODE`.\n * Defaults to `\"oss\"` — the safest default for self-hosters who deploy\n * without setting the variable. `archive` normalizes to `platform` here so\n * every behavioral branch stays a two-way choice; use\n * `getDeclaredInstanceMode()` for display surfaces.\n */\nexport function getInstanceMode(): InstanceMode {\n\tconst declared = declaredMode();\n\treturn declared === \"archive\" ? \"platform\" : declared;\n}\n\n/** The mode as declared in the env, for status/identity surfaces. */\nexport function getDeclaredInstanceMode(): DeclaredInstanceMode {\n\treturn declaredMode();\n}\n\n/**\n * True when public reads are credit-metered (the free window, retention, and\n * credits gates arm). Platform/archive deployments meter by default;\n * self-host never does unless the operator explicitly sets\n * `METERED_READS=true`. `METERED_READS=false` disarms a metered deployment.\n */\nexport function isMeteredReads(): boolean {\n\tconst override = process.env.METERED_READS?.trim().toLowerCase();\n\tif (override === \"true\") return true;\n\tif (override === \"false\") return false;\n\treturn getInstanceMode() === \"platform\";\n}\n\n/** True when the active mode is `\"platform\"` (shared multi-tenant). */\nexport function isPlatformMode(): boolean {\n\treturn getInstanceMode() === \"platform\";\n}\n\n/** True when the active mode is `\"oss\"` (self-hosted). */\nexport function isOssMode(): boolean {\n\treturn getInstanceMode() === \"oss\";\n}\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;AAcA,IAAM,cAAuC,CAAC,OAAO,UAAU;AAOxD,SAAS,eAAe,GAAiB;AAAA,EAC/C,MAAM,MAAM,QAAQ,IAAI,eAAe,KAAK,EAAE,YAAY;AAAA,EAC1D,IAAI,OAAQ,YAAkC,SAAS,GAAG,GAAG;AAAA,IAC5D,OAAO;AAAA,EACR;AAAA,EACA,OAAO;AAAA;AAID,SAAS,cAAc,GAAY;AAAA,EACzC,OAAO,gBAAgB,MAAM;AAAA;AAIvB,SAAS,SAAS,GAAY;AAAA,EACpC,OAAO,gBAAgB,MAAM;AAAA;",
-  "debugId": "B04DA9673CE8B2EF64756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;AAkBA,IAAM,cAA+C;AAAA,EACpD;AAAA,EACA;AAAA,EACA;AACD;AAEA,SAAS,YAAY,GAAyB;AAAA,EAC7C,MAAM,MAAM,QAAQ,IAAI,eAAe,KAAK,EAAE,YAAY;AAAA,EAC1D,IAAI,OAAQ,YAAkC,SAAS,GAAG,GAAG;AAAA,IAC5D,OAAO;AAAA,EACR;AAAA,EACA,OAAO;AAAA;AAUD,SAAS,eAAe,GAAiB;AAAA,EAC/C,MAAM,WAAW,aAAa;AAAA,EAC9B,OAAO,aAAa,YAAY,aAAa;AAAA;AAIvC,SAAS,uBAAuB,GAAyB;AAAA,EAC/D,OAAO,aAAa;AAAA;AASd,SAAS,cAAc,GAAY;AAAA,EACzC,MAAM,WAAW,QAAQ,IAAI,eAAe,KAAK,EAAE,YAAY;AAAA,EAC/D,IAAI,aAAa;AAAA,IAAQ,OAAO;AAAA,EAChC,IAAI,aAAa;AAAA,IAAS,OAAO;AAAA,EACjC,OAAO,gBAAgB,MAAM;AAAA;AAIvB,SAAS,cAAc,GAAY;AAAA,EACzC,OAAO,gBAAgB,MAAM;AAAA;AAIvB,SAAS,SAAS,GAAY;AAAA,EACpC,OAAO,gBAAgB,MAAM;AAAA;",
+  "debugId": "F90A93497EE7AEC664756E2164756E21",
   "names": []
 }

package/dist/src/node/local-client.d.ts

@@ -18,6 +18,7 @@ declare const FAILURE_CLASSES: readonly ["omission", "version", "digest_mismatch
 type FailureClass = (typeof FAILURE_CLASSES)[number];
 declare const RETRY_STATES: readonly ["open", "retrying", "halted", "resolved"];
 type RetryState = (typeof RETRY_STATES)[number];
+type BootstrapSource = "archive" | "genesis" | "import";
 interface BlocksTable {
 	height: number;
 	hash: string;
@@ -223,11 +224,9 @@ interface AccountsTable {
 	ghost: Generated<boolean>;
 	/** Stacks principal owning a wallet-ghost account (x402-paid deploys). */
 	wallet_principal: string | null;
-	plan: Generated<string>;
 	display_name: string | null;
 	bio: string | null;
 	avatar_url: string | null;
-	slug: string | null;
 	stripe_customer_id: string | null;
 	/** Opt-out toggle for the subgraph reindex-completion email. Defaults true. */
 	notify_reindex_complete: Generated<boolean>;
@@ -244,19 +243,6 @@ interface SessionsTable {
 	last_used_at: Date | null;
 	created_at: Generated<Date>;
 }
-/**
-* One-time claim tokens for ghost accounts. The raw token only ever appears in
-* the claim URL returned at mint time; we store its sha256. A used token marks
-* the account as claimed (or merged into an existing account).
-*/
-interface ClaimTokensTable {
-	id: Generated<string>;
-	account_id: string;
-	token_hash: string;
-	created_at: Generated<Date>;
-	expires_at: Date;
-	used_at: Date | null;
-}
 interface MagicLinksTable {
 	id: Generated<string>;
 	email: string;
@@ -267,47 +253,6 @@ interface MagicLinksTable {
 	failed_attempts: Generated<number>;
 	created_at: Generated<Date>;
 }
-interface UsageDailyTable {
-	account_id: string;
-	tenant_id: string | null;
-	date: string;
-	api_requests: Generated<number>;
-	deliveries: Generated<number>;
-	streams_events_returned: Generated<number>;
-	index_decoded_events_returned: Generated<number>;
-}
-interface UsageSnapshotsTable {
-	id: Generated<string>;
-	account_id: string;
-	measured_at: Generated<Date>;
-	storage_bytes: Generated<number>;
-}
-interface AccountInsightsTable {
-	id: Generated<string>;
-	account_id: string;
-	category: string;
-	insight_type: string;
-	resource_id: string | null;
-	severity: string;
-	title: string;
-	body: string;
-	data: unknown;
-	dismissed_at: Date | null;
-	expires_at: Date | null;
-	created_at: Generated<Date>;
-}
-interface AccountAgentRunsTable {
-	id: Generated<string>;
-	account_id: string;
-	started_at: Generated<Date>;
-	completed_at: Date | null;
-	status: Generated<string>;
-	input_tokens: Generated<number>;
-	output_tokens: Generated<number>;
-	cost_usd: Generated<number>;
-	insights_created: Generated<number>;
-	error: string | null;
-}
 interface SubgraphProcessingStatsTable {
 	id: Generated<string>;
 	subgraph_name: string;
@@ -340,41 +285,6 @@ interface SubgraphHealthSnapshotsTable {
 	last_processed_block: number | null;
 	captured_at: Generated<Date>;
 }
-interface SubgraphUsageDailyTable {
-	subgraph_id: string;
-	date: string;
-	query_count: Generated<number>;
-}
-interface ProjectsTable {
-	id: Generated<string>;
-	name: string;
-	slug: string;
-	account_id: string;
-	settings: Generated<Record<string, unknown>>;
-	network: Generated<string>;
-	node_rpc: string | null;
-	created_at: Generated<Date>;
-	updated_at: Generated<Date>;
-}
-interface TeamMembersTable {
-	id: Generated<string>;
-	project_id: string;
-	account_id: string;
-	role: Generated<string>;
-	invited_by: string | null;
-	created_at: Generated<Date>;
-}
-interface TeamInvitationsTable {
-	id: Generated<string>;
-	project_id: string;
-	email: string;
-	role: Generated<string>;
-	token: string;
-	invited_by: string | null;
-	expires_at: Date;
-	accepted_at: Date | null;
-	created_at: Generated<Date>;
-}
 interface ProcessedStripeEventsTable {
 	event_id: string;
 	event_type: string;
@@ -811,6 +721,20 @@ interface StageFailuresTable {
 	resolved_at: Date | null;
 	retain_until: Generated<Date>;
 }
+/**
+* The instance's declared scope — one row per network. `start_height` is what
+* makes missing history below it deliberate rather than a gap.
+*/
+interface SyncScopesTable {
+	network: string;
+	start_height: number;
+	target_height: number | null;
+	bootstrap_source: BootstrapSource;
+	bootstrap_manifest_digest: string | null;
+	genesis_hash: string | null;
+	created_at: Generated<Date>;
+	updated_at: Generated<Date>;
+}
 interface Database {
 	blocks: BlocksTable;
 	transactions: TransactionsTable;
@@ -827,27 +751,14 @@ interface Database {
 	accounts: AccountsTable;
 	sessions: SessionsTable;
 	magic_links: MagicLinksTable;
-	claim_tokens: ClaimTokensTable;
-	usage_daily: UsageDailyTable;
-	usage_snapshots: UsageSnapshotsTable;
-	account_insights: AccountInsightsTable;
-	account_agent_runs: AccountAgentRunsTable;
 	subgraph_health_snapshots: SubgraphHealthSnapshotsTable;
 	subgraph_processing_stats: SubgraphProcessingStatsTable;
 	subgraph_table_snapshots: SubgraphTableSnapshotsTable;
 	subgraph_gaps: SubgraphGapsTable;
 	subgraph_operations: SubgraphOperationsTable;
-	subgraph_usage_daily: SubgraphUsageDailyTable;
-	projects: ProjectsTable;
-	team_members: TeamMembersTable;
-	team_invitations: TeamInvitationsTable;
 	processed_stripe_events: ProcessedStripeEventsTable;
-	tenants: TenantsTable;
-	tenant_usage_monthly: TenantUsageMonthlyTable;
-	tenant_compute_addons: TenantComputeAddonsTable;
 	account_spend_caps: AccountSpendCapsTable;
 	account_credits: AccountCreditsTable;
-	provisioning_audit_log: ProvisioningAuditLogTable;
 	subscriptions: SubscriptionsTable;
 	subscription_outbox: SubscriptionOutboxTable;
 	subscription_deliveries: SubscriptionDeliveriesTable;
@@ -876,6 +787,7 @@ interface Database {
 	chain_read_cache: ChainReadCacheTable;
 	pending_fork_blocks: PendingForkBlocksTable;
 	observer_journal: ObserverJournalTable;
+	sync_scopes: SyncScopesTable;
 	stage_registry: StageRegistryTable;
 	stage_runs: StageRunsTable;
 	stage_block_receipts: StageBlockReceiptsTable;
@@ -922,57 +834,6 @@ interface X402PaymentsTable {
 	*  reconciler's heal path can never double-credit them. */
 	credited_at: Generated<Date> | null;
 }
-type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
-interface TenantsTable {
-	id: Generated<string>;
-	account_id: string;
-	slug: string;
-	status: ColumnType<TenantStatus, TenantStatus | undefined, TenantStatus>;
-	plan: string;
-	cpus: ColumnType<number, number | string, number | string>;
-	memory_mb: number;
-	storage_limit_mb: number;
-	storage_used_mb: number | null;
-	pg_container_id: string | null;
-	api_container_id: string | null;
-	processor_container_id: string | null;
-	target_database_url_enc: Buffer;
-	tenant_jwt_secret_enc: Buffer;
-	anon_key_enc: Buffer;
-	service_key_enc: Buffer;
-	api_url_internal: string;
-	api_url_public: string;
-	suspended_at: Date | null;
-	last_health_check_at: Date | null;
-	last_active_at: Generated<Date>;
-	service_gen: Generated<number>;
-	anon_gen: Generated<number>;
-	project_id: string | null;
-	created_at: Generated<Date>;
-	updated_at: Generated<Date>;
-}
-interface TenantUsageMonthlyTable {
-	id: Generated<string>;
-	tenant_id: string;
-	period_month: Date;
-	storage_peak_mb: Generated<number>;
-	storage_avg_mb: Generated<number>;
-	storage_last_mb: Generated<number>;
-	measurements: Generated<number>;
-	first_at: Generated<Date>;
-	last_at: Generated<Date>;
-}
-interface TenantComputeAddonsTable {
-	id: Generated<string>;
-	tenant_id: string;
-	memory_mb_delta: Generated<number>;
-	cpu_delta: Generated<number | string>;
-	storage_mb_delta: Generated<number>;
-	effective_from: Generated<Date>;
-	effective_until: Date | null;
-	stripe_subscription_item_id: string | null;
-	created_at: Generated<Date>;
-}
 interface AccountSpendCapsTable {
 	account_id: string;
 	monthly_cap_cents: number | null;
@@ -996,20 +857,6 @@ interface AccountCreditsTable {
 	refill_last_at: Date | null;
 	updated_at: Generated<Date>;
 }
-type ProvisioningAuditEvent = "provision.start" | "provision.success" | "provision.failure" | "suspend" | "resume" | "resize" | "keys.rotate" | "bastion.key.upload" | "bastion.key.revoke" | "teardown";
-type ProvisioningAuditStatus = "ok" | "error";
-interface ProvisioningAuditLogTable {
-	id: Generated<string>;
-	tenant_id: string | null;
-	tenant_slug: string | null;
-	account_id: string | null;
-	actor: string;
-	event: ProvisioningAuditEvent;
-	status: ProvisioningAuditStatus;
-	detail: unknown | null;
-	error: string | null;
-	created_at: Generated<Date>;
-}
 type SubscriptionStatus = "active" | "paused" | "error";
 /** Polymorphic subscription mode: `subgraph` reacts to processed table rows;
 *  `chain` reacts to raw chain events matched directly off the Index/Streams

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,90 @@ 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;
 /**
 * 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 +281,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 +295,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 { sealKeyCanary, runPreflight, reportRuntimeStatus, preflightResources, precheckRestore, planUpgrade, planBackup, parseRuntimeConfig, migrateEmbedded, measureResources, keyMatchesCanary, isolateHandler, isModuleId, encryptBundle, emptyHealth, diskFloorGb, decryptBundle, decidePreflight, createSupervisor, createMemoryModule, createMemoryMigrationRunner, commandFor, applyUpgrade, actionFor, UpgradeStep, UpgradePlan, UPGRADE_STEPS, UNDERSIZED_OVERRIDE, SupervisorHealth, Supervisor, StatusPlane, STATUS_PLANES, SECRET_KEYS, RuntimeStatusReport, RuntimeNetwork, RuntimeModule, RuntimeConfig, RestorePrecheck, ResourceSnapshot, RequiredConfigKey, REQUIRED_KEYS, PreflightDecision, PlaneStatus, PUBLISHER_PROFILE, 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 };