@ontrails/core 1.0.0-beta.24 → 1.0.0-beta.29

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @ontrails/core
 
+## 1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- 1307568: Centralize Trails config module path conventions, move local config overrides to root `trails.config.local.*`, scaffold the matching gitignore entries, and load project-local Warden rules from `.trails/rules.ts` or `.trails/rules/`.
+- 371d19e: Move the default `trails.db` location to the per-user Trails state store, expose deterministic state-store path helpers, stop scaffolding disposable `.trails/cache` and `.trails/state` directories, and update topo-store documentation for the global-state substrate.
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- c36aca9: Preserve existing Result error boundaries directly and widen Warden pass-through
+  coaching beyond trail blazes.
+- 3befcf1: Configure Trails SQLite read and write connections with a busy timeout so concurrent artifact readers and writers wait through transient lock contention instead of failing immediately.
+- a4f9cf6: Reserve the `shift` error category and `WorkspaceShiftError` before the stable
+  cutover so surface mappings can distinguish moved-workspace retry verdicts.
+  Update Warden's error-mapping completeness examples to cover the reserved
+  category.
+- 9bcf34e: Add trail-owned CLI command projection metadata and serialize resolved command
+  route facts for downstream tools.
+
 ## 1.0.0-beta.24
 
 ## 1.0.0-beta.23

package/README.md

@@ -129,6 +129,7 @@ The current taxonomy is generated from the `errorClasses` owner registry and cat
 | `timeout` | 5 | 504 | -32603 | Yes | `TimeoutError` |
 | `rate_limit` | 6 | 429 | -32603 | Yes | `RateLimitError` |
 | `network` | 7 | 502 | -32603 | Yes | `NetworkError` |
+| `shift` | 10 | 503 | -32603 | Yes | `WorkspaceShiftError` |
 | `internal` | 8 | 500 | -32603 | No | `AssertionError`, `InternalError`, `DerivationError`, `RecoverableCompletionError` |
 | `auth` | 9 | 401 | -32600 | No | `AuthError` |
 | `cancelled` | 130 | 499 | -32603 | No | `CancelledError` |
@@ -161,14 +162,14 @@ The developer returns `Result.err(new NotFoundError(...))`. The framework maps i
 The root package also exposes a few low-level contracts that other framework packages build on:
 
 - **Intrinsic tracing** -- `TraceRecord`, `TraceSink`, `TraceContext`, and the sink registry helpers are the core-owned execution record shape shared by `@ontrails/observe`, `@ontrails/tracing`, and adapters.
-- **Trails DB** -- `deriveTrailsDbPath`, `deriveTrailsDir`, `ensureSubsystemSchema`, `openReadTrailsDb`, and `openWriteTrailsDb` are the generic database primitive used by framework subsystems.
+- **Trails DB** -- `deriveTrailsDbPath`, `deriveTrailsStateDir`, `deriveTrailsStateHome`, `deriveTrailsProjectKey`, `deriveTrailsDir`, `ensureSubsystemSchema`, `openReadTrailsDb`, and `openWriteTrailsDb` are the generic database primitive used by framework subsystems.
 - **Surface projection helpers** -- safe error projection, layer field projection, compose-batch validation, late-bound signal references, and Zod default-wrapper stripping are stable root exports for first-party surfaces, store helpers, and tests.
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
 ## Migration: topo-store moved to `@ontrails/topographer`
 
-Per [ADR-0042](../../docs/adr/0042-core-topographer-boundary-doctrine.md), the topo-store public API previously exported from `@ontrails/core` now lives in `@ontrails/topographer`. Generic `trails-db` helpers (`openReadTrailsDb`, `openWriteTrailsDb`, `ensureSubsystemSchema`, `deriveTrailsDbPath`, `deriveTrailsDir`) stay in core because tracing and other subsystems share them.
+Per [ADR-0042](../../docs/adr/0042-core-topographer-boundary-doctrine.md), the topo-store public API previously exported from `@ontrails/core` now lives in `@ontrails/topographer`. Generic `trails-db` helpers (`openReadTrailsDb`, `openWriteTrailsDb`, `ensureSubsystemSchema`, `deriveTrailsDbPath`, `deriveTrailsStateDir`, `deriveTrailsStateHome`, `deriveTrailsProjectKey`, `deriveTrailsDir`) stay in core because tracing and other subsystems share them.
 
 Update consumer imports:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.24",
+  "version": "1.0.0-beta.29",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",

package/src/derive.ts

@@ -50,6 +50,57 @@ export interface FieldOverride {
     | undefined;
 }
 
+// ---------------------------------------------------------------------------
+// CLI command route projection
+// ---------------------------------------------------------------------------
+
+/** Authored CLI command path shape. Strings are split on whitespace. */
+export type CliCommandPathInput = string | readonly string[];
+
+/**
+ * Authored CLI command alias shape.
+ *
+ * String aliases are sibling leaf aliases. Array aliases are absolute command
+ * paths.
+ */
+export type CliCommandAliasInput = string | readonly string[];
+
+/** Source that produced a resolved CLI command route. */
+export type CliCommandRouteSource = 'derived' | 'trail' | 'surface';
+
+/** Whether a resolved CLI command route is canonical or an alias. */
+export type CliCommandRouteKind = 'alias' | 'canonical';
+
+/** Trail-authored CLI projection metadata. */
+export interface TrailCliProjection {
+  readonly aliases?: readonly CliCommandAliasInput[] | undefined;
+  readonly path?: CliCommandPathInput | undefined;
+}
+
+/** A resolved command path accepted by a CLI surface for one trail. */
+export interface CliCommandRoute {
+  readonly kind: CliCommandRouteKind;
+  readonly path: readonly string[];
+  readonly source: CliCommandRouteSource;
+  readonly target: string;
+}
+
+/** Resolved CLI projection for one trail. */
+export interface TrailCliCommandProjection {
+  readonly path: readonly string[];
+  readonly routes: readonly CliCommandRoute[];
+}
+
+interface TrailCliProjectionInput {
+  readonly cli?: CliCommandPathInput | TrailCliProjection | undefined;
+  readonly id: string;
+}
+
+export interface DeriveTrailCliCommandProjectionOptions {
+  readonly aliases?: readonly CliCommandAliasInput[] | undefined;
+  readonly aliasSource?: Extract<CliCommandRouteSource, 'surface' | 'trail'>;
+}
+
 // ---------------------------------------------------------------------------
 // Zod v4 internals accessor
 // ---------------------------------------------------------------------------
@@ -214,6 +265,149 @@ export const deriveCliPath = (trailId: string): string[] => {
   return segments;
 };
 
+const hasWhitespace = (value: string): boolean => /\s/.test(value);
+
+const validateCliSegment = (segment: string, context: string): string => {
+  const normalized = segment.trim();
+  if (normalized.length === 0) {
+    throw new ValidationError(`${context} cannot contain empty segments`);
+  }
+  if (hasWhitespace(normalized)) {
+    throw new ValidationError(
+      `${context} segment "${segment}" cannot contain whitespace`
+    );
+  }
+  return normalized;
+};
+
+const splitCliPathString = (value: string, context: string): string[] => {
+  const segments = value
+    .trim()
+    .split(/\s+/)
+    .filter((segment) => segment.length > 0);
+  if (segments.length === 0) {
+    throw new ValidationError(`${context} cannot be empty`);
+  }
+  return segments.map((segment) => validateCliSegment(segment, context));
+};
+
+/** Normalize an authored CLI command path. */
+export const normalizeCliCommandPath = (
+  value: CliCommandPathInput,
+  context = 'CLI command path'
+): readonly string[] =>
+  typeof value === 'string'
+    ? splitCliPathString(value, context)
+    : value.map((segment) => validateCliSegment(segment, context));
+
+const isTrailCliProjection = (
+  value: CliCommandPathInput | TrailCliProjection
+): value is TrailCliProjection =>
+  typeof value !== 'string' &&
+  !Array.isArray(value) &&
+  value !== null &&
+  typeof value === 'object';
+
+const trailCliProjectionFor = (
+  trail: TrailCliProjectionInput
+): TrailCliProjection | undefined => {
+  if (trail.cli === undefined) {
+    return undefined;
+  }
+  return isTrailCliProjection(trail.cli) ? trail.cli : { path: trail.cli };
+};
+
+const deriveCanonicalCliRoute = (
+  trail: TrailCliProjectionInput
+): CliCommandRoute => {
+  const projection = trailCliProjectionFor(trail);
+  const path =
+    projection?.path === undefined
+      ? deriveCliPath(trail.id)
+      : normalizeCliCommandPath(
+          projection.path,
+          `CLI command path for trail "${trail.id}"`
+        );
+  return {
+    kind: 'canonical',
+    path,
+    source: projection?.path === undefined ? 'derived' : 'trail',
+    target: trail.id,
+  };
+};
+
+const normalizeCliAlias = ({
+  alias,
+  canonicalPath,
+  source,
+  target,
+}: {
+  readonly alias: CliCommandAliasInput;
+  readonly canonicalPath: readonly string[];
+  readonly source: Extract<CliCommandRouteSource, 'surface' | 'trail'>;
+  readonly target: string;
+}): CliCommandRoute => {
+  const context = `CLI command alias for trail "${target}"`;
+  if (typeof alias === 'string') {
+    const segment = alias.trim();
+    if (segment.length === 0) {
+      throw new ValidationError(`${context} cannot be empty`);
+    }
+    if (hasWhitespace(segment)) {
+      throw new ValidationError(
+        `${context} must be a single command segment; use a string array for absolute paths`
+      );
+    }
+    return {
+      kind: 'alias',
+      path: [
+        ...canonicalPath.slice(0, -1),
+        validateCliSegment(segment, context),
+      ],
+      source,
+      target,
+    };
+  }
+  return {
+    kind: 'alias',
+    path: normalizeCliCommandPath(alias, context),
+    source,
+    target,
+  };
+};
+
+/** Derive resolved CLI command routes for one trail. */
+export const deriveTrailCliCommandProjection = (
+  trail: TrailCliProjectionInput,
+  options?: DeriveTrailCliCommandProjectionOptions
+): TrailCliCommandProjection => {
+  const canonical = deriveCanonicalCliRoute(trail);
+  const projection = trailCliProjectionFor(trail);
+  const trailAliases =
+    projection?.aliases?.map((alias) =>
+      normalizeCliAlias({
+        alias,
+        canonicalPath: canonical.path,
+        source: 'trail',
+        target: trail.id,
+      })
+    ) ?? [];
+  const surfaceAliases =
+    options?.aliases?.map((alias) =>
+      normalizeCliAlias({
+        alias,
+        canonicalPath: canonical.path,
+        source: options.aliasSource ?? 'surface',
+        target: trail.id,
+      })
+    ) ?? [];
+
+  return {
+    path: canonical.path,
+    routes: [canonical, ...trailAliases, ...surfaceAliases],
+  };
+};
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------

package/src/errors.ts

@@ -18,6 +18,7 @@ export const errorCategories = [
   'timeout',
   'rate_limit',
   'network',
+  'shift',
   'internal',
   'auth',
   'cancelled',
@@ -179,6 +180,22 @@ export class NetworkError extends TrailsError {
   readonly retryable = true as const;
 }
 
+/**
+ * @example
+ * ```ts
+ * return Result.err(new WorkspaceShiftError('workspace changed during check'));
+ * ```
+ *
+ * Raised when the observed workspace substrate moves during one run.
+ *
+ * A shift voids the run's verdict, including passes. Callers can retry on
+ * stable ground without changing their request.
+ */
+export class WorkspaceShiftError extends TrailsError {
+  readonly category = 'shift' as const;
+  readonly retryable = true as const;
+}
+
 export class InternalError extends TrailsError {
   readonly category: ErrorCategory = 'internal';
   readonly retryable = false as const;
@@ -344,6 +361,12 @@ export const errorClasses = [
     name: 'NetworkError',
     retryable: true,
   },
+  {
+    category: 'shift',
+    ctor: WorkspaceShiftError,
+    name: 'WorkspaceShiftError',
+    retryable: true,
+  },
   {
     category: 'internal',
     ctor: InternalError,
@@ -397,6 +420,7 @@ export const codesByCategory = {
   not_found: { exit: 2, http: 404, jsonRpc: -32_601 },
   permission: { exit: 4, http: 403, jsonRpc: -32_600 },
   rate_limit: { exit: 6, http: 429, jsonRpc: -32_603 },
+  shift: { exit: 10, http: 503, jsonRpc: -32_603 },
   timeout: { exit: 5, http: 504, jsonRpc: -32_603 },
   validation: { exit: 1, http: 400, jsonRpc: -32_602 },
 } as const satisfies Record<ErrorCategory, ErrorCategoryCodes>;
@@ -414,6 +438,7 @@ const deriveCodeMap = <TCode extends keyof ErrorCategoryCodes>(
   not_found: codesByCategory.not_found[code],
   permission: codesByCategory.permission[code],
   rate_limit: codesByCategory.rate_limit[code],
+  shift: codesByCategory.shift[code],
   timeout: codesByCategory.timeout[code],
   validation: codesByCategory.validation[code],
 });
@@ -436,6 +461,7 @@ export const retryableMap: Record<ErrorCategory, boolean> = {
   not_found: false,
   permission: false,
   rate_limit: true,
+  shift: true,
   timeout: true,
   validation: false,
 } as const;

package/src/execute.ts

@@ -388,7 +388,7 @@ const prepareContext = async (
   );
   const permitted = enforcePermitRequirement(trail, baseCtx);
   if (permitted.isErr()) {
-    return Result.err(permitted.error);
+    return permitted;
   }
 
   const resources = await createResources(
@@ -1412,7 +1412,7 @@ const executeRequestedTrailVersion = async (
 
   const resolved = resolveTrailVersion(trail, reference);
   if (resolved.isErr()) {
-    return Result.err(resolved.error);
+    return resolved;
   }
 
   if (resolved.value.current) {
@@ -1496,14 +1496,14 @@ const validateContextLayerInputs = (
 ): Result<TrailContext, ValidationError> => {
   const layerInputs = readContextLayerInputs(ctx);
   if (layerInputs.isErr()) {
-    return Result.err(layerInputs.error);
+    return layerInputs;
   }
   if (layerInputs.value === undefined) {
     return Result.ok(ctx);
   }
   const validated = validateLayerInputs(layers, layerInputs.value);
   if (validated.isErr()) {
-    return Result.err(validated.error);
+    return validated;
   }
   return Result.ok({
     ...ctx,
@@ -1540,7 +1540,7 @@ const executeTrailInternal = async (
 
     const resolvedCtx = await prepareContext(trail, options);
     if (resolvedCtx.isErr()) {
-      return Result.err(resolvedCtx.error);
+      return resolvedCtx;
     }
 
     const layers = composeAttachedLayers(trail, options);
@@ -1550,7 +1550,7 @@ const executeTrailInternal = async (
         layers
       );
       if (layerCtx.isErr()) {
-        return Result.err(layerCtx.error);
+        return layerCtx;
       }
       return await runTrail(
         trail,

package/src/fire.ts

@@ -1003,7 +1003,7 @@ export const createFireFn = (
       traceSink
     );
     if (dispatch.isErr()) {
-      return Result.err(dispatch.error);
+      return dispatch;
     }
     await recordSignalLifecycleTrace(
       trackedProducerCtx,

package/src/index.ts

@@ -17,6 +17,7 @@ export {
   TimeoutError,
   RateLimitError,
   NetworkError,
+  WorkspaceShiftError,
   InternalError,
   AuthError,
   CancelledError,
@@ -391,6 +392,9 @@ export type { Topo, TopoIdentity } from './topo.js';
 export {
   deriveTrailsDbPath,
   deriveTrailsDir,
+  deriveTrailsProjectKey,
+  deriveTrailsStateDir,
+  deriveTrailsStateHome,
   ensureSubsystemSchema,
   ensureTrailsWorkspace,
   openReadTrailsDb,
@@ -441,8 +445,24 @@ export type {
 } from './layer-projection.js';
 
 // Derive
-export { deriveCliPath, deriveFields } from './derive.js';
-export type { Field, FieldOverride } from './derive.js';
+export {
+  deriveCliPath,
+  deriveFields,
+  deriveTrailCliCommandProjection,
+  normalizeCliCommandPath,
+} from './derive.js';
+export type {
+  CliCommandAliasInput,
+  CliCommandPathInput,
+  CliCommandRoute,
+  CliCommandRouteKind,
+  CliCommandRouteSource,
+  DeriveTrailCliCommandProjectionOptions,
+  Field,
+  FieldOverride,
+  TrailCliCommandProjection,
+  TrailCliProjection,
+} from './derive.js';
 
 // Compose schema
 export { buildComposeValidationSchema } from './compose-schema.js';

package/src/resource-config.ts

@@ -401,7 +401,7 @@ const doCreateResourceInstance = async (
   try {
     const created = await declaredResource.create(resourceContext);
     if (created.isErr()) {
-      return Result.err(created.error);
+      return created;
     }
 
     const instance = created.unwrap();

package/src/schedule-runtime.ts

@@ -591,7 +591,7 @@ export const createScheduleRuntime = (
 
     const validated = validateTopo(graph);
     if (validated.isErr()) {
-      return Result.err(validated.error);
+      return validated;
     }
 
     const registrations = collectScheduleActivations(graph);

package/src/serialization.ts

@@ -18,6 +18,7 @@ import {
   RateLimitError,
   RetryExhaustedError,
   TimeoutError,
+  WorkspaceShiftError,
   errorClasses,
   isTrailsError,
 } from './errors.js';
@@ -89,6 +90,7 @@ const errorFactories: Record<ErrorCategory, ErrorFactory> = {
     }
     return new RateLimitError(msg, rlOpts);
   },
+  shift: (msg, opts) => new WorkspaceShiftError(msg, opts),
   timeout: (msg, opts) => new TimeoutError(msg, opts),
   validation: (msg, opts) => new ValidationError(msg, opts),
 };

package/src/trail.ts

@@ -12,7 +12,11 @@ import {
   isActivationSource,
 } from './activation-source.js';
 import type { AnyContour } from './contour.js';
-import type { FieldOverride } from './derive.js';
+import type {
+  FieldOverride,
+  CliCommandPathInput,
+  TrailCliProjection,
+} from './derive.js';
 import type { Layer } from './layer.js';
 import type { Result } from './result.js';
 import type { AnyResource } from './resource.js';
@@ -413,6 +417,8 @@ export interface TrailSpec<
   readonly layers?: readonly Layer[] | undefined;
   /** Per-field overrides for deriveFields() (labels, hints, options) */
   readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
+  /** CLI projection metadata for canonical command path overrides and aliases. */
+  readonly cli?: CliCommandPathInput | TrailCliProjection | undefined;
   /** Contours this trail operates on. */
   readonly contours?: readonly AnyContour[] | undefined;
   /** IDs or trail objects of downstream trails this trail may invoke via ctx.compose() */

package/src/trails-db.ts

@@ -1,44 +1,36 @@
 import { Database } from 'bun:sqlite';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
 
 import { NotFoundError } from './errors.js';
 
 const TRAILS_DIR = '.trails';
 const TRAILS_DB_FILE = 'trails.db';
-const TRAILS_CACHE_DIR = 'cache';
-const TRAILS_STATE_DIR = 'state';
+const TRAILS_STORE_DIR = 'trails';
+const TRAILS_PROJECTS_DIR = 'projects';
 const SCHEMA_VERSION_TABLE = 'meta_schema_versions';
-const WORKSPACE_SUBDIRS = [TRAILS_CACHE_DIR, TRAILS_STATE_DIR] as const;
+const SQLITE_BUSY_TIMEOUT_MS = 5000;
+const PROJECT_KEY_HASH_LENGTH = 16;
+const PROJECT_KEY_NAME_FALLBACK = 'project';
 
 /**
- * The canonical lines written to a freshly-bootstrapped
- * `.trails/.gitignore`. Kept as the source of truth for every consumer that
- * needs to either write the file (scaffold) or audit its content (tests).
+ * Legacy no-op compatibility export.
  *
- * @see {@link WORKSPACE_GITIGNORE_CONTENT} for the rendered string form.
+ * `.trails/` is committed project control, not disposable cache/state. New
+ * code should not write a `.trails/.gitignore`; keep this export available for
+ * older callers during the pre-1.0 cutover.
  */
-export const WORKSPACE_GITIGNORE_LINES = [
-  '# Local config overrides',
-  'config.local.js',
-  'config.local.ts',
-  '',
-  '# Rebuildable cache',
-  'cache/',
-  '',
-  '# Mutable runtime state',
-  'state/',
-  '',
-] as const;
+export const WORKSPACE_GITIGNORE_LINES = [] as const;
 
 /**
- * The canonical rendered `.trails/.gitignore` content. Use this when writing
- * the file eagerly (e.g. during `trails create` scaffolding) or when asserting
- * on the workspace bootstrap output.
+ * Legacy no-op compatibility export. See {@link WORKSPACE_GITIGNORE_LINES}.
  */
-export const WORKSPACE_GITIGNORE_CONTENT = `${WORKSPACE_GITIGNORE_LINES.join('\n').trimEnd()}\n`;
+export const WORKSPACE_GITIGNORE_CONTENT = '';
 
 export interface TrailsDbLocationOptions {
+  readonly env?: Record<string, string | undefined>;
   readonly path?: string;
   readonly rootDir?: string;
 }
@@ -56,74 +48,81 @@ interface SchemaVersionRow {
 const deriveRootDir = (rootDir?: string): string =>
   resolve(rootDir ?? process.cwd());
 
-export const deriveTrailsDir = (options?: TrailsDbLocationOptions): string =>
-  join(deriveRootDir(options?.rootDir), TRAILS_DIR);
+const sanitizeProjectKeyName = (name: string): string => {
+  const normalized = name.replaceAll(/[^a-zA-Z0-9._-]+/g, '-');
+  return normalized.length > 0 ? normalized : PROJECT_KEY_NAME_FALLBACK;
+};
 
-export const deriveTrailsDbPath = (options?: TrailsDbLocationOptions): string =>
-  options?.path
-    ? resolve(options.path)
-    : join(deriveTrailsDir(options), TRAILS_STATE_DIR, TRAILS_DB_FILE);
+const projectHash = (rootDir: string): string =>
+  createHash('sha256')
+    .update(rootDir)
+    .digest('hex')
+    .slice(0, PROJECT_KEY_HASH_LENGTH);
 
-const ensureDbParentDir = (dbPath: string): void => {
-  mkdirSync(dirname(dbPath), { recursive: true });
+export const deriveTrailsProjectKey = (
+  options?: TrailsDbLocationOptions
+): string => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  return `${sanitizeProjectKeyName(basename(rootDir))}-${projectHash(rootDir)}`;
 };
 
-const appendMissingGitignoreLines = (
-  gitignorePath: string,
-  content: string
-): void => {
-  const existingLines = new Set(content.split('\n').map((l) => l.trim()));
-  const missing = WORKSPACE_GITIGNORE_LINES.filter(
-    (line) => line !== '' && !existingLines.has(line)
+export const deriveTrailsStateHome = (
+  options?: TrailsDbLocationOptions
+): string => {
+  const env = options?.env ?? process.env;
+  return resolve(
+    env['TRAILS_STATE_HOME'] ??
+      env['XDG_STATE_HOME'] ??
+      join(homedir(), '.local', 'state')
   );
-
-  if (missing.length === 0) {
-    return;
-  }
-
-  const next = `${content.trimEnd()}\n\n${missing.join('\n')}`;
-  writeFileSync(gitignorePath, `${next.trimEnd()}\n`);
 };
 
-const ensureWorkspaceGitignore = (trailsDir: string): void => {
-  const gitignorePath = join(trailsDir, '.gitignore');
+export const deriveTrailsStateDir = (
+  options?: TrailsDbLocationOptions
+): string =>
+  join(
+    deriveTrailsStateHome(options),
+    TRAILS_STORE_DIR,
+    TRAILS_PROJECTS_DIR,
+    deriveTrailsProjectKey(options)
+  );
+
+export const deriveTrailsDir = (options?: TrailsDbLocationOptions): string =>
+  join(deriveRootDir(options?.rootDir), TRAILS_DIR);
 
-  if (!existsSync(gitignorePath)) {
-    writeFileSync(gitignorePath, WORKSPACE_GITIGNORE_CONTENT);
-    return;
-  }
+export const deriveTrailsDbPath = (options?: TrailsDbLocationOptions): string =>
+  options?.path
+    ? resolve(options.path)
+    : join(deriveTrailsStateDir(options), TRAILS_DB_FILE);
 
-  appendMissingGitignoreLines(
-    gitignorePath,
-    readFileSync(gitignorePath, 'utf8')
-  );
+const ensureDbParentDir = (dbPath: string): void => {
+  mkdirSync(dirname(dbPath), { recursive: true });
 };
 
 /**
  * Bootstrap the `.trails/` workspace at `rootDir`.
  *
- * Creates the workspace directory plus the canonical `cache/` and `state/`
- * subdirectories, then either writes a fresh `.gitignore` matching
- * {@link WORKSPACE_GITIGNORE_CONTENT} or appends any missing canonical lines
- * to an existing one. Safe to call repeatedly. This is the single canonical
- * source of truth for workspace layout — scaffolding, configuration loading,
- * and runtime DB initialization all flow through here.
+ * Creates only the committed-control directory. Derived cache and observed
+ * state live in the per-user Trails store, so this helper intentionally does
+ * not create `.trails/cache`, `.trails/state`, or `.trails/.gitignore`.
  */
 export const ensureTrailsWorkspace = (rootDir: string): void => {
   const trailsDir = deriveTrailsDir({ rootDir });
   mkdirSync(trailsDir, { recursive: true });
-  for (const subdir of WORKSPACE_SUBDIRS) {
-    mkdirSync(join(trailsDir, subdir), { recursive: true });
-  }
-  ensureWorkspaceGitignore(trailsDir);
 };
 
 const initializeWritePragmas = (db: Database): void => {
+  db.run(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS.toString()}`);
   db.run('PRAGMA journal_mode = WAL');
   db.run('PRAGMA synchronous = NORMAL');
   db.run('PRAGMA foreign_keys = ON');
 };
 
+const initializeReadPragmas = (db: Database): void => {
+  db.run(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS.toString()}`);
+  db.run('PRAGMA foreign_keys = ON');
+};
+
 const ensureSchemaVersionTable = (db: Database): void => {
   db.run(`CREATE TABLE IF NOT EXISTS ${SCHEMA_VERSION_TABLE} (
     subsystem TEXT PRIMARY KEY,
@@ -160,15 +159,14 @@ export const openWriteTrailsDb = (
   options?: TrailsDbLocationOptions
 ): Database => {
   const rootDir = deriveRootDir(options?.rootDir);
-  const dbPath = deriveTrailsDbPath(
-    options?.path ? { path: options.path, rootDir } : { rootDir }
-  );
+  const locationOptions: TrailsDbLocationOptions = {
+    ...(options?.env === undefined ? {} : { env: options.env }),
+    ...(options?.path === undefined ? {} : { path: options.path }),
+    rootDir,
+  };
+  const dbPath = deriveTrailsDbPath(locationOptions);
 
-  if (options?.path === undefined) {
-    ensureTrailsWorkspace(rootDir);
-  } else {
-    ensureDbParentDir(dbPath);
-  }
+  ensureDbParentDir(dbPath);
 
   const db = new Database(dbPath, { create: true });
   initializeWritePragmas(db);
@@ -186,7 +184,7 @@ export const openReadTrailsDb = (
     );
   }
   const db = new Database(dbPath, { readonly: true });
-  db.run('PRAGMA foreign_keys = ON');
+  initializeReadPragmas(db);
   return db;
 };