@cleocode/core 2026.7.2 → 2026.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. package/dist/conduit/local-transport.d.ts +3 -6
  2. package/dist/conduit/local-transport.d.ts.map +1 -1
  3. package/dist/conduit/local-transport.js +6 -7
  4. package/dist/conduit/local-transport.js.map +1 -1
  5. package/dist/db/index.d.ts +15 -1
  6. package/dist/db/index.d.ts.map +1 -1
  7. package/dist/db/index.js +15 -1
  8. package/dist/db/index.js.map +1 -1
  9. package/dist/docs/export-document.js +16032 -22124
  10. package/dist/docs/export-document.js.map +3 -3
  11. package/dist/goal/store.d.ts.map +1 -1
  12. package/dist/goal/store.js.map +1 -1
  13. package/dist/hooks/payload-schemas.d.ts +9 -9
  14. package/dist/llm/pi/pi-session-storage.d.ts.map +1 -1
  15. package/dist/llm/pi/pi-session-storage.js +6 -1
  16. package/dist/llm/pi/pi-session-storage.js.map +1 -1
  17. package/dist/llm/plugin-facade.js +5532 -16583
  18. package/dist/llm/plugin-facade.js.map +3 -3
  19. package/dist/memory/brain-links.d.ts +26 -2
  20. package/dist/memory/brain-links.d.ts.map +1 -1
  21. package/dist/memory/brain-links.js +65 -19
  22. package/dist/memory/brain-links.js.map +1 -1
  23. package/dist/memory/brain-writer-thread.d.ts.map +1 -1
  24. package/dist/memory/brain-writer-thread.js +31 -40
  25. package/dist/memory/brain-writer-thread.js.map +1 -1
  26. package/dist/memory/claude-mem-migration.d.ts.map +1 -1
  27. package/dist/memory/claude-mem-migration.js +7 -1
  28. package/dist/memory/claude-mem-migration.js.map +1 -1
  29. package/dist/memory/dialectic-evaluator.d.ts +11 -6
  30. package/dist/memory/dialectic-evaluator.d.ts.map +1 -1
  31. package/dist/memory/dialectic-evaluator.js +8 -2
  32. package/dist/memory/dialectic-evaluator.js.map +1 -1
  33. package/dist/memory/graph-memory-bridge.d.ts.map +1 -1
  34. package/dist/memory/graph-memory-bridge.js +3 -1
  35. package/dist/memory/graph-memory-bridge.js.map +1 -1
  36. package/dist/memory/learnings.d.ts +8 -8
  37. package/dist/memory/patterns.d.ts +14 -14
  38. package/dist/memory/retrieval/build-retrieval-bundle.d.ts +1 -1
  39. package/dist/memory/retrieval/build-retrieval-bundle.d.ts.map +1 -1
  40. package/dist/memory/retrieval/build-retrieval-bundle.js.map +1 -1
  41. package/dist/memory/retrieval/observe.d.ts.map +1 -1
  42. package/dist/memory/retrieval/observe.js +31 -16
  43. package/dist/memory/retrieval/observe.js.map +1 -1
  44. package/dist/memory/session-memory.d.ts.map +1 -1
  45. package/dist/memory/session-memory.js +35 -1
  46. package/dist/memory/session-memory.js.map +1 -1
  47. package/dist/nexus/migrations/M-split-graph.d.ts.map +1 -1
  48. package/dist/nexus/migrations/M-split-graph.js +4 -1
  49. package/dist/nexus/migrations/M-split-graph.js.map +1 -1
  50. package/dist/nexus/sigil.d.ts +1 -2
  51. package/dist/nexus/sigil.d.ts.map +1 -1
  52. package/dist/nexus/user-profile.d.ts +1 -2
  53. package/dist/nexus/user-profile.d.ts.map +1 -1
  54. package/dist/orchestration/spawn-prompt.d.ts.map +1 -1
  55. package/dist/orchestration/spawn-prompt.js +4 -2
  56. package/dist/orchestration/spawn-prompt.js.map +1 -1
  57. package/dist/scaffold/ensure-skills.d.ts.map +1 -1
  58. package/dist/scaffold/ensure-skills.js +67 -0
  59. package/dist/scaffold/ensure-skills.js.map +1 -1
  60. package/dist/selfimprove/dhq-adapter.d.ts.map +1 -1
  61. package/dist/selfimprove/dhq-adapter.js +6 -2
  62. package/dist/selfimprove/dhq-adapter.js.map +1 -1
  63. package/dist/selfimprove/fix-gen.js +5635 -16565
  64. package/dist/selfimprove/fix-gen.js.map +3 -3
  65. package/dist/store/agent-registry-store.d.ts.map +1 -1
  66. package/dist/store/agent-registry-store.js +1 -2
  67. package/dist/store/agent-registry-store.js.map +1 -1
  68. package/dist/store/background-jobs.d.ts +1 -2
  69. package/dist/store/background-jobs.d.ts.map +1 -1
  70. package/dist/store/background-jobs.js.map +1 -1
  71. package/dist/store/conduit-sqlite.d.ts.map +1 -1
  72. package/dist/store/conduit-sqlite.js +1 -2
  73. package/dist/store/conduit-sqlite.js.map +1 -1
  74. package/dist/store/cross-db-cleanup.d.ts +38 -0
  75. package/dist/store/cross-db-cleanup.d.ts.map +1 -1
  76. package/dist/store/cross-db-cleanup.js +125 -0
  77. package/dist/store/cross-db-cleanup.js.map +1 -1
  78. package/dist/store/db-helpers.d.ts +1 -2
  79. package/dist/store/db-helpers.d.ts.map +1 -1
  80. package/dist/store/dual-scope-db.d.ts +304 -4
  81. package/dist/store/dual-scope-db.d.ts.map +1 -1
  82. package/dist/store/dual-scope-db.js +647 -262
  83. package/dist/store/dual-scope-db.js.map +1 -1
  84. package/dist/store/memory-accessor.d.ts +1 -1
  85. package/dist/store/memory-accessor.d.ts.map +1 -1
  86. package/dist/store/memory-accessor.js.map +1 -1
  87. package/dist/store/memory-sqlite.d.ts +1 -1
  88. package/dist/store/memory-sqlite.d.ts.map +1 -1
  89. package/dist/store/memory-sqlite.js +18 -7
  90. package/dist/store/memory-sqlite.js.map +1 -1
  91. package/dist/store/migration-manager.d.ts +7 -4
  92. package/dist/store/migration-manager.d.ts.map +1 -1
  93. package/dist/store/migration-manager.js +10 -10
  94. package/dist/store/migration-manager.js.map +1 -1
  95. package/dist/store/migration-sqlite.js +1 -1
  96. package/dist/store/migration-sqlite.js.map +1 -1
  97. package/dist/store/nexus-sqlite.d.ts +1 -1
  98. package/dist/store/nexus-sqlite.d.ts.map +1 -1
  99. package/dist/store/nexus-sqlite.js +1 -1
  100. package/dist/store/nexus-sqlite.js.map +1 -1
  101. package/dist/store/schema/attachments.d.ts +1 -1
  102. package/dist/store/schema/audit.d.ts +2 -2
  103. package/dist/store/schema/background-jobs.d.ts +1 -1
  104. package/dist/store/schema/cleo-global/agent-registry.d.ts +1 -1
  105. package/dist/store/schema/cleo-global/models-catalog.d.ts +1 -1
  106. package/dist/store/schema/cleo-global/skills.d.ts +2 -2
  107. package/dist/store/schema/cleo-project/audit.d.ts +2 -2
  108. package/dist/store/schema/cleo-project/docs.d.ts +1 -1
  109. package/dist/store/schema/cleo-project/lifecycle.d.ts +4 -4
  110. package/dist/store/schema/cleo-project/nexus-graph.d.ts +2 -2
  111. package/dist/store/schema/cleo-project/provenance-rest.d.ts +3 -3
  112. package/dist/store/schema/cleo-project/runtime.d.ts +2 -2
  113. package/dist/store/schema/cleo-project/tasks-core-batch2.d.ts +1 -1
  114. package/dist/store/schema/cleo-project/tasks-core.d.ts +3 -3
  115. package/dist/store/schema/cleo-shared/brain.d.ts +5 -5
  116. package/dist/store/schema/jsonb.js +1 -1
  117. package/dist/store/schema/jsonb.js.map +1 -1
  118. package/dist/store/schema/lifecycle.d.ts +4 -4
  119. package/dist/store/schema/memory-schema.d.ts +3 -3
  120. package/dist/store/schema/nexus-schema.d.ts +1 -1
  121. package/dist/store/schema/provenance/releases.d.ts +3 -3
  122. package/dist/store/schema/skills-schema.d.ts +2 -2
  123. package/dist/store/schema/tasks.d.ts +2 -2
  124. package/dist/store/skills-db.d.ts +1 -1
  125. package/dist/store/skills-db.d.ts.map +1 -1
  126. package/dist/store/skills-db.js +1 -1
  127. package/dist/store/skills-db.js.map +1 -1
  128. package/dist/store/sqlite.d.ts +1 -1
  129. package/dist/store/sqlite.d.ts.map +1 -1
  130. package/dist/store/sqlite.js +30 -8
  131. package/dist/store/sqlite.js.map +1 -1
  132. package/dist/store/validation-schemas.d.ts +35 -35
  133. package/dist/store/writer-lease.d.ts +85 -53
  134. package/dist/store/writer-lease.d.ts.map +1 -1
  135. package/dist/store/writer-lease.js +194 -112
  136. package/dist/store/writer-lease.js.map +1 -1
  137. package/dist/tasks/add.d.ts.map +1 -1
  138. package/dist/tasks/add.js +9 -2
  139. package/dist/tasks/add.js.map +1 -1
  140. package/dist/tasks/backfill-child-projections.d.ts.map +1 -1
  141. package/dist/tasks/backfill-child-projections.js +3 -1
  142. package/dist/tasks/backfill-child-projections.js.map +1 -1
  143. package/dist/tasks/evidence.d.ts +17 -0
  144. package/dist/tasks/evidence.d.ts.map +1 -1
  145. package/dist/tasks/evidence.js +145 -35
  146. package/dist/tasks/evidence.js.map +1 -1
  147. package/dist/tasks/infer-add-params.d.ts.map +1 -1
  148. package/dist/tasks/infer-add-params.js +6 -1
  149. package/dist/tasks/infer-add-params.js.map +1 -1
  150. package/dist/tasks/tool-cache.d.ts +29 -0
  151. package/dist/tasks/tool-cache.d.ts.map +1 -1
  152. package/dist/tasks/tool-cache.js +166 -6
  153. package/dist/tasks/tool-cache.js.map +1 -1
  154. package/dist/tasks/tool-resolver.d.ts +5 -1
  155. package/dist/tasks/tool-resolver.d.ts.map +1 -1
  156. package/dist/tasks/tool-resolver.js +28 -20
  157. package/dist/tasks/tool-resolver.js.map +1 -1
  158. package/dist/telemetry/index.d.ts.map +1 -1
  159. package/dist/telemetry/index.js +4 -1
  160. package/dist/telemetry/index.js.map +1 -1
  161. package/dist/telemetry/sqlite.d.ts +1 -2
  162. package/dist/telemetry/sqlite.d.ts.map +1 -1
  163. package/dist/telemetry/sqlite.js +1 -2
  164. package/dist/telemetry/sqlite.js.map +1 -1
  165. package/package.json +14 -14
  166. package/schemas/project-context.schema.json +69 -0
  167. package/templates/workflows/release-prepare.yml.tmpl +10 -0
@@ -51,8 +51,7 @@
51
51
  */
52
52
  import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
53
53
  import { type ExodusAbortDetail } from './exodus/abort-events.js';
54
- import type * as CleoGlobalSchemaTypes from './schema/cleo-global/index.js';
55
- import type * as CleoProjectSchemaTypes from './schema/cleo-project/index.js';
54
+ import { type WriterLeaseIdentity } from './writer-lease.js';
56
55
  /**
57
56
  * The two canonical scopes for the consolidated dual-scope `cleo.db` substrate.
58
57
  *
@@ -61,9 +60,9 @@ import type * as CleoProjectSchemaTypes from './schema/cleo-project/index.js';
61
60
  */
62
61
  export type DualScope = 'project' | 'global';
63
62
  /** Typed Drizzle handle for the project-scope `cleo.db`. */
64
- export type CleoProjectDb = NodeSQLiteDatabase<typeof CleoProjectSchemaTypes>;
63
+ export type CleoProjectDb = NodeSQLiteDatabase;
65
64
  /** Typed Drizzle handle for the global-scope `cleo.db`. */
66
- export type CleoGlobalDb = NodeSQLiteDatabase<typeof CleoGlobalSchemaTypes>;
65
+ export type CleoGlobalDb = NodeSQLiteDatabase;
67
66
  /**
68
67
  * Handle returned by {@link openDualScopeDb}.
69
68
  *
@@ -78,6 +77,18 @@ export interface DualScopeDbHandle<TScope extends DualScope = DualScope> {
78
77
  readonly scope: TScope;
79
78
  /** Absolute path to the underlying SQLite file. */
80
79
  readonly dbPath: string;
80
+ /**
81
+ * Immutable writer-lease identity bound to this exact handle at construction
82
+ * (T12042). The chokepoint write primitives derive scope + dbPath from this
83
+ * identity via {@link resolveDbIdentity} — a caller cannot pair file-A
84
+ * identity with file-B DB. Frozen and normalized.
85
+ */
86
+ readonly identity: WriterLeaseIdentity;
87
+ /**
88
+ * Whether the underlying native `DatabaseSync` connection is still
89
+ * open. Reflects `nativeDb.isOpen` and is `false` after `close()`.
90
+ */
91
+ readonly isOpen: boolean;
81
92
  /**
82
93
  * Set ONLY when the exodus-on-open data-continuity gate ABORTED the first-open
83
94
  * auto-migration for this scope (T11828 · DHQ-059). When present, the handle is
@@ -253,6 +264,285 @@ export declare function openDualScopeDbAtPath(scope: 'global', dbPath: string, e
253
264
  * @internal
254
265
  */
255
266
  export declare function _resetDualScopeDbCache(scope?: DualScope): void;
267
+ /**
268
+ * A typed handle to a single project's consolidated `cleo.db`, keyed by canonical
269
+ * database path. Obtained from {@link CleoRuntime.openProject}.
270
+ *
271
+ * Each {@link ProjectStore} wraps ONE shared {@link DualScopeDbHandle} — closing
272
+ * it affects only this project; other projects and the global scope are untouched.
273
+ *
274
+ * ## Lifecycle identity
275
+ *
276
+ * Every store carries an opaque identity tag. Its `close()` is stale-safe: it only
277
+ * evicts the registry entry when that entry still belongs to THIS store (not a
278
+ * replacement opened after close). An old stale `close()` is a no-op.
279
+ *
280
+ * @task T12036 (E6-L12)
281
+ * @epic T11249 (E6)
282
+ * @saga T11242
283
+ */
284
+ export interface ProjectStore {
285
+ /** The literal scope discriminator. */
286
+ readonly scope: 'project';
287
+ /** Absolute on-disk path to this project's `cleo.db`. */
288
+ readonly dbPath: string;
289
+ /**
290
+ * Immutable writer-lease identity bound to this store's underlying
291
+ * {@link DualScopeDbHandle} at construction (T12042).
292
+ */
293
+ readonly identity: WriterLeaseIdentity;
294
+ /** The typed Drizzle ORM handle for the project-scope consolidated schema. */
295
+ readonly db: CleoProjectDb;
296
+ /**
297
+ * Whether the underlying native `DatabaseSync` connection is still
298
+ * open. `false` after `close()`. Delegates to
299
+ * {@link DualScopeDbHandle.isOpen}.
300
+ */
301
+ readonly isOpen: boolean;
302
+ /**
303
+ * Set when the exodus-on-open auto-migration aborted for this project
304
+ * (T11828 · DHQ-059). `undefined` on a normal open.
305
+ */
306
+ readonly exodusAbort?: ExodusAbortDetail;
307
+ /**
308
+ * Close this project's handle and evict it from the runtime registry
309
+ * if-and-only-if the registry still points to this store. Safe to call
310
+ * multiple times (idempotent). Does NOT affect the global scope or other
311
+ * open projects.
312
+ */
313
+ close(): void;
314
+ }
315
+ /**
316
+ * A typed handle to the global consolidated `cleo.db`, keyed by canonical
317
+ * database path. Obtained from {@link CleoRuntime.openGlobal}.
318
+ *
319
+ * The {@link GlobalStore} wraps the shared dual-scope chokepoint handle —
320
+ * closing it only disposes the global entry, never any project.
321
+ *
322
+ * ## Lifecycle identity
323
+ *
324
+ * Same stale-safe semantics as {@link ProjectStore}: an old `close()` after a
325
+ * reopen is a no-op.
326
+ *
327
+ * @task T12036 (E6-L12)
328
+ * @epic T11249 (E6)
329
+ * @saga T11242
330
+ */
331
+ export interface GlobalStore {
332
+ /** The literal scope discriminator. */
333
+ readonly scope: 'global';
334
+ /** Absolute on-disk path to the global `cleo.db`. */
335
+ readonly dbPath: string;
336
+ /**
337
+ * Immutable writer-lease identity bound to this store's underlying
338
+ * {@link DualScopeDbHandle} at construction (T12042).
339
+ */
340
+ readonly identity: WriterLeaseIdentity;
341
+ /** The typed Drizzle ORM handle for the global-scope consolidated schema. */
342
+ readonly db: CleoGlobalDb;
343
+ /**
344
+ * Whether the underlying native `DatabaseSync` connection is still
345
+ * open. `false` after `close()`. Delegates to
346
+ * {@link DualScopeDbHandle.isOpen}.
347
+ */
348
+ readonly isOpen: boolean;
349
+ /**
350
+ * Set when the exodus-on-open auto-migration aborted for the global scope
351
+ * (T11828 · DHQ-059). `undefined` on a normal open.
352
+ */
353
+ readonly exodusAbort?: ExodusAbortDetail;
354
+ /**
355
+ * Close the global handle and evict it from the runtime registry
356
+ * if-and-only-if the registry still points to this store. Safe to call
357
+ * multiple times (idempotent).
358
+ */
359
+ close(): void;
360
+ }
361
+ /**
362
+ * The CleoRuntime store registry — the explicit composition root that owns
363
+ * project and global database entries keyed by canonical database path.
364
+ *
365
+ * Created via {@link createCleoRuntime}. Each entry in the registry is a
366
+ * {@link ProjectStore} or {@link GlobalStore} that wraps a shared consolidated
367
+ * {@link DualScopeDbHandle} obtained from the dual-scope chokepoint
368
+ * ({@link openDualScopeDbAtPath}). The registry provides:
369
+ *
370
+ * - **Path-keyed identity** — entries are keyed by `${scope}::${canonical
371
+ * dbPath}` (scoped composite key), not cwd or "last opened project".
372
+ * Equivalent path spellings are normalized via `path.resolve` before keying
373
+ * so `/path/./to/cleo.db` and `/path/to/cleo.db` single-flight together.
374
+ * - **Single-flight** — concurrent `openProject(p)` or `openGlobal()` calls
375
+ * for the same key share one initialization. If the entry is closed during
376
+ * that initialization, the acquired handle is closed and the openers reject.
377
+ * - **Scoped disposal** — closing a project never closes another project or
378
+ * the global scope. `closeAll()` disposes every entry. Each store's `close()`
379
+ * is stale-safe: only evicts if the registry still references that exact
380
+ * store instance.
381
+ * - **Cache-hit liveness** — when the underlying `DatabaseSync` was externally
382
+ * closed, the registry evicts and reopens (mirrors the dual-scope chokepoint
383
+ * pattern).
384
+ *
385
+ * ## Cross-runtime sharing
386
+ *
387
+ * Two separate {@link CleoRuntime} instances (created by independent calls to
388
+ * {@link createCleoRuntime}) share the **process-global** dual-scope handle
389
+ * cache (`_cache` in this module). A project opened by runtime A returns a
390
+ * store whose `close()` closes that shared handle — runtime B's store for the
391
+ * same path will observe `isOpen === false` on its store, and the
392
+ * **cache-hit liveness** check in this runtime will reacquire a fresh handle
393
+ * on the next `openProject`/`openGlobal`. This is by design: the runtime
394
+ * registry owns **entry lifecycle**, not the underlying connection.
395
+ *
396
+ * For connection-level isolation, pass `{ dedicated: true }` to
397
+ * {@link CleoRuntime.openProject} or {@link CleoRuntime.openGlobal}. This
398
+ * opens a second `DatabaseSync` connection to the same file (WAL allows
399
+ * concurrent connections), bypasses the shared chokepoint cache, and returns
400
+ * a store whose `close()` closes only that dedicated connection. Dedicated
401
+ * entries are NOT keyed or tracked by the runtime registry — they are
402
+ * returned directly and the caller is responsible for closing them.
403
+ *
404
+ * @task T12036 (E6-L12)
405
+ * @epic T11249 (E6)
406
+ * @saga T11242
407
+ */
408
+ /**
409
+ * Options for {@link CleoRuntime.openProject} and
410
+ * {@link CleoRuntime.openGlobal}.
411
+ *
412
+ * @task T12036 (E6-L12)
413
+ */
414
+ export interface CleoRuntimeOpenOptions {
415
+ /**
416
+ * When `true`, open a DEDICATED, NON-cached connection — a second SQLite
417
+ * handle to the same file, independent of the singleton `_cache`. The
418
+ * returned store is NOT tracked in the runtime registry and its `close()`
419
+ * closes only that dedicated connection. Used for isolation between
420
+ * concurrent consumers (e.g. a snapshot worker, a migration engine).
421
+ *
422
+ * @default false
423
+ */
424
+ readonly dedicated?: boolean;
425
+ }
426
+ export interface CleoRuntime {
427
+ /**
428
+ * Open (or reuse) the project-scope `cleo.db` at the given path.
429
+ *
430
+ * The path may be relative or absolute — it is normalized via
431
+ * `path.resolve()` before keying. The path MUST resolve to a project's
432
+ * canonical `cleo.db` file (use {@link resolveDualScopeDbPath} to compute
433
+ * it from a project root directory).
434
+ *
435
+ * Concurrent calls for the same normalized path single-flight — all callers
436
+ * receive the same {@link ProjectStore} instance unless `dedicated: true`
437
+ * was passed.
438
+ *
439
+ * @param dbPath - Absolute or relative path to the project's `cleo.db`.
440
+ * Normalized via `path.resolve()` before keying.
441
+ * @param options - Optional open mode (e.g. `{ dedicated: true }`).
442
+ * @returns A typed {@link ProjectStore} bound to the requested path.
443
+ */
444
+ openProject(dbPath: string, options?: CleoRuntimeOpenOptions): Promise<ProjectStore>;
445
+ /**
446
+ * Open (or reuse) the global-scope `cleo.db`. The path is resolved
447
+ * internally via {@link getCleoHome}.
448
+ *
449
+ * Concurrent calls single-flight — all callers receive the same
450
+ * {@link GlobalStore} instance unless `dedicated: true`.
451
+ *
452
+ * @param options - Optional open mode (e.g. `{ dedicated: true }`).
453
+ * @returns A typed {@link GlobalStore} bound to the global scope.
454
+ */
455
+ openGlobal(options?: CleoRuntimeOpenOptions): Promise<GlobalStore>;
456
+ /**
457
+ * Close and evict a single project entry from the registry. The
458
+ * underlying dual-scope handle is closed (evicted from the chokepoint
459
+ * cache) and this project is removed from the registry map. Other
460
+ * projects and the global scope are unaffected.
461
+ *
462
+ * If the project is mid-initialization, the in-flight open is cancelled:
463
+ * its acquired handle is closed and its promise rejects.
464
+ *
465
+ * Idempotent — a path not in the registry is a no-op.
466
+ *
467
+ * @param dbPath - The path previously passed to {@link openProject}.
468
+ * Normalized internally.
469
+ */
470
+ closeProject(dbPath: string): void;
471
+ /**
472
+ * Close and evict every entry in the registry. Disposes all project
473
+ * handles and the global handle if open. Cancels any in-flight opens.
474
+ * Safe to call multiple times.
475
+ */
476
+ closeAll(): void;
477
+ /**
478
+ * The set of composite registry keys (`scope::normalizedDbPath`)
479
+ * currently tracked by this runtime. The key format matches the
480
+ * internal scope-qualified cache key and distinguishes a project
481
+ * path from a global path that happens to share the same spelling.
482
+ *
483
+ * Read-only snapshot — concurrent opens/closes may race the snapshot.
484
+ */
485
+ readonly openPaths: ReadonlySet<string>;
486
+ }
487
+ /**
488
+ * Override the dual-scope opener function used by the given
489
+ * {@link CleoRuntime} instance. Tests inject a custom opener to return a
490
+ * pre-closed handle, exercising the post-await liveness and bounded-
491
+ * reacquisition code paths.
492
+ *
493
+ * The injected function receives the same `(scope, dbPath)` signature as
494
+ * {@link openDualScopeDbAtPath} and must return a
495
+ * {@link DualScopeDbHandle}. Only non-dedicated opens (
496
+ * {@link CleoRuntime.openProject} and {@link CleoRuntime.openGlobal}
497
+ * without `{ dedicated: true }`) are affected. Dedicated opens always
498
+ * call {@link openDualScopeDbAtPath} directly — a custom opener can
499
+ * never turn a dedicated store into a cached/shared store.
500
+ *
501
+ * Pass `undefined` to restore the default (`openDualScopeDbAtPath`).
502
+ *
503
+ * @param runtime - The runtime instance to configure.
504
+ * @param fn - The opener to use, or `undefined` to reset.
505
+ *
506
+ * @internal Test seam; imported directly from this module, not the barrel.
507
+ */
508
+ export declare function setRuntimeOpenFn(runtime: CleoRuntime, fn: typeof openDualScopeDbAtPath | undefined): void;
509
+ /**
510
+ * Create a new {@link CleoRuntime} store registry.
511
+ *
512
+ * The returned runtime is the explicit composition root for project and
513
+ * global database entries. Use {@link CleoRuntime.openProject} to open a
514
+ * project's `cleo.db` at a canonical path, and {@link CleoRuntime.openGlobal}
515
+ * for the global scope. Closing a project via {@link CleoRuntime.closeProject}
516
+ * or the store's own `close()` disposes only that entry.
517
+ *
518
+ * ## Cross-runtime behavior
519
+ *
520
+ * Two separate runtime instances SHARE the **process-global dual-scope
521
+ * handle cache** (`_cache`). Closing a store in one runtime closes the
522
+ * shared `DatabaseSync` — another runtime referencing the same path
523
+ * will observe a closed connection. The **cache-hit liveness** check in
524
+ * this runtime reacquires a fresh handle on the next `openProject`/
525
+ * `openGlobal`. This is by design: the runtime owns **entry lifecycle**,
526
+ * not the underlying connection. Use a dedicated connection for isolation.
527
+ *
528
+ * @returns A fresh {@link CleoRuntime} instance with an empty registry.
529
+ *
530
+ * @example
531
+ * ```ts
532
+ * import { createCleoRuntime, resolveDualScopeDbPath } from '@cleocode/core/db';
533
+ *
534
+ * const runtime = createCleoRuntime();
535
+ * const projectA = await runtime.openProject(resolveDualScopeDbPath('project', '/path/to/projA'));
536
+ * const projectB = await runtime.openProject(resolveDualScopeDbPath('project', '/path/to/projB'));
537
+ * // projectA and projectB are distinct, independent handles.
538
+ * projectA.close(); // Only closes projectA; projectB and any global handle are intact.
539
+ * ```
540
+ *
541
+ * @task T12036 (E6-L12)
542
+ * @epic T11249 (E6)
543
+ * @saga T11242
544
+ */
545
+ export declare function createCleoRuntime(): CleoRuntime;
256
546
  import type { InferInsertModel } from 'drizzle-orm';
257
547
  import type { SQLiteTableWithColumns, TableConfig } from 'drizzle-orm/sqlite-core';
258
548
  /**
@@ -276,6 +566,11 @@ import type { SQLiteTableWithColumns, TableConfig } from 'drizzle-orm/sqlite-cor
276
566
  * the consolidated-schema MUTATION primitives, so the guard is write-only and
277
567
  * never affects read paths.
278
568
  *
569
+ * Derives the writer-lease identity from the DB handle itself via
570
+ * {@link resolveDbIdentity} — the identity was registered at
571
+ * {@link DualScopeDbHandle} construction, so a caller cannot pair file-A
572
+ * identity with file-B DB (T12042).
573
+ *
279
574
  * @example
280
575
  * ```ts
281
576
  * import { tasksTasksTable } from '@cleocode/core/store/schema/cleo-project';
@@ -284,6 +579,7 @@ import type { SQLiteTableWithColumns, TableConfig } from 'drizzle-orm/sqlite-cor
284
579
  *
285
580
  * @task T11513 (E4-T2)
286
581
  * @task T11828 (write-side exodus-abort guard)
582
+ * @task T12042 (E6-L12b — exact DB-bound identity)
287
583
  * @epic T11247 (E4)
288
584
  * @saga T11242
289
585
  */
@@ -309,6 +605,9 @@ export declare function insertIdempotent<TTable extends SQLiteTableWithColumns<T
309
605
  * Refuses the write (throws {@link ExodusAbortWriteUnsafeError}) when a prior
310
606
  * exodus-on-open aborted in this process (T11828 · DHQ-059) — write-only guard.
311
607
  *
608
+ * Derives the writer-lease identity from the DB handle itself via
609
+ * {@link resolveDbIdentity} (T12042 — exact DB-bound identity, no fallback).
610
+ *
312
611
  * @example
313
612
  * ```ts
314
613
  * await upsertIdempotent(db, tasksTasksTable, updatedTask, 'idempotencyKey',
@@ -317,6 +616,7 @@ export declare function insertIdempotent<TTable extends SQLiteTableWithColumns<T
317
616
  *
318
617
  * @task T11513 (E4-T2)
319
618
  * @task T11828 (write-side exodus-abort guard)
619
+ * @task T12042 (E6-L12b — exact DB-bound identity)
320
620
  * @epic T11247 (E4)
321
621
  * @saga T11242
322
622
  */
@@ -1 +1 @@
1
- {"version":3,"file":"dual-scope-db.d.ts","sourceRoot":"","sources":["../../src/store/dual-scope-db.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"dual-scope-db.d.ts","sourceRoot":"","sources":["../../src/store/dual-scope-db.ts"],"names":[],"mappings":"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"}