Local telemetry archives for Maple's embedded store (depends on #129)

.github/workflows/ci.yml

@@ -46,14 +46,98 @@ jobs:
 
             # shellcheck is preinstalled on the ubuntu-latest runner image.
             - name: shellcheck
-              run: shellcheck scripts/install.sh scripts/uninstall.sh scripts/build-local-binary.sh
+              run: >-
+                  shellcheck scripts/install.sh scripts/uninstall.sh scripts/build-local-binary.sh
+                  apps/cli/test/native-checkpoint-smoke.sh
+                  apps/cli/test/native-archive-smoke.sh
+                  apps/cli/test/native-archive-crash-recovery-probe.sh
 
             # Syntax-check the POSIX installers against the actual /bin/sh they claim.
             - name: sh -n
               run: |
                   sh -n scripts/install.sh
                   sh -n scripts/uninstall.sh
 
+    local-checkpoint-native:
+        name: Local checkpoint native
+        runs-on: ubuntu-latest
+        timeout-minutes: 20
+        steps:
+            - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+            - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4
+
+            - run: bun install --frozen-lockfile
+
+            - name: Build native local bundle
+              run: scripts/build-local-binary.sh
+
+            - name: Run repeated checkpoint restore and fresh-process reopen smoke
+              env:
+                  KEEP_ROOT: "1"
+                  TMPDIR: ${{ runner.temp }}/maple-native-checkpoint
+              run: |
+                  mkdir -p "$TMPDIR"
+                  apps/cli/test/native-checkpoint-smoke.sh "$GITHUB_WORKSPACE/dist"
+
+            - name: Upload checkpoint failure evidence
+              if: ${{ failure() }}
+              uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4
+              with:
+                  name: native-checkpoint-failure-${{ github.run_id }}
+                  path: ${{ runner.temp }}/maple-native-checkpoint
+                  if-no-files-found: ignore
+
+    local-archive-native:
+        name: Local archive native
+        runs-on: ubuntu-latest
+        timeout-minutes: 45
+        steps:
+            - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+            - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4
+
+            - run: bun install --frozen-lockfile
+
+            - name: Install pinned DuckDB CLI
+              run: |
+                  curl -fsSL https://github.com/duckdb/duckdb/releases/download/v1.5.3/duckdb_cli-linux-amd64.gz \
+                    -o "$RUNNER_TEMP/duckdb.gz"
+                  echo "f05f3b448a9a1bc6e7ac27ff14dfe67bf5761b153c2002723365a456618ef35b  $RUNNER_TEMP/duckdb.gz" \
+                    | sha256sum --check --strict
+                  gunzip "$RUNNER_TEMP/duckdb.gz"
+                  chmod +x "$RUNNER_TEMP/duckdb"
+                  echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
+
+            - name: Build native local bundle
+              run: scripts/build-local-binary.sh
+
+            - name: Run archive lifecycle smoke
+              env:
+                  KEEP_ROOT: "1"
+                  TMPDIR: ${{ runner.temp }}/maple-native-archive
+              run: |
+                  mkdir -p "$TMPDIR"
+                  apps/cli/test/native-archive-smoke.sh "$GITHUB_WORKSPACE/dist"
+
+            - name: Run archive crash-recovery boundaries
+              env:
+                  KEEP_ROOT: "1"
+                  TMPDIR: ${{ runner.temp }}/maple-native-archive-recovery
+              run: |
+                  mkdir -p "$TMPDIR"
+                  apps/cli/test/native-archive-crash-recovery-probe.sh "$GITHUB_WORKSPACE/dist"
+
+            - name: Upload archive failure evidence
+              if: ${{ failure() }}
+              uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4
+              with:
+                  name: native-archive-failure-${{ github.run_id }}
+                  path: |
+                      ${{ runner.temp }}/maple-native-archive
+                      ${{ runner.temp }}/maple-native-archive-recovery
+                  if-no-files-found: ignore
+
     service-map-perf:
         name: Service Map Perf
         runs-on: ubuntu-latest

.gitignore

@@ -53,3 +53,5 @@ playwright/.cache/
 
 # local-only Drizzle Studio config pointing at miniflare D1
 drizzle.config.local.ts
+.18bd7*.bun-build
+.[0-9a-f]*.bun-build

apps/cli/package.json

@@ -7,7 +7,7 @@
 	"type": "module",
 	"scripts": {
 		"start": "bun run src/bin.ts",
-		"test": "vitest run",
+		"test": "bun test test/*.test.ts",
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {

apps/cli/src/bin.ts

@@ -9,6 +9,8 @@ import { Mode } from "./core/mode"
 import { TelemetryLayer } from "./core/telemetry"
 import { maybeNotifyUpdate } from "./core/update"
 import { WarehouseExecutorFromMode } from "./core/warehouse"
+import { archiveErrorMessage } from "./server/archives/errors"
+import { CHECKPOINT_REOPEN_PROBE_ENV, validateCheckpointDataDir } from "./server/checkpoints"
 import { MAPLE_VERSION } from "./version"
 
 // WarehouseExecutorFromMode needs Mode (which needs MapleConfig). provideMerge
@@ -31,10 +33,33 @@ const MainLayer = WarehouseExecutorFromMode.pipe(
 // exporter flushes when its layer scope closes, and only the outermost provide's
 // scope is the runtime's main scope that `BunRuntime.runMain` closes on exit.
 // Merging it into MainLayer leaves spans unflushed for short-lived commands.
-maybeNotifyUpdate.pipe(
-	Effect.flatMap(() => Command.run(cli, { version: MAPLE_VERSION })),
-	Effect.withSpan("maple", { attributes: { "cli.argv": process.argv.slice(2).join(" ") } }),
-	Effect.provide(MainLayer),
-	Effect.provide(TelemetryLayer),
-	BunRuntime.runMain,
-)
+const checkpointProbeDataDir = process.env[CHECKPOINT_REOPEN_PROBE_ENV]
+
+if (checkpointProbeDataDir !== undefined) {
+	// Private re-exec path used by checkpoint restore. It intentionally bypasses
+	// CLI dispatch, update checks, telemetry, and schema bootstrap: success means
+	// this new process loaded the persisted restored representation and queried
+	// its core tables before closing chDB cleanly.
+	try {
+		process.stdout.write(`${JSON.stringify(validateCheckpointDataDir(checkpointProbeDataDir))}\n`)
+	} catch (error) {
+		process.stderr.write(
+			`checkpoint reopen probe failed: ${error instanceof Error ? error.message : String(error)}\n`,
+		)
+		process.exitCode = 1
+	}
+} else {
+	maybeNotifyUpdate.pipe(
+		Effect.flatMap(() => Command.run(cli, { version: MAPLE_VERSION })),
+		Effect.withSpan("maple", { attributes: { "cli.argv": process.argv.slice(2).join(" ") } }),
+		Effect.catchTag("@maple/cli/ArchiveError", (error) =>
+			Effect.sync(() => {
+				process.stderr.write(archiveErrorMessage(error))
+				process.exitCode = 1
+			}),
+		),
+		Effect.provide(MainLayer),
+		Effect.provide(TelemetryLayer),
+		BunRuntime.runMain,
+	)
+}

apps/cli/src/cli.ts

@@ -9,7 +9,8 @@ import { metrics, query } from "./commands/data"
 import { timeseries, breakdown, compare } from "./commands/analytics"
 import { login, logout, whoami } from "./commands/auth"
 import { use } from "./commands/config"
-import { start, stop, reset } from "./commands/server"
+import { start, stop, reset, checkpoint, restore } from "./commands/server"
+import { archive } from "./commands/archive"
 import { update } from "./commands/update"
 
 // One CLI, two backends. Every query command bottoms out at the shared
@@ -46,6 +47,10 @@ export const cli = Command.make("maple").pipe(
 		start,
 		stop,
 		reset,
+		checkpoint,
+		restore,
+		// Parquet archives (local mode)
+		archive,
 		// Self-update
 		update,
 		// Services