target-supabase-sdk 0.2.12 → 0.2.13

package/src/shared/log/spool/config.ts

@@ -0,0 +1,56 @@
+import { envInt, envMs } from "../../../node/env/env-parsers";
+import type { LogSpoolConfig } from "./interface";
+
+export const LOG_SPOOL_SERVICE_ID_ENV = "LOG_SPOOL_SERVICE_ID";
+
+export const DEFAULT_LOG_SPOOL_CONFIG: LogSpoolConfig = {
+    writer: {
+        maxEntries: 2000,
+        maxBytes: 2 * 1024 * 1024,
+        flushDebounceMs: 3_000,
+        maxAgeMs: 60_000,
+        postTimeoutMs: 30_000,
+    },
+    gc: {
+        intervalMs: 24 * 60 * 60 * 1000,
+        syncedRetentionMs: 7 * 24 * 60 * 60 * 1000,
+        tmpRetentionMs: 7 * 24 * 60 * 60 * 1000,
+    },
+    collectIntervalMs: 60_000,
+};
+
+export function resolveLogSpoolConfig(partial?: Partial<LogSpoolConfig>): LogSpoolConfig {
+    const defaults = DEFAULT_LOG_SPOOL_CONFIG;
+    return {
+        writer: { ...defaults.writer, ...partial?.writer },
+        gc: { ...defaults.gc, ...partial?.gc },
+        collectIntervalMs: partial?.collectIntervalMs ?? defaults.collectIntervalMs,
+    };
+}
+
+export function logSpoolConfigFromEnv(env: NodeJS.ProcessEnv = process.env): LogSpoolConfig {
+    return resolveLogSpoolConfig({
+        writer: {
+            maxEntries: envInt("LOG_SPOOL_MAX_ENTRIES", DEFAULT_LOG_SPOOL_CONFIG.writer.maxEntries, { env, min: 1 }),
+            maxBytes: envInt("LOG_SPOOL_MAX_BYTES", DEFAULT_LOG_SPOOL_CONFIG.writer.maxBytes, { env, min: 1 }),
+            flushDebounceMs: envMs("LOG_SPOOL_FLUSH_DEBOUNCE_MS", DEFAULT_LOG_SPOOL_CONFIG.writer.flushDebounceMs, {
+                env,
+            }),
+            maxAgeMs: envMs("LOG_SPOOL_MAX_AGE_MS", DEFAULT_LOG_SPOOL_CONFIG.writer.maxAgeMs, { env }),
+            postTimeoutMs: envMs("LOG_PERSIST_POST_TIMEOUT_MS", DEFAULT_LOG_SPOOL_CONFIG.writer.postTimeoutMs, { env }),
+        },
+        gc: {
+            intervalMs: envMs("LOG_SPOOL_GC_INTERVAL_MS", DEFAULT_LOG_SPOOL_CONFIG.gc.intervalMs, { env }),
+            syncedRetentionMs: envMs("LOG_SPOOL_SYNCED_RETENTION_MS", DEFAULT_LOG_SPOOL_CONFIG.gc.syncedRetentionMs, {
+                env,
+            }),
+            tmpRetentionMs: envMs("LOG_SPOOL_TMP_RETENTION_MS", DEFAULT_LOG_SPOOL_CONFIG.gc.tmpRetentionMs, { env }),
+        },
+        collectIntervalMs: envMs("LOG_SPOOL_COLLECT_INTERVAL_MS", DEFAULT_LOG_SPOOL_CONFIG.collectIntervalMs, { env }),
+    });
+}
+
+export function logSpoolServiceIdFromEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
+    const raw = env[LOG_SPOOL_SERVICE_ID_ENV]?.trim();
+    return raw != null && raw !== "" ? raw : undefined;
+}

package/src/shared/log/spool/coordinator.ts

@@ -0,0 +1,55 @@
+import { ensureLogSpoolFromEnv, getLogSpoolStats, logSpoolEnabledFromEnv, shutdownLogSpoolFromEnv } from "./enable";
+import type { LogSpoolWriterStats } from "./interface";
+
+export interface LogSpoolCoordinatorOptions {
+    /** Logical service value (e.g. `watch-service`). */
+    serviceValue: string;
+    /** Instance id after registry claim — passed to child spawn env. */
+    serviceId: string;
+}
+
+/** Service-bound facade for file log spool writer lifecycle. */
+export interface LogSpoolCoordinator {
+    isEnabled(): boolean;
+    getServiceId(): string;
+    /** Enable spool writer in this process. */
+    registerProcess(process?: string): Promise<boolean>;
+    getWriterStats(): LogSpoolWriterStats | null;
+    shutdownLogSpool(): Promise<void>;
+}
+
+export function createLogSpoolCoordinator(options: LogSpoolCoordinatorOptions): LogSpoolCoordinator {
+    const { serviceValue, serviceId } = options;
+
+    return {
+        isEnabled() {
+            return logSpoolEnabledFromEnv();
+        },
+
+        getServiceId() {
+            return serviceId;
+        },
+
+        registerProcess(process?: string) {
+            return ensureLogSpoolFromEnv({
+                serviceValue,
+                serviceId,
+                processRole: process,
+            });
+        },
+
+        getWriterStats() {
+            if (!logSpoolEnabledFromEnv()) {
+                return null;
+            }
+            return getLogSpoolStats();
+        },
+
+        async shutdownLogSpool() {
+            if (!logSpoolEnabledFromEnv()) {
+                return;
+            }
+            await shutdownLogSpoolFromEnv();
+        },
+    };
+}

package/src/shared/log/spool/enable.ts

@@ -0,0 +1,136 @@
+import { createLogger } from "../core/create-logger";
+import { logPersistProcessFromEnv, logPersistServiceFromEnv, logSpoolEnabledFromEnv } from "../upload/env";
+import { registerLogPersistOffer } from "../upload/hook";
+import { LOG_PERSIST_TOPIC } from "../upload/logger";
+import { LOG_SPOOL_SERVICE_ID_ENV, logSpoolConfigFromEnv, logSpoolServiceIdFromEnv } from "./config";
+import type { EnsureLogSpoolFromEnvOptions, LogSpoolProcessRole } from "./interface";
+import { resolveLogSpoolRoot } from "./paths";
+import {
+    assertValidLogSpoolExtraProcessRole,
+    isKnownLogSpoolProcessRole,
+    LOG_SPOOL_EXTRA_PROCESS_ROLES_ENV,
+} from "./process-roles";
+import { enableLogSpoolWriter, getLogSpoolWriterStats, shutdownLogSpoolWriter } from "./writer";
+
+export { logSpoolEnabledFromEnv };
+
+export function resolveLogSpoolProcessRole(explicit?: string): LogSpoolProcessRole {
+    const raw = explicit ?? logPersistProcessFromEnv();
+    if (raw == null || raw === "") {
+        throw new Error("[LogSpool] LOG_PERSIST_PROCESS is required when LOG_PERSIST_ENABLED=true");
+    }
+    if (!isKnownLogSpoolProcessRole(raw)) {
+        throw new Error(
+            `[LogSpool] invalid LOG_PERSIST_PROCESS: ${raw} (not a core role and not listed in ${LOG_SPOOL_EXTRA_PROCESS_ROLES_ENV})`,
+        );
+    }
+    return raw;
+}
+
+/**
+ * Env vars for child spawn after main claims registry slot.
+ * Optional when using {@link ManagedChildProcesses.spawn} — auto-injected from parent env.
+ */
+export function buildLogSpoolSpawnEnv(input: {
+    serviceId: string;
+    processRole: LogSpoolProcessRole;
+}): Record<string, string> {
+    return {
+        [LOG_SPOOL_SERVICE_ID_ENV]: input.serviceId,
+        LOG_PERSIST_PROCESS: input.processRole,
+    };
+}
+
+/**
+ * When persistence is enabled and parent has `LOG_SPOOL_SERVICE_ID`, map spawn `label`
+ * to spool env when `label` is a known core or extra process role.
+ */
+export function resolveLogSpoolSpawnEnvForLabel(
+    label: string,
+    env: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+    if (!logSpoolEnabledFromEnv(env)) {
+        return {};
+    }
+    const serviceId = env[LOG_SPOOL_SERVICE_ID_ENV]?.trim();
+    if (serviceId == null || serviceId === "") {
+        return {};
+    }
+    if (!isKnownLogSpoolProcessRole(label, env)) {
+        return {};
+    }
+    return buildLogSpoolSpawnEnv({ serviceId, processRole: label });
+}
+
+export async function ensureLogSpoolFromEnv(options: EnsureLogSpoolFromEnvOptions = {}): Promise<boolean> {
+    if (!logSpoolEnabledFromEnv()) {
+        registerLogPersistOffer(null);
+        return false;
+    }
+
+    const serviceId = options.serviceId ?? logSpoolServiceIdFromEnv();
+    const serviceValue = options.serviceValue ?? logPersistServiceFromEnv();
+    const processRole = resolveLogSpoolProcessRole(options.processRole);
+
+    if (serviceId == null || serviceId === "") {
+        throw new Error(
+            "[LogSpool] LOG_SPOOL_SERVICE_ID is required when LOG_PERSIST_ENABLED=true (set after registry claim or pass serviceId)",
+        );
+    }
+    if (serviceValue == null || serviceValue === "") {
+        throw new Error("[LogSpool] LOG_PERSIST_SERVICE is required when LOG_PERSIST_ENABLED=true");
+    }
+
+    const spoolRoot = options.spoolRoot ?? resolveLogSpoolRoot();
+
+    await enableLogSpoolWriter({
+        serviceId,
+        processRole,
+        serviceValue,
+        spoolRoot,
+        config: options.config ?? logSpoolConfigFromEnv(),
+    });
+
+    const lifecycleLogger = createLogger({ module: "log-spool" });
+    lifecycleLogger.info("log spool enabled from env", {
+        topic: LOG_PERSIST_TOPIC,
+        data: { serviceId, processRole, serviceValue, spoolRoot },
+    });
+
+    return true;
+}
+
+export async function shutdownLogSpoolFromEnv(): Promise<void> {
+    await shutdownLogSpoolWriter();
+}
+
+export function getLogSpoolStats(): ReturnType<typeof getLogSpoolWriterStats> {
+    return getLogSpoolWriterStats();
+}
+
+export function validateLogSpoolPreloadEnv(env: NodeJS.ProcessEnv = process.env): void {
+    if (!logSpoolEnabledFromEnv(env)) {
+        return;
+    }
+
+    const missing: string[] = [];
+    if (env.LOG_PERSIST_SERVICE?.trim() == null || env.LOG_PERSIST_SERVICE.trim() === "") {
+        missing.push("LOG_PERSIST_SERVICE");
+    }
+    const runtimeDir = env.LOG_PERSIST_REGISTRY_DIR?.trim() || env.RUNTIME_DATA_DIR?.trim();
+    if (runtimeDir == null || runtimeDir === "") {
+        missing.push("LOG_PERSIST_REGISTRY_DIR or RUNTIME_DATA_DIR");
+    }
+
+    if (missing.length > 0) {
+        throw new Error(`[LogSpool] preload env incomplete: ${missing.join(", ")}`);
+    }
+
+    for (const role of env[LOG_SPOOL_EXTRA_PROCESS_ROLES_ENV]?.split(",") ?? []) {
+        const trimmed = role.trim();
+        if (trimmed === "") {
+            continue;
+        }
+        assertValidLogSpoolExtraProcessRole(trimmed);
+    }
+}

package/src/shared/log/spool/file.ts

@@ -0,0 +1,75 @@
+import type { LogEntry } from "../core/log-manager";
+import { computeLogBatchIdempotencyKey } from "../upload/batch-id";
+import type { LogSpoolProcessRole } from "./interface";
+
+/** `role.timestamp.hash.tmp|json` — role is lowercase alphanumeric + hyphen. */
+const BATCH_FILE_PATTERN = /^([a-z][a-z0-9-]*)\.(\d{14})\.([a-f0-9]{8})\.(tmp|json)$/;
+
+export function formatLogSpoolBatchTimestamp(ms: number): string {
+    const d = new Date(ms);
+    const pad = (n: number) => String(n).padStart(2, "0");
+    return (
+        `${d.getFullYear()}` +
+        `${pad(d.getMonth() + 1)}` +
+        `${pad(d.getDate())}` +
+        `${pad(d.getHours())}` +
+        `${pad(d.getMinutes())}` +
+        `${pad(d.getSeconds())}`
+    );
+}
+
+export function computeLogSpoolShortHash(input: {
+    serviceValue: string;
+    serviceId: string;
+    processRole: LogSpoolProcessRole;
+    entries: LogEntry[];
+}): string {
+    const processKey = `${input.serviceId}:${input.processRole}`;
+    const idempotencyKey = computeLogBatchIdempotencyKey({
+        service: input.serviceValue,
+        process: processKey,
+        lane: "slow",
+        entries: input.entries,
+    });
+    return idempotencyKey.slice(0, 8);
+}
+
+export function buildLogSpoolBatchBaseName(input: {
+    processRole: LogSpoolProcessRole;
+    firstEntryTimestamp: number;
+    shortHash: string;
+}): string {
+    const ts = formatLogSpoolBatchTimestamp(input.firstEntryTimestamp);
+    return `${input.processRole}.${ts}.${input.shortHash}`;
+}
+
+export function parseLogSpoolBatchFilename(filename: string): {
+    processRole: LogSpoolProcessRole;
+    timestampMs: number;
+    shortHash: string;
+    extension: "tmp" | "json";
+} | null {
+    const match = BATCH_FILE_PATTERN.exec(filename);
+    if (match == null) {
+        return null;
+    }
+
+    const processRole = match[1] as LogSpoolProcessRole;
+    const tsRaw = match[2];
+    const shortHash = match[3];
+    const extension = match[4] as "tmp" | "json";
+
+    const year = Number(tsRaw.slice(0, 4));
+    const month = Number(tsRaw.slice(4, 6));
+    const day = Number(tsRaw.slice(6, 8));
+    const hour = Number(tsRaw.slice(8, 10));
+    const minute = Number(tsRaw.slice(10, 12));
+    const second = Number(tsRaw.slice(12, 14));
+    const timestampMs = Date.UTC(year, month - 1, day, hour, minute, second);
+
+    if (!Number.isFinite(timestampMs)) {
+        return null;
+    }
+
+    return { processRole, timestampMs, shortHash, extension };
+}

package/src/shared/log/spool/interface.ts

@@ -0,0 +1,62 @@
+import type { LogEntry } from "../core/log-manager";
+import type { LogSpoolCoreProcessRole, LogSpoolProcessRole } from "./process-roles";
+
+/** On-disk batch before guard upload — producer writes `.tmp`, guard renames to `.json` after post. */
+export interface LogSpoolBatchFile {
+    entries: LogEntry[];
+    meta?: Record<string, unknown>;
+}
+
+export interface LogSpoolWriterConfig {
+    maxEntries: number;
+    maxBytes: number;
+    flushDebounceMs: number;
+    /** Flush buffered entries after this age even when below count/byte thresholds. */
+    maxAgeMs: number;
+    postTimeoutMs: number;
+}
+
+export interface LogSpoolGcConfig {
+    /** How often guard runs tmp/json GC (upload collect still runs every collect tick). */
+    intervalMs: number;
+    syncedRetentionMs: number;
+    tmpRetentionMs: number;
+}
+
+export interface LogSpoolConfig {
+    writer: LogSpoolWriterConfig;
+    gc: LogSpoolGcConfig;
+    collectIntervalMs: number;
+}
+
+export interface EnableLogSpoolOptions {
+    /** Service instance id (`Service.id` from registry claim). */
+    serviceId: string;
+    /** Spool directory name — core or {@link LOG_SPOOL_EXTRA_PROCESS_ROLES_ENV} extra. */
+    processRole: LogSpoolProcessRole;
+    /** Logical service value for List meta (`LOG_PERSIST_SERVICE`, e.g. `watch-service`). */
+    serviceValue: string;
+    spoolRoot?: string;
+    config?: Partial<LogSpoolConfig>;
+}
+
+export interface EnsureLogSpoolFromEnvOptions {
+    serviceId?: string;
+    processRole?: LogSpoolProcessRole;
+    serviceValue?: string;
+    spoolRoot?: string;
+    config?: Partial<LogSpoolConfig>;
+}
+
+export interface LogSpoolWriterStats {
+    enabled: boolean;
+    bufferedEntries: number;
+    bufferedBytes: number;
+    flushInProgress: boolean;
+    debouncePending: boolean;
+    ageFlushPending: boolean;
+    serviceId: string | null;
+    processRole: LogSpoolProcessRole | null;
+}
+
+export type { LogSpoolCoreProcessRole, LogSpoolProcessRole };

package/src/shared/log/spool/paths.ts

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+import { runtimeDataDirFromEnv } from "../upload/env";
+import type { LogSpoolProcessRole } from "./interface";
+
+export const LOG_SPOOL_DIR_NAME = "log-spool";
+
+export function resolveLogSpoolRoot(explicit?: string): string {
+    if (explicit != null && explicit.trim() !== "") {
+        return explicit;
+    }
+    const configured = process.env.LOG_SPOOL_DIR?.trim();
+    if (configured != null && configured !== "") {
+        return configured;
+    }
+    const runtimeDir = runtimeDataDirFromEnv();
+    if (runtimeDir == null) {
+        throw new Error(
+            "[LogSpool] spool root required: set LOG_SPOOL_DIR or LOG_PERSIST_REGISTRY_DIR / RUNTIME_DATA_DIR",
+        );
+    }
+    return join(runtimeDir, LOG_SPOOL_DIR_NAME);
+}
+
+export function logSpoolServiceDir(spoolRoot: string, serviceId: string): string {
+    return join(spoolRoot, serviceId);
+}
+
+export function logSpoolProcessDir(spoolRoot: string, serviceId: string, processRole: LogSpoolProcessRole): string {
+    return join(spoolRoot, serviceId, processRole);
+}

package/src/shared/log/spool/process-roles.ts

@@ -0,0 +1,75 @@
+/** Four-process L3 blueprint roles — always scanned by collect-log. */
+export const LOG_SPOOL_CORE_PROCESS_ROLES = ["main", "guard", "scheduler", "worker"] as const;
+
+export type LogSpoolCoreProcessRole = (typeof LOG_SPOOL_CORE_PROCESS_ROLES)[number];
+
+/** Spool directory / `LOG_PERSIST_PROCESS` name — core or service-specific extra. */
+export type LogSpoolProcessRole = LogSpoolCoreProcessRole | string;
+
+export const LOG_SPOOL_EXTRA_PROCESS_ROLES_ENV = "LOG_SPOOL_EXTRA_PROCESS_ROLES";
+
+const EXTRA_ROLE_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+function parseRoleList(raw: string | undefined): string[] {
+    if (raw == null || raw.trim() === "") {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part !== "");
+}
+
+/** Parse comma-separated extra roles from env (e.g. `chrome-sidecar`). */
+export function logSpoolExtraProcessRolesFromEnv(env: NodeJS.ProcessEnv = process.env): string[] {
+    return parseRoleList(env[LOG_SPOOL_EXTRA_PROCESS_ROLES_ENV]);
+}
+
+/** Core + extras, deduped, stable order (core first). */
+export function resolveAllLogSpoolProcessRoles(env: NodeJS.ProcessEnv = process.env): LogSpoolProcessRole[] {
+    const extras = logSpoolExtraProcessRolesFromEnv(env);
+    const seen = new Set<string>(LOG_SPOOL_CORE_PROCESS_ROLES);
+    const all: LogSpoolProcessRole[] = [...LOG_SPOOL_CORE_PROCESS_ROLES];
+    for (const role of extras) {
+        if (!seen.has(role)) {
+            seen.add(role);
+            all.push(role);
+        }
+    }
+    return all;
+}
+
+export function isLogSpoolCoreProcessRole(value: string): value is LogSpoolCoreProcessRole {
+    return (LOG_SPOOL_CORE_PROCESS_ROLES as readonly string[]).includes(value);
+}
+
+/** Whether `value` is a known spool role (core or configured extra). */
+export function isKnownLogSpoolProcessRole(value: string, env: NodeJS.ProcessEnv = process.env): boolean {
+    if (isLogSpoolCoreProcessRole(value)) {
+        return true;
+    }
+    return logSpoolExtraProcessRolesFromEnv(env).includes(value);
+}
+
+/** Validate extra role token — lowercase alphanumeric + hyphen, not a duplicate core name. */
+export function assertValidLogSpoolExtraProcessRole(role: string): void {
+    if (role === "" || !EXTRA_ROLE_PATTERN.test(role)) {
+        throw new Error(
+            `[LogSpool] invalid extra process role "${role}" — use lowercase letters, digits, hyphen (e.g. chrome-sidecar)`,
+        );
+    }
+    if (isLogSpoolCoreProcessRole(role)) {
+        throw new Error(`[LogSpool] extra process role "${role}" duplicates a core role`);
+    }
+}
+
+export function mergeLogSpoolExtraProcessRolesEnv(env: NodeJS.ProcessEnv, extraRoles: readonly string[]): void {
+    if (extraRoles.length === 0) {
+        return;
+    }
+    for (const role of extraRoles) {
+        assertValidLogSpoolExtraProcessRole(role);
+    }
+    const merged = new Set([...logSpoolExtraProcessRolesFromEnv(env), ...extraRoles]);
+    env[LOG_SPOOL_EXTRA_PROCESS_ROLES_ENV] = [...merged].join(",");
+}

package/src/shared/log/spool/register-collect-log-runner.ts

@@ -0,0 +1,63 @@
+import { LOG_TOPIC_TRIGGER } from "../../../trigger/trigger.constant";
+import { TriggerManager } from "../../../trigger/trigger-manager";
+import { logSpoolEnabledFromEnv } from "../upload/env";
+import { spoolLogger } from "../upload/logger";
+import { runCollectLogTick } from "./collector";
+import { logSpoolConfigFromEnv } from "./config";
+
+export const COLLECT_LOG_RUNNER_KEY = "collect-log";
+
+export interface RegisterCollectLogRunnerOptions {
+    serviceValue: string;
+    getServiceId: () => Promise<string | null>;
+    runnerKey?: string;
+    intervalMs?: number;
+    initialDelayMs?: number;
+    spoolRoot?: string;
+}
+
+/**
+ * Guard process only — uploads `.tmp` spool batches and runs GC.
+ * Register before {@link TriggerNode.start} (e.g. in {@link ServiceGuardNode.create}).
+ */
+export function registerCollectLogRunner(options: RegisterCollectLogRunnerOptions): void {
+    if (!logSpoolEnabledFromEnv()) {
+        return;
+    }
+
+    const config = logSpoolConfigFromEnv();
+    const intervalMs = options.intervalMs ?? config.collectIntervalMs;
+
+    TriggerManager.registerRunner({
+        key: options.runnerKey ?? COLLECT_LOG_RUNNER_KEY,
+        intervalMs,
+        initialDelayMs: options.initialDelayMs ?? 0,
+        retryCount: 1,
+        fn: async (ctx) => {
+            const serviceId = await options.getServiceId();
+            if (serviceId == null) {
+                ctx.logger.warn("collect-log skipped — serviceId unavailable", { topic: LOG_TOPIC_TRIGGER });
+                return;
+            }
+
+            const result = await runCollectLogTick({
+                serviceId,
+                serviceValue: options.serviceValue,
+                spoolRoot: options.spoolRoot,
+                config,
+            });
+
+            if (result.uploaded > 0 || result.failed > 0) {
+                ctx.logger.info("collect-log runner finished", {
+                    topic: LOG_TOPIC_TRIGGER,
+                    data: result,
+                });
+            }
+        },
+    });
+
+    spoolLogger.info("collect-log runner registered", {
+        intervalMs,
+        serviceValue: options.serviceValue,
+    });
+}

package/src/shared/log/spool/service-lifecycle.ts

@@ -0,0 +1,35 @@
+import { logSpoolEnabledFromEnv } from "../upload/env";
+import { ensureLogSpoolFromEnv, getLogSpoolStats, shutdownLogSpoolFromEnv } from "./enable";
+import type { LogSpoolWriterStats } from "./interface";
+
+/** Whether file log spool is enabled (`LOG_PERSIST_ENABLED=true`). */
+export function isLogSpoolEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+    return logSpoolEnabledFromEnv(env);
+}
+
+/**
+ * Guard / scheduler / worker (and extra roles) — enable writer from spawn env.
+ * Main is enabled by `createServiceHost` after registry claim.
+ */
+export async function enableLogSpoolFromEnvInChild(): Promise<void> {
+    if (!logSpoolEnabledFromEnv()) {
+        return;
+    }
+    await ensureLogSpoolFromEnv();
+}
+
+/** Writer buffer stats when spool enabled; `null` when disabled. Typical use: main observability. */
+export function getMainLogSpoolWriterStats(): LogSpoolWriterStats | null {
+    if (!logSpoolEnabledFromEnv()) {
+        return null;
+    }
+    return getLogSpoolStats();
+}
+
+/** Flush memory buffer and disable writer when spool enabled; no-op otherwise. */
+export async function shutdownLogSpool(): Promise<void> {
+    if (!logSpoolEnabledFromEnv()) {
+        return;
+    }
+    await shutdownLogSpoolFromEnv();
+}