@bendyline/gezel 1.0.6 → 1.1.0

package/dist/native/index.d.ts

@@ -292,7 +292,7 @@ declare function recordLlamaQuarantine(home: string, input: {
  * (`win32-x64`, `darwin-arm64`, `linux-x64`, `linux-arm64`).
  */
 
-type NativeBinaryName = 'llama-server' | 'ds4-server' | 'sd-server' | 'whisper-server' | 'device-health' | 'uv';
+type NativeBinaryName = 'llama-server' | 'ds4-server' | 'sd-server' | 'whisper-server' | 'device-health' | 'uv' | 'duckdb';
 interface DiscoverInput {
     /** GEZEL_HOME — backend cache file lives at `<home>/engines/llama-cpp/`. */
     home: string;
@@ -360,13 +360,6 @@ interface DiscoverResult {
         quarantined?: LlamaBackend[];
     };
 }
-/**
- * Resolve a single bundled binary under `<root>/<subdir>/<file>`. The
- * `subdir` is `<platform>[-<variant>]`; the file is `<name>[.exe]`.
- *
- * Returns `null` when the file isn't on disk. Caller decides whether
- * to fall through to a variant-less subdir or surface "not found."
- */
 declare function resolveNativeBinaryUnder(root: string, name: NativeBinaryName, subdir: string, platform?: NodeJS.Platform, fileExists?: (p: string) => boolean): string | null;
 /**
  * Discover bundled native binaries and stamp the matching env vars on
@@ -418,8 +411,14 @@ declare function windowsDetachedSpawnOptions(platform?: NodeJS.Platform): {
  * discovery) write/read the same cache file at
  * `<home>/engines/llama-cpp/backend.json`. A mismatch between the two
  * would cause cache thrash; keep them in one constant.
+ *
+ * Mirrors the `tag=` line of that file, so it followed upstream from the
+ * rolling `b####` build tags to semver stable releases (`v0.3.0`). Nothing
+ * compares these values for order — the cache is keyed on equality alone,
+ * so a scheme change simply misses once and re-probes, which is the same
+ * thing any bump does.
  */
-declare const LLAMA_ENGINE_VERSION = "b10353";
+declare const LLAMA_ENGINE_VERSION = "v0.3.0";
 
 /**
  * Map a (platform, arch) pair to the subdirectory name used under
@@ -486,6 +485,9 @@ type DeviceGpuProcessOwner = 'machine-engine' | 'app-engine' | 'development-engi
 interface DeviceGpuProcess {
     pid: number;
     name?: string;
+    /** Windows adapter identity parsed from the PDH instance, when available. */
+    adapterLuid?: string;
+    /** Historical wire name; Windows reports resident local bytes in this field. */
     dedicatedBytes: number;
     owner: DeviceGpuProcessOwner;
 }
@@ -493,7 +495,7 @@ interface DeviceHealthSample {
     sampledAt: string;
     sources: string[];
     readings: DeviceHealthReading[];
-    /** Dedicated GPU-memory owners when the platform exposes process counters. */
+    /** GPU-memory process samples when the platform exposes trustworthy counters. */
     processes?: DeviceGpuProcess[];
     errors: string[];
 }
@@ -641,4 +643,112 @@ interface FindGpuPanicOptions {
  */
 declare function findRecentGpuPanics(opts?: FindGpuPanicOptions): GpuPanicRecord[];
 
-export { type CommandResult, DEFAULT_DEVICE_SAFETY_POLICY, type DetectInput, type DetectResult, type DeviceHealthCommandRunner, type DeviceHealthDecision, DeviceHealthGate, type DeviceHealthGateOptions, type DeviceHealthProbe, type DeviceHealthReading, type DeviceHealthSample, type DeviceHealthState, type DeviceHealthStatusSnapshot, type DeviceSafetyMode, type DeviceSafetyPolicyInput, type DeviceTelemetryFailurePolicy, type DeviceVendor, type DiscoverInput, type DiscoverResult, type FindGpuPanicOptions, GPU_PANIC_RE, type GpuPanicRecord, type GpuVendorHint, LLAMA_ENGINE_VERSION, type LlamaBackend, type LlamaQuarantineEntry, type NativeBinaryName, type QuarantineIo, type ResolvedDeviceSafetyPolicy, type ResolvedLlamaBinary, type SystemDeviceHealthProbeOptions, binaryFingerprint, createSystemDeviceHealthProbe, detectLlamaBackend, discoverNativeBinaries, evaluateDeviceHealth, findRecentGpuPanics, isBinaryQuarantined, llamaQuarantinePath, parseAmdSmiJson, parseNvidiaSmiCsv, readLlamaQuarantine, recordLlamaQuarantine, resolveAvailableLlamaBinary, resolveDeviceSafetyPolicy, resolveNativeBinaryUnder, resolvePlatformKey, windowsDetachedSpawnOptions, windowsHeadlessSpawnOptions };
+/**
+ * Pinned DuckDB CLI release, and the one place its identity lives.
+ *
+ * DuckDB is **vendored, not built**. The DuckDB Foundation publishes a
+ * precompiled single-file CLI per platform, already Developer ID signed and
+ * notarized on macOS and Authenticode signed on Windows, so Gezel
+ * redistributes those exact bytes rather than compiling or re-signing them.
+ * That is the same provenance rule the bundled Node runtime follows (see the
+ * `signIgnore` block in `packages/app/electron-builder.yml`): when a vendor
+ * already ships a binary that satisfies the platform's own trust model,
+ * putting our signature on it replaces their attestation with ours and
+ * destroys the "hash-comparable against the vendor's manifest" property.
+ *
+ * Two consumers read this module, which is why it lives in core rather than
+ * in `packages/app`:
+ *
+ *   - `packages/app/scripts/fetch-duckdb.mjs` stages the binary into the
+ *     Electron installer at build time.
+ *   - `packages/service/src/engines/resolver.ts` downloads it at runtime for
+ *     npm / CLI installs that have no Electron payload.
+ *
+ * Both verify against {@link DUCKDB_ARCHIVE_SHA256} (the published archive)
+ * and {@link DUCKDB_BINARY_SHA256} (the executable inside it), and both land
+ * the result in the same versioned directory — see {@link duckdbInstallDir} —
+ * so a machine with both a desktop install and an npm `gezeld` shares one
+ * verified copy.
+ *
+ * ── Why two digests ──────────────────────────────────────────────────────
+ *
+ * The archive digest is what the download path can check before it unpacks
+ * anything, and it is the value comparable against a digest a user computes
+ * from DuckDB's own release page. The binary digest is what the *bundle*
+ * path checks, because the Electron installer ships the extracted executable
+ * with no archive around it. Recording only one would leave one of the two
+ * paths verifying nothing.
+ *
+ * ── Bumping ──────────────────────────────────────────────────────────────
+ *
+ * Run `node scripts/bump-duckdb.mjs <version>`. It downloads every platform
+ * archive, computes both digests, confirms the CLI reports the pinned commit,
+ * and rewrites this file. The PR diff is the audit trail. Never hand-edit a
+ * digest.
+ *
+ * A version bump is a security review, not a chore: `DuckRunner`'s
+ * configuration prelude and `statement-guard`'s use of `json_serialize_sql`
+ * are behavioural contracts measured against a specific engine build. Re-run
+ * the sandbox matrix in `docs/observation-corpora.md` before landing one.
+ *
+ * License: MIT — https://github.com/duckdb/duckdb
+ */
+/** Upstream release tag, without the leading `v`. */
+declare const DUCKDB_VERSION = "1.5.5";
+/**
+ * The commit the tag points at. `duckdb --version` echoes its first ten
+ * characters, which is how the fetch and bump scripts prove they unpacked the
+ * build this file claims rather than whatever the URL happened to serve.
+ */
+declare const DUCKDB_COMMIT = "d8cdaa33fda8df955cc76ef58a280f68f4cd43fa";
+/**
+ * sha256 of DuckDB's `LICENSE` at {@link DUCKDB_COMMIT}. Pinned for the same
+ * reason the binary is: we redistribute the text, so a silent upstream change
+ * to the terms should fail the build rather than ship unnoticed.
+ */
+declare const DUCKDB_LICENSE_SHA256 = "7e17fd31249fa875cb3b1c5e05c6c3e99b75509f6a2804ca176c217834de1dcb";
+/** Platform keys this pin covers — the platforms Gezel ships a daemon for. */
+type DuckdbPlatformKey = 'darwin-arm64' | 'linux-x64' | 'linux-arm64' | 'win32-x64';
+/**
+ * Release asset per platform. The glibc archives are pinned over the `-musl`
+ * variants to match the rest of the native tree.
+ */
+declare const DUCKDB_ASSET: Record<DuckdbPlatformKey, string>;
+/** sha256 of each published archive, as served by duckdb/duckdb's releases. */
+declare const DUCKDB_ARCHIVE_SHA256: Record<DuckdbPlatformKey, string>;
+/** sha256 of the `duckdb[.exe]` executable inside each archive. */
+declare const DUCKDB_BINARY_SHA256: Record<DuckdbPlatformKey, string>;
+/**
+ * The DuckDB Foundation's Apple Developer Team ID. macOS verification asserts
+ * *this* identity rather than Bendyline's — the whole point of vendoring the
+ * signed binary is that the vendor's attestation is the one that travels with
+ * it. Asserting the vendor's team is strictly stronger than the Windows
+ * precedent, which today asserts no publisher at all for vendored binaries.
+ */
+declare const DUCKDB_APPLE_TEAM_ID = "7NCTQWA3HA";
+/** Authenticode subject common name on the Windows build. */
+declare const DUCKDB_WINDOWS_PUBLISHER = "Stichting DuckDB Foundation";
+/** Base URL for the pinned release's assets. */
+declare function duckdbAssetUrl(key: DuckdbPlatformKey, version?: string): string;
+/**
+ * Map `(process.platform, process.arch)` to a pin key, or `null` where DuckDB
+ * publishes no build we ship. Callers treat `null` as "no bundled query
+ * engine on this host" and fall back to a system install.
+ */
+declare function duckdbPlatformKey(platform: NodeJS.Platform, arch: string): DuckdbPlatformKey | null;
+/** Executable name on this platform. */
+declare function duckdbBinaryName(platform?: NodeJS.Platform): string;
+/**
+ * Versioned install directory: `<home>/engines/duckdb/<version>/`.
+ *
+ * Versioned so a pin bump installs alongside the old copy rather than
+ * mutating a binary a running query may be executing, and so the discovery
+ * ladder can ask for exactly the build whose sandbox behaviour we measured.
+ * Shared by the Electron bundle installer and the CLI downloader on purpose:
+ * one machine, one verified copy, whichever install path put it there.
+ */
+declare function duckdbInstallDir(home: string, version?: string): string;
+/** Absolute path to the pinned executable inside {@link duckdbInstallDir}. */
+declare function duckdbInstalledBinary(home: string, platform?: NodeJS.Platform, version?: string): string;
+
+export { type CommandResult, DEFAULT_DEVICE_SAFETY_POLICY, DUCKDB_APPLE_TEAM_ID, DUCKDB_ARCHIVE_SHA256, DUCKDB_ASSET, DUCKDB_BINARY_SHA256, DUCKDB_COMMIT, DUCKDB_LICENSE_SHA256, DUCKDB_VERSION, DUCKDB_WINDOWS_PUBLISHER, type DetectInput, type DetectResult, type DeviceHealthCommandRunner, type DeviceHealthDecision, DeviceHealthGate, type DeviceHealthGateOptions, type DeviceHealthProbe, type DeviceHealthReading, type DeviceHealthSample, type DeviceHealthState, type DeviceHealthStatusSnapshot, type DeviceSafetyMode, type DeviceSafetyPolicyInput, type DeviceTelemetryFailurePolicy, type DeviceVendor, type DiscoverInput, type DiscoverResult, type DuckdbPlatformKey, type FindGpuPanicOptions, GPU_PANIC_RE, type GpuPanicRecord, type GpuVendorHint, LLAMA_ENGINE_VERSION, type LlamaBackend, type LlamaQuarantineEntry, type NativeBinaryName, type QuarantineIo, type ResolvedDeviceSafetyPolicy, type ResolvedLlamaBinary, type SystemDeviceHealthProbeOptions, binaryFingerprint, createSystemDeviceHealthProbe, detectLlamaBackend, discoverNativeBinaries, duckdbAssetUrl, duckdbBinaryName, duckdbInstallDir, duckdbInstalledBinary, duckdbPlatformKey, evaluateDeviceHealth, findRecentGpuPanics, isBinaryQuarantined, llamaQuarantinePath, parseAmdSmiJson, parseNvidiaSmiCsv, readLlamaQuarantine, recordLlamaQuarantine, resolveAvailableLlamaBinary, resolveDeviceSafetyPolicy, resolveNativeBinaryUnder, resolvePlatformKey, windowsDetachedSpawnOptions, windowsHeadlessSpawnOptions };

package/dist/native/index.js

@@ -305,10 +305,55 @@ function isEntry(value) {
 
 // src/native/discover.ts
 import { existsSync } from "fs";
+import { join as join4 } from "path";
+
+// src/native/duckdb-pin.ts
 import { join as join3 } from "path";
+var DUCKDB_VERSION = "1.5.5";
+var DUCKDB_COMMIT = "d8cdaa33fda8df955cc76ef58a280f68f4cd43fa";
+var DUCKDB_LICENSE_SHA256 = "7e17fd31249fa875cb3b1c5e05c6c3e99b75509f6a2804ca176c217834de1dcb";
+var DUCKDB_ASSET = {
+  "darwin-arm64": "duckdb_cli-osx-arm64.zip",
+  "linux-x64": "duckdb_cli-linux-amd64.zip",
+  "linux-arm64": "duckdb_cli-linux-arm64.zip",
+  "win32-x64": "duckdb_cli-windows-amd64.zip"
+};
+var DUCKDB_ARCHIVE_SHA256 = {
+  "darwin-arm64": "da5177b8869c4ed8c65d514fb47a8ed0f6fa7427f103304932d5e83851e46abd",
+  "linux-x64": "08c0ca117111fcede14239d0093792352befdc174218c344d232c13279643d05",
+  "linux-arm64": "02163197027a42149147364d31fa67cac82108517a4be43304a1cc226eaef07a",
+  "win32-x64": "e1428b7114a841626b5054723731cbf45c6df91b42ae1a6c355f88fad1f6dc4c"
+};
+var DUCKDB_BINARY_SHA256 = {
+  "darwin-arm64": "d0610710dd30667aa6c76709299b6822e55dc9199803350aa2e1b06e3346943b",
+  "linux-x64": "3d33b1df037cb049155c393778df7853fafb23e9d49d7c9cacdde4dd67155788",
+  "linux-arm64": "9882c99a9804407de82c0edb1816d7667733d37d771a98eb23ad5f6a8d37acb1",
+  "win32-x64": "fde737c7749075f6b54e14772a4e6b33a5fa0201075d03640aca358074ea4554"
+};
+var DUCKDB_APPLE_TEAM_ID = "7NCTQWA3HA";
+var DUCKDB_WINDOWS_PUBLISHER = "Stichting DuckDB Foundation";
+function duckdbAssetUrl(key, version = DUCKDB_VERSION) {
+  return `https://github.com/duckdb/duckdb/releases/download/v${version}/${DUCKDB_ASSET[key]}`;
+}
+function duckdbPlatformKey(platform, arch) {
+  if (platform === "darwin" && arch === "arm64") return "darwin-arm64";
+  if (platform === "linux" && arch === "x64") return "linux-x64";
+  if (platform === "linux" && arch === "arm64") return "linux-arm64";
+  if (platform === "win32" && arch === "x64") return "win32-x64";
+  return null;
+}
+function duckdbBinaryName(platform = process.platform) {
+  return platform === "win32" ? "duckdb.exe" : "duckdb";
+}
+function duckdbInstallDir(home, version = DUCKDB_VERSION) {
+  return join3(home, "engines", "duckdb", version);
+}
+function duckdbInstalledBinary(home, platform = process.platform, version = DUCKDB_VERSION) {
+  return join3(duckdbInstallDir(home, version), duckdbBinaryName(platform));
+}
 
 // src/native/llama-engine-version.ts
-var LLAMA_ENGINE_VERSION = "b10353";
+var LLAMA_ENGINE_VERSION = "v0.3.0";
 
 // src/native/platform-key.ts
 function resolvePlatformKey(platform = process.platform, arch = process.arch) {
@@ -326,11 +371,12 @@ function resolvePlatformKey(platform = process.platform, arch = process.arch) {
 }
 
 // src/native/discover.ts
+var UNPREFIXED_BINARIES = /* @__PURE__ */ new Set(["uv"]);
 function resolveNativeBinaryUnder(root, name, subdir, platform = process.platform, fileExists = existsSync) {
   const ext = platform === "win32" ? ".exe" : "";
-  const candidates = name === "uv" ? [`uv${ext}`] : [`gezel-${name}${ext}`, `${name}${ext}`];
+  const candidates = UNPREFIXED_BINARIES.has(name) ? [`${name}${ext}`] : [`gezel-${name}${ext}`, `${name}${ext}`];
   for (const file of candidates) {
-    const p = join3(root, subdir, file);
+    const p = join4(root, subdir, file);
     if (fileExists(p)) return p;
   }
   return null;
@@ -351,7 +397,8 @@ function discoverNativeBinaries(input) {
       "sd-server",
       "whisper-server",
       "device-health",
-      "uv"
+      "uv",
+      "duckdb"
     ]) {
       binaries.push({ name, source: "no-platform-key" });
     }
@@ -438,6 +485,18 @@ function discoverNativeBinaries(input) {
       }
     }
   }
+  if (process.env.GEZEL_DUCKDB_BIN) {
+    binaries.push({ name: "duckdb", source: "pre-set", path: process.env.GEZEL_DUCKDB_BIN });
+  } else {
+    const duckBin = duckdbInstalledBinary(input.home, platform);
+    if (fileExists(duckBin)) {
+      process.env.GEZEL_DUCKDB_BIN = duckBin;
+      binaries.push({ name: "duckdb", source: "discovered", path: duckBin });
+      log?.info?.(`[native] duckdb: ${duckBin}`);
+    } else {
+      binaries.push({ name: "duckdb", source: "not-found" });
+    }
+  }
   const subdirFor = (name) => name === "ds4-server" && platform === "linux" ? `${platformKey}-cuda` : platformKey;
   for (const { name, envVar } of [
     { name: "ds4-server", envVar: "GEZEL_DS4_SERVER_BIN" },
@@ -703,6 +762,7 @@ function parseDeviceHealthHelperJson(stdout) {
       processes.push({
         pid,
         ...typeof process2.name === "string" ? { name: process2.name } : {},
+        ...typeof process2.adapterLuid === "string" && process2.adapterLuid.length > 0 ? { adapterLuid: process2.adapterLuid } : {},
         dedicatedBytes,
         owner
       });
@@ -1060,10 +1120,10 @@ var DeviceHealthGate = class {
 // src/native/gpu-panic.ts
 import { readFileSync as readFileSync3, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
 import { homedir } from "os";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 var PANIC_DIRS = [
   "/Library/Logs/DiagnosticReports",
-  join4(homedir(), "Library", "Logs", "DiagnosticReports")
+  join5(homedir(), "Library", "Logs", "DiagnosticReports")
 ];
 var GPU_PANIC_RE = /IOGPUMemory|IOAccelerator|AGXAccelerator|AGXG\d|completeMemory\(\)\s+prepare\s+count\s+underflow|IOGPUFamily/i;
 function findRecentGpuPanics(opts = {}) {
@@ -1079,7 +1139,7 @@ function findRecentGpuPanics(opts = {}) {
       continue;
     }
     for (const name of names) {
-      const path = join4(dir, name);
+      const path = join5(dir, name);
       let mtimeMs;
       try {
         mtimeMs = statSync2(path).mtimeMs;
@@ -1102,6 +1162,14 @@ function findRecentGpuPanics(opts = {}) {
 export {
   DEFAULT_DEVICE_SAFETY_POLICY,
   DEVICE_HARD_TEMPERATURE_C,
+  DUCKDB_APPLE_TEAM_ID,
+  DUCKDB_ARCHIVE_SHA256,
+  DUCKDB_ASSET,
+  DUCKDB_BINARY_SHA256,
+  DUCKDB_COMMIT,
+  DUCKDB_LICENSE_SHA256,
+  DUCKDB_VERSION,
+  DUCKDB_WINDOWS_PUBLISHER,
   DeviceHealthGate,
   GPU_PANIC_RE,
   LLAMA_ENGINE_VERSION,
@@ -1109,6 +1177,11 @@ export {
   createSystemDeviceHealthProbe,
   detectLlamaBackend,
   discoverNativeBinaries,
+  duckdbAssetUrl,
+  duckdbBinaryName,
+  duckdbInstallDir,
+  duckdbInstalledBinary,
+  duckdbPlatformKey,
   evaluateDeviceHealth,
   findRecentGpuPanics,
   isBinaryQuarantined,

package/dist/paths.d.ts

@@ -33,6 +33,12 @@ declare function userProjectDir(root: string, projectId: string): string;
  * continues to resolve the canonical definition from the machine-shared root.
  */
 declare function projectPrivateDir(root: string, projectId: string): string;
+/**
+ * Daemon-owned record of the seed files the applied project type deployed
+ * into the workspace (the "overlay manifest"). Per-machine by design — it
+ * lives in the private sidecar, never in the possibly-synced workspace.
+ */
+declare function projectTypeOverlayFile(root: string, projectId: string): string;
 declare function machineSharedGezelDir(gezelId: string): string | null;
 declare function machineSharedProjectDir(projectId: string): string | null;
 /**
@@ -211,6 +217,8 @@ declare function projectFindingLifecycleFile(root: string, projectId: string): s
 declare function projectBoekwachterIssuesFile(root: string, projectId: string): string;
 /** Durable per-project code-review records for this account. */
 declare function projectCodeReviewsFile(root: string, projectId: string): string;
+/** Durable per-project diffpack records for this account. */
+declare function projectDiffpacksFile(root: string, projectId: string): string;
 /** Durable per-account report-action lifecycle records. */
 declare function projectReportActionsFile(root: string, projectId: string): string;
 /** Per-project documents folder — holds about.md, missionObjectives.md, etc. */
@@ -227,6 +235,73 @@ declare function projectArtifactsDir(root: string, projectId: string, external?:
 declare const PROJECT_SHADOW_DIR_NAME = "shadow";
 /** Per-project `artifacts/shadow/` root. */
 declare function projectShadowDir(root: string, projectId: string, external?: ExternalFolders): string;
+/**
+ * Reserved artifacts subtree holding tables derived from tabular files that
+ * live in the project *workspace* — a CSV too large to read, a spreadsheet a
+ * gezel cannot open at all. Sibling to `shadow/`, and derived the same way:
+ * regenerable from the source file, write-denied to gezels and users, safe to
+ * delete.
+ *
+ * Distinct from a connector corpus under `data/`, because the two have
+ * different lifecycles. A connector corpus is an append-only stream that grows
+ * forever and needs sealing, compaction and retention; a workspace table is a
+ * *snapshot of one file*, rebuilt wholesale when the file's content hash moves
+ * and swept when the file goes.
+ *
+ * Companion directories keep the source's full basename (`sales.xlsx_tables`),
+ * so `X_tables` → source `X` is a lossless reverse map for orphan collection
+ * and `a.csv` cannot collide with `a.xlsx` — the same reasoning as the shadow
+ * tree's `_files` convention.
+ */
+declare const PROJECT_TABULAR_DIR_NAME = "tabular";
+/** Suffix marking one source file's companion directory under `tabular/`. */
+declare const TABULAR_COMPANION_SUFFIX = "_tables";
+/** Per-project `artifacts/tabular/` root. */
+declare function projectTabularDir(root: string, projectId: string, external?: ExternalFolders): string;
+/**
+ * Directory level inside a connector corpus that holds observation tables:
+ * `artifacts/data/<corpus>/tables/<table>/`. Deliberately NOT underscore-
+ * prefixed. Inside a corpus the underscore prefix marks the *mutable* surface
+ * (`_meta.json`, `_actions/`), and `isProtectedConnectorCorpusPath` denies
+ * gezel writes to everything else under `data/`. Keeping `tables` bare
+ * therefore inherits the existing read-only guard rather than needing a
+ * second one.
+ */
+declare const CONNECTOR_TABLES_DIR_NAME = "tables";
+/**
+ * Where a table's materialized rollups live, under its own directory. Kept
+ * separate from the raw partitions because retention deletes raw data and
+ * never deletes rollups.
+ */
+declare const CONNECTOR_ROLLUPS_DIR_NAME = "rollups";
+/** Filename of a table's semantic layer, beside its data. */
+declare const OBSERVATION_TABLE_MANIFEST_FILE = "manifest.json";
+/** Filename of a table's writer/compaction/rollup bookkeeping. */
+declare const OBSERVATION_TABLE_STATE_FILE = "state.json";
+/**
+ * Reserved artifacts subtree holding diffpacks: proposed change sets a gezel
+ * drafted but never applied. Each pack owns `after/` (the copy-on-write draft
+ * tree), `files/` (the sealed single-file unified diffs), `notes.md` and
+ * `manifest.json`. Lives under artifacts — never the workspace, which is the
+ * whole point: the gezel proposes, the user applies.
+ */
+declare const PROJECT_DIFFPACKS_DIR_NAME = "diffpacks";
+/** Per-project `artifacts/diffpacks/` root. */
+declare function projectDiffpacksDir(root: string, projectId: string, external?: ExternalFolders): string;
+/** One pack's folder: `artifacts/diffpacks/<packId>/`. */
+declare function projectDiffpackDir(root: string, projectId: string, packId: string, external?: ExternalFolders): string;
+/**
+ * Reserved artifacts subtree holding the user's chat prompt drafts. Each draft
+ * owns `message.md` (the prompt markdown), `message_files/` (its uploads,
+ * referenced document-relatively while editing) and `draft.json` (thread
+ * association, status, sent stamps). Lives under artifacts so a draft is an
+ * ordinary inspectable file the user can open, back up, and grep.
+ */
+declare const PROJECT_PROMPTS_DIR_NAME = "prompts";
+/** Per-project `artifacts/prompts/` root. */
+declare function projectPromptsDir(root: string, projectId: string, external?: ExternalFolders): string;
+/** One draft's folder: `artifacts/prompts/<draftId>/`. */
+declare function projectPromptDraftDir(root: string, projectId: string, draftId: string, external?: ExternalFolders): string;
 /** Per-project memories folder (daily markdown + summary + vectra index). */
 declare function projectMemoriesDir(root: string, projectId: string, external?: ExternalFolders): string;
 /**
@@ -283,6 +358,13 @@ declare function projectTerminalsDir(root: string, projectId: string): string;
 declare function projectTerminalFile(root: string, projectId: string, threadId: string): string;
 /** JSONL file holding events that aren't scoped to any project. */
 declare function globalHistoryFile(root: string): string;
+/**
+ * Gezel-to-gezel messages that were accepted but not yet dispatched — a
+ * handoff parks while the sender is mid-turn, and that park is a closure in
+ * one process's memory. Written when the park happens, dropped when the
+ * dispatch fires, replayed at boot.
+ */
+declare function pendingHandoffsFile(root: string): string;
 /**
  * Home-scoped index directory for cross-project derived caches (session
  * transcripts, history mirror, documents library). Always local: it's a
@@ -293,6 +375,22 @@ declare function globalIndexDir(root: string): string;
 declare function globalIndexDbFile(root: string): string;
 /** Per-project JSONL holding events scoped to that project. Always local. */
 declare function projectHistoryFile(root: string, projectId: string): string;
+/** Root of the user-private knowledge tier. Owned by the knowledge manager. */
+declare function knowledgeDir(root: string): string;
+/** The authoritative per-user registry of installed/enabled catalogs. */
+declare function knowledgeRegistryFile(root: string): string;
+/** User-private extracted catalog versions live under this tree. */
+declare function knowledgeCatalogsDir(root: string): string;
+/**
+ * One immutable extracted catalog version:
+ * `knowledge/catalogs/<publisherId>/<catalogId>/<version>/<digest16>/`.
+ * The digest segment makes re-publishing the same version string with
+ * different bytes land in a different directory instead of silently
+ * shadowing the installed one.
+ */
+declare function knowledgeCatalogVersionDir(root: string, publisherId: string, catalogId: string, version: string, contentDigest: string): string;
+/** Resumable download staging for catalog archives. */
+declare function knowledgeDownloadsDir(root: string): string;
 /**
  * Single per-project file holding the array of structured Q&A
  * (`Question` records) created by the `ask_user_question` MCP tool.
@@ -378,12 +476,18 @@ declare function craftbookTemplateScriptsDir(root: string, prefix: string, id: s
 declare function craftbookTemplateScriptFile(root: string, prefix: string, id: string, version: string, name: string): string;
 /** First two lowercased chars of a craftbook id — the catalog's shard prefix. */
 declare function craftbookShardPrefix(id: string): string;
+/** Installed AI App packages, kept as versioned catalog slices. */
+declare function aiAppsRoot(root: string): string;
+/** Active-version registry for installed AI Apps. */
+declare function aiAppsRegistryFile(root: string): string;
+declare function aiAppVersionDir(root: string, appId: string, version: string): string;
+declare function aiAppItemsDir(root: string, appId: string, version: string): string;
+declare function aiAppReceiptFile(root: string, appId: string, version: string): string;
 /**
  * Local catalog source for user-installed / imported project types. Mirrors
  * the bundled catalog layout under
- * `~/.gezel/project-types/{prefix}/{id}/versions/{version}/`. A `.gzl`
- * import or a "install from gilde" action copies items here so they browse
- * next to the bundled ones. See docs/project-types.md.
+ * `~/.gezel/project-types/{prefix}/{id}/versions/{version}/`. Manually
+ * authored local items browse next to bundled and mounted `.gezapp` items.
  */
 declare function projectTypesRoot(root: string): string;
 declare function projectTypeDir(root: string, prefix: string, id: string): string;
@@ -634,4 +738,4 @@ declare function binRuntimeRoot(root: string): string;
  */
 declare function readConfigRaw(root: string): Promise<Record<string, unknown>>;
 
-export { type ExternalFolders, type GezelPaths, MACHINE_SHARED_MARKER, type MachineStorageScope, PROJECT_SHADOW_DIR_NAME, activeMachineSharedHome, ambientDashboardLatestFile, ambientDashboardStateFile, ambientDir, ambientDisplayStateFile, backupsDir, binRuntimeRoot, channelsDir, craftbookShardPrefix, craftbookTemplateDir, craftbookTemplateManifestFile, craftbookTemplateScriptFile, craftbookTemplateScriptsDir, craftbookTemplateVersionDir, craftbookTemplateVersionManifestFile, craftbookTemplatesRoot, daemonTransactionsRoot, deviceIdentityFile, enginesRoot, fallbackProjectIndexDir, fallbackProjectVillageFile, foldersStateDir, gezelDir, gezelGrowthPath, gezelHome, gezelLocalDir, gezelMemoriesDir, gezelPaths, gezelPoppetjePath, gezelSessionFile, gezelSessionsDir, gezelStorageScope, gezelToolsPath, gezelToolsetsFile, gezelToolsetsInstallDir, gildeLiveRoot, gildeLiveStateFile, gildeLiveVersionDir, gildeLiveVersionsDir, globalHistoryFile, globalIndexDbFile, globalIndexDir, keurmeesterCasesDir, keurmeesterDigestStatePath, keurmeesterDigestsDir, keurmeesterDir, machineSharedGezelDir, machineSharedHome, machineSharedMarkerFile, machineSharedProjectDir, meesterStatusDir, meesterStatusFile, meesterStatusStateFile, pendingGrantsFile, playwrightBrowsersDir, projectActivityFile, projectArtifactsDir, projectArtifactsIndexDbFile, projectBoekwachterIssuesFile, projectCodeReviewsFile, projectContentIndexDbFile, projectCreateTransactionsRoot, projectDir, projectDocsDir, projectFindingLifecycleFile, projectHistoryFile, projectIndexDir, projectInternalGithubDir, projectLocalConfigFile, projectLocalCraftbookDir, projectLocalCraftbooksRoot, projectLocalDir, projectLocalFilesDir, projectLocalGezelDir, projectLocalGezelsRoot, projectLocalImportsFile, projectLocalIndexDbFile, projectLocalIndexDir, projectLocalPendingImportsFile, projectLocalQuarantineDir, projectLocalRoot, projectLocalVillageFile, projectMemoriesDir, projectMemoryIndexDir, projectMetaFile, projectPrivateDir, projectQuestionsFile, projectReportActionsFile, projectScriptFile, projectScriptRunFile, projectScriptRunsDir, projectScriptsDir, projectShadowDir, projectStorageDir, projectStorageScope, projectTaskAboutFile, projectTaskDir, projectTaskFile, projectTaskNextIdFile, projectTaskNotesFile, projectTasksDir, projectTerminalFile, projectTerminalsDir, projectToolsetsFile, projectToolsetsInstallDir, projectTypeDir, projectTypeManifestFile, projectTypeShardPrefix, projectTypeVersionDir, projectTypeVersionManifestFile, projectTypesRoot, readConfigRaw, remotesFile, secretsFile, secretsKeyFile, sharedCloneDir, sharedClonesRoot, sharedToolsetsFile, sharedToolsetsInstallDir, systemInstalledToolsetsFile, systemToolsetsFile, systemToolsetsInstallDir, tokensFile, toolsetConfigFile, toolsetConfigsDir, userGezelDir, userProjectDir, userScriptFile, userScriptsDir };
+export { CONNECTOR_ROLLUPS_DIR_NAME, CONNECTOR_TABLES_DIR_NAME, type ExternalFolders, type GezelPaths, MACHINE_SHARED_MARKER, type MachineStorageScope, OBSERVATION_TABLE_MANIFEST_FILE, OBSERVATION_TABLE_STATE_FILE, PROJECT_DIFFPACKS_DIR_NAME, PROJECT_PROMPTS_DIR_NAME, PROJECT_SHADOW_DIR_NAME, PROJECT_TABULAR_DIR_NAME, TABULAR_COMPANION_SUFFIX, activeMachineSharedHome, aiAppItemsDir, aiAppReceiptFile, aiAppVersionDir, aiAppsRegistryFile, aiAppsRoot, ambientDashboardLatestFile, ambientDashboardStateFile, ambientDir, ambientDisplayStateFile, backupsDir, binRuntimeRoot, channelsDir, craftbookShardPrefix, craftbookTemplateDir, craftbookTemplateManifestFile, craftbookTemplateScriptFile, craftbookTemplateScriptsDir, craftbookTemplateVersionDir, craftbookTemplateVersionManifestFile, craftbookTemplatesRoot, daemonTransactionsRoot, deviceIdentityFile, enginesRoot, fallbackProjectIndexDir, fallbackProjectVillageFile, foldersStateDir, gezelDir, gezelGrowthPath, gezelHome, gezelLocalDir, gezelMemoriesDir, gezelPaths, gezelPoppetjePath, gezelSessionFile, gezelSessionsDir, gezelStorageScope, gezelToolsPath, gezelToolsetsFile, gezelToolsetsInstallDir, gildeLiveRoot, gildeLiveStateFile, gildeLiveVersionDir, gildeLiveVersionsDir, globalHistoryFile, globalIndexDbFile, globalIndexDir, keurmeesterCasesDir, keurmeesterDigestStatePath, keurmeesterDigestsDir, keurmeesterDir, knowledgeCatalogVersionDir, knowledgeCatalogsDir, knowledgeDir, knowledgeDownloadsDir, knowledgeRegistryFile, machineSharedGezelDir, machineSharedHome, machineSharedMarkerFile, machineSharedProjectDir, meesterStatusDir, meesterStatusFile, meesterStatusStateFile, pendingGrantsFile, pendingHandoffsFile, playwrightBrowsersDir, projectActivityFile, projectArtifactsDir, projectArtifactsIndexDbFile, projectBoekwachterIssuesFile, projectCodeReviewsFile, projectContentIndexDbFile, projectCreateTransactionsRoot, projectDiffpackDir, projectDiffpacksDir, projectDiffpacksFile, projectDir, projectDocsDir, projectFindingLifecycleFile, projectHistoryFile, projectIndexDir, projectInternalGithubDir, projectLocalConfigFile, projectLocalCraftbookDir, projectLocalCraftbooksRoot, projectLocalDir, projectLocalFilesDir, projectLocalGezelDir, projectLocalGezelsRoot, projectLocalImportsFile, projectLocalIndexDbFile, projectLocalIndexDir, projectLocalPendingImportsFile, projectLocalQuarantineDir, projectLocalRoot, projectLocalVillageFile, projectMemoriesDir, projectMemoryIndexDir, projectMetaFile, projectPrivateDir, projectPromptDraftDir, projectPromptsDir, projectQuestionsFile, projectReportActionsFile, projectScriptFile, projectScriptRunFile, projectScriptRunsDir, projectScriptsDir, projectShadowDir, projectStorageDir, projectStorageScope, projectTabularDir, projectTaskAboutFile, projectTaskDir, projectTaskFile, projectTaskNextIdFile, projectTaskNotesFile, projectTasksDir, projectTerminalFile, projectTerminalsDir, projectToolsetsFile, projectToolsetsInstallDir, projectTypeDir, projectTypeManifestFile, projectTypeOverlayFile, projectTypeShardPrefix, projectTypeVersionDir, projectTypeVersionManifestFile, projectTypesRoot, readConfigRaw, remotesFile, secretsFile, secretsKeyFile, sharedCloneDir, sharedClonesRoot, sharedToolsetsFile, sharedToolsetsInstallDir, systemInstalledToolsetsFile, systemToolsetsFile, systemToolsetsInstallDir, tokensFile, toolsetConfigFile, toolsetConfigsDir, userGezelDir, userProjectDir, userScriptFile, userScriptsDir };