@adhd/agent-core-env 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.1.3 (2026-10-06)
+
+### 🚀 Features
+
+- **agent-core-env:** adapter-backed registry open + BEGIN IMMEDIATE / busy-retry contract (ADR-0001 D4 step 1) ([6f889317](https://github.com/PseudoSky/adhd/commit/6f889317))
+- **vite-plugins:** absorb perf/test-resolve-fix — test-time @adhd/* source resolution ([b2022986](https://github.com/PseudoSky/adhd/commit/b2022986))
+
+### 🩹 Fixes
+
+- **agent-core-env,agent-mcp:** BEGIN IMMEDIATE + bounded BUSY retry on AgentStore read-modify-write ([d9fddae5](https://github.com/PseudoSky/adhd/commit/d9fddae5))
+- **agent-core-env,agent-mcp:** make the SQLite busy_timeout locking contract explicit ([c492feb8](https://github.com/PseudoSky/adhd/commit/c492feb8))
+- **vite:** restore import.meta.url in CJS output under vite 8 ([9690844d](https://github.com/PseudoSky/adhd/commit/9690844d))
+- **nx:** finish the ESLint v9 flat-config migration and unblock the gate ([4ccdb53e](https://github.com/PseudoSky/adhd/commit/4ccdb53e))
+
+### ❤️ Thank You
+
+- pseudosky
+
 ## 0.1.1 (2026-09-24)
 
 

package/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("@adhd/environment"),i=require("node:fs"),o=require("node:path"),y=require("better-sqlite3"),u=require("drizzle-orm/better-sqlite3"),d="agent-registry",a={namespaces:["production"],dirs:{data:{kind:"data",scope:"global"}},files:{registry:{in:"data",name:"registry.db"}},config:{}};function c(r={}){if(r.registryDbPath)return r.registryDbPath;const t=process.env.ADHD_AGENT_REGISTRY_DB_PATH;if(t)return t;const n=process.env.REGISTRY_DATABASE_PATH;if(n)return n;const e=process.env.DATABASE_PATH;return e||new g.Environment("agent-registry",a,r.scope?{scope:r.scope}:{}).files.registry}function D(r={}){const t=o.resolve(c({registryDbPath:r.registryDbPath})),n=o.dirname(t);i.existsSync(n)||i.mkdirSync(n,{recursive:!0});const e=new y(t);e.pragma("journal_mode = WAL"),e.pragma("foreign_keys = ON");const s=u.drizzle(e);return{sqlite:e,db:s}}exports.AGENT_REGISTRY_PROJECT_ID=d;exports.agentRegistryEnvironmentSpec=a;exports.openRegistryDb=D;exports.resolveRegistryDbPath=c;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const R=require("@adhd/environment"),a=require("node:fs"),i=require("node:path"),c=require("@adhd/sox-store-adapter"),b=require("better-sqlite3"),h=require("drizzle-orm/better-sqlite3"),f="agent-registry",y={namespaces:["production"],dirs:{data:{kind:"data",scope:"global"}},files:{registry:{in:"data",name:"registry.db"}},config:{}};function u(t={}){if(t.registryDbPath)return t.registryDbPath;const e=process.env.ADHD_AGENT_REGISTRY_DB_PATH;if(e)return e;const r=process.env.REGISTRY_DATABASE_PATH;if(r)return r;const n=process.env.DATABASE_PATH;return n||new R.Environment("agent-registry",y,t.scope?{scope:t.scope}:{}).files.registry}const m=5,T=20,E=500,A=5e3;function S(t){return c.isBusyError(t)||c.isConcurrentConflict(t)}function p(t){return new Promise(e=>setTimeout(e,Math.max(0,Math.round(t))))}async function l(t,e,r={}){const n=Math.max(1,Math.trunc(r.maxAttempts??m)),s=Math.max(0,r.baseDelayMs??T),D=Math.max(s,r.maxDelayMs??E);for(let o=0;;o++)try{return await t.transaction(e,{mode:"immediate"})}catch(_){if(!S(_)||o>=n-1)throw _;const d=Math.min(D,s*2**o);await p(d*(.5+Math.random()*.5))}}async function U(t={}){const e=i.resolve(u({registryDbPath:t.registryDbPath})),r=i.dirname(e);a.existsSync(r)||a.mkdirSync(r,{recursive:!0});const n=Math.max(0,Math.trunc(t.busyTimeoutMs??A)),s=await c.createTursoAdapter({dbPath:e,concurrencyMode:"multiprocess-wal"});return typeof s.init=="function"&&await s.init(),await s.pragmaSet("busy_timeout",n),s}const M=5e3;function g(t,e={}){const r=Math.max(0,Math.trunc(e.busyTimeoutMs??M));t.pragma("journal_mode = WAL"),t.pragma("foreign_keys = ON"),t.pragma(`busy_timeout = ${r}`)}function Y(t={}){const e=i.resolve(u({registryDbPath:t.registryDbPath})),r=i.dirname(e);a.existsSync(r)||a.mkdirSync(r,{recursive:!0});const n=new b(e);g(n,{busyTimeoutMs:t.busyTimeoutMs});const s=h.drizzle(n);return{sqlite:n,db:s}}exports.AGENT_REGISTRY_PROJECT_ID=f;exports.DEFAULT_BUSY_MAX_ATTEMPTS=m;exports.DEFAULT_BUSY_RETRY_BASE_DELAY_MS=T;exports.DEFAULT_BUSY_RETRY_MAX_DELAY_MS=E;exports.DEFAULT_BUSY_TIMEOUT_MS=M;exports.DEFAULT_REGISTRY_BUSY_TIMEOUT_MS=A;exports.agentRegistryEnvironmentSpec=y;exports.applyLockingPragmas=g;exports.isBusyContention=S;exports.openRegistryDb=Y;exports.openRegistryStore=U;exports.resolveRegistryDbPath=u;exports.withImmediateRetry=l;

package/index.d.ts

@@ -1,6 +1,12 @@
 export { resolveRegistryDbPath } from './resolve-registry-db-path.js';
 export type { ResolveRegistryDbPathOpts } from './resolve-registry-db-path.js';
+export { openRegistryStore } from './open-registry-store.js';
+export type { OpenRegistryStoreOpts } from './open-registry-store.js';
+export { withImmediateRetry, isBusyContention, DEFAULT_BUSY_MAX_ATTEMPTS, DEFAULT_BUSY_RETRY_BASE_DELAY_MS, DEFAULT_BUSY_RETRY_MAX_DELAY_MS, DEFAULT_REGISTRY_BUSY_TIMEOUT_MS, } from './store-transaction.js';
+export type { BusyRetryConfig } from './store-transaction.js';
 export { openRegistryDb } from './open-registry-db.js';
 export type { OpenRegistryDbOpts, RegistryDbHandle } from './open-registry-db.js';
+export { applyLockingPragmas, DEFAULT_BUSY_TIMEOUT_MS, } from './sqlite-locking.js';
+export type { ISqliteConn, LockingPragmaOpts } from './sqlite-locking.js';
 export { agentRegistryEnvironmentSpec, AGENT_REGISTRY_PROJECT_ID } from './spec.js';
 export type { AgentRegistryEnvConfig } from './spec.js';

package/index.js

@@ -1,9 +1,10 @@
-import { Environment as a } from "@adhd/environment";
-import o from "node:fs";
-import i from "node:path";
-import c from "better-sqlite3";
-import { drizzle as g } from "drizzle-orm/better-sqlite3";
-const b = "agent-registry", m = {
+import { Environment as T } from "@adhd/environment";
+import s from "node:fs";
+import o from "node:path";
+import { isBusyError as _, isConcurrentConflict as f, createTursoAdapter as A } from "@adhd/sox-store-adapter";
+import M from "better-sqlite3";
+import { drizzle as d } from "drizzle-orm/better-sqlite3";
+const B = "agent-registry", g = {
   namespaces: ["production"],
   dirs: {
     data: { kind: "data", scope: "global" }
@@ -13,33 +14,94 @@ const b = "agent-registry", m = {
   },
   config: {}
 };
-function f(e = {}) {
-  if (e.registryDbPath)
-    return e.registryDbPath;
-  const t = process.env.ADHD_AGENT_REGISTRY_DB_PATH;
-  if (t)
-    return t;
-  const n = process.env.REGISTRY_DATABASE_PATH;
-  if (n)
-    return n;
-  const r = process.env.DATABASE_PATH;
-  return r || new a(
+function m(t = {}) {
+  if (t.registryDbPath)
+    return t.registryDbPath;
+  const e = process.env.ADHD_AGENT_REGISTRY_DB_PATH;
+  if (e)
+    return e;
+  const r = process.env.REGISTRY_DATABASE_PATH;
+  if (r)
+    return r;
+  const n = process.env.DATABASE_PATH;
+  return n || new T(
     "agent-registry",
-    m,
-    e.scope ? { scope: e.scope } : {}
+    g,
+    t.scope ? { scope: t.scope } : {}
   ).files.registry;
 }
-function u(e = {}) {
-  const t = i.resolve(f({ registryDbPath: e.registryDbPath })), n = i.dirname(t);
-  o.existsSync(n) || o.mkdirSync(n, { recursive: !0 });
-  const r = new c(t);
-  r.pragma("journal_mode = WAL"), r.pragma("foreign_keys = ON");
-  const s = g(r);
-  return { sqlite: r, db: s };
+const h = 5, D = 20, p = 500, E = 5e3;
+function b(t) {
+  return _(t) || f(t);
+}
+function S(t) {
+  return new Promise(
+    (e) => setTimeout(e, Math.max(0, Math.round(t)))
+  );
+}
+async function L(t, e, r = {}) {
+  const n = Math.max(
+    1,
+    Math.trunc(r.maxAttempts ?? h)
+  ), a = Math.max(
+    0,
+    r.baseDelayMs ?? D
+  ), u = Math.max(
+    a,
+    r.maxDelayMs ?? p
+  );
+  for (let i = 0; ; i++)
+    try {
+      return await t.transaction(e, { mode: "immediate" });
+    } catch (c) {
+      if (!b(c) || i >= n - 1)
+        throw c;
+      const y = Math.min(u, a * 2 ** i);
+      await S(y * (0.5 + Math.random() * 0.5));
+    }
+}
+async function I(t = {}) {
+  const e = o.resolve(
+    m({ registryDbPath: t.registryDbPath })
+  ), r = o.dirname(e);
+  s.existsSync(r) || s.mkdirSync(r, { recursive: !0 });
+  const n = Math.max(
+    0,
+    Math.trunc(t.busyTimeoutMs ?? E)
+  ), a = await A({
+    dbPath: e,
+    concurrencyMode: "multiprocess-wal"
+  });
+  return typeof a.init == "function" && await a.init(), await a.pragmaSet("busy_timeout", n), a;
+}
+const l = 5e3;
+function R(t, e = {}) {
+  const r = Math.max(
+    0,
+    Math.trunc(e.busyTimeoutMs ?? l)
+  );
+  t.pragma("journal_mode = WAL"), t.pragma("foreign_keys = ON"), t.pragma(`busy_timeout = ${r}`);
+}
+function G(t = {}) {
+  const e = o.resolve(m({ registryDbPath: t.registryDbPath })), r = o.dirname(e);
+  s.existsSync(r) || s.mkdirSync(r, { recursive: !0 });
+  const n = new M(e);
+  R(n, { busyTimeoutMs: t.busyTimeoutMs });
+  const a = d(n);
+  return { sqlite: n, db: a };
 }
 export {
-  b as AGENT_REGISTRY_PROJECT_ID,
-  m as agentRegistryEnvironmentSpec,
-  u as openRegistryDb,
-  f as resolveRegistryDbPath
+  B as AGENT_REGISTRY_PROJECT_ID,
+  h as DEFAULT_BUSY_MAX_ATTEMPTS,
+  D as DEFAULT_BUSY_RETRY_BASE_DELAY_MS,
+  p as DEFAULT_BUSY_RETRY_MAX_DELAY_MS,
+  l as DEFAULT_BUSY_TIMEOUT_MS,
+  E as DEFAULT_REGISTRY_BUSY_TIMEOUT_MS,
+  g as agentRegistryEnvironmentSpec,
+  R as applyLockingPragmas,
+  b as isBusyContention,
+  G as openRegistryDb,
+  I as openRegistryStore,
+  m as resolveRegistryDbPath,
+  L as withImmediateRetry
 };

package/open-registry-db.d.ts

@@ -6,10 +6,14 @@ export interface OpenRegistryDbOpts {
      *  absent, the full precedence chain (function arg / env vars / canonical
      *  default) resolves the path. */
     registryDbPath?: string;
+    /** `busy_timeout` budget (ms) applied at connect time. Typed config, never
+     *  an env-var toggle (ADR-0013). Defaults to 5000ms. */
+    busyTimeoutMs?: number;
 }
 export interface RegistryDbHandle {
-    /** The raw `better-sqlite3` connection — WAL mode + `foreign_keys = ON`
-     *  already set, matching every existing family client's pragmas. */
+    /** The raw `better-sqlite3` connection — WAL mode + `foreign_keys = ON` +
+     *  `busy_timeout` already set (see `sqlite-locking.ts`), matching every
+     *  existing family client's pragmas. */
     sqlite: Database.Database;
     /** A schema-less Drizzle instance over `sqlite`. Each family package
      *  binds its OWN schema-typed Drizzle instance against this same

package/open-registry-store.d.ts

@@ -0,0 +1,15 @@
+import { StoreAdapter } from '@adhd/sox-store-adapter';
+
+export interface OpenRegistryStoreOpts {
+    /** Explicit path override — forwarded to `resolveRegistryDbPath()`. */
+    registryDbPath?: string;
+    /** `busy_timeout` budget (ms) applied at connect time. Typed config, never
+     *  an env-var toggle (sox ADR-0013). Defaults to 5000 ms. */
+    busyTimeoutMs?: number;
+}
+/**
+ * Opens (and, if needed, creates) the shared registry store through
+ * `@adhd/sox-store-adapter` (Turso, multiprocess-enabled), applying the typed
+ * `busy_timeout`. The caller owns the returned adapter and must `close()` it.
+ */
+export declare function openRegistryStore(opts?: OpenRegistryStoreOpts): Promise<StoreAdapter>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/agent-core-env",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Shared @adhd/environment-backed resolver for the agent-registry family's one shared SQLite file (agent-store-prompts/-tools, agent-core-policy/-provider, agent-engine-compiler) — resolveRegistryDbPath() + lazy openRegistryDb(), no import-time DB open.",
   "type": "module",
   "publishConfig": {
@@ -14,6 +14,7 @@
   },
   "dependencies": {
     "@adhd/environment": "^0.1.8",
+    "@adhd/sox-store-adapter": "^0.13.0",
     "better-sqlite3": "12.10.0",
     "drizzle-orm": "0.45.2"
   },

package/sqlite-locking.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `sqlite-locking.ts` — the explicit parallel-process locking contract for
+ * the agent-* SQLite clients.
+ *
+ * The repo invariant (AGENTS.md hard rule; ADR-0012, superseding ADR-0007) is
+ * that every store is parallel-process enabled: multiple processes may hold
+ * concurrent write connections to the same SQLite file. This module makes the
+ * connect-time half of that contract EXPLICIT, CONFIGURABLE and TYPED (never
+ * an env-var toggle — ADR-0013):
+ *
+ *   1. `journal_mode = WAL`     — readers do not block the writer.
+ *   2. `foreign_keys = ON`.
+ *   3. `busy_timeout = N` (ms)  — a writer that loses the lock race waits a
+ *      bounded time for the holder before surfacing an error.
+ *
+ * SCOPE NOTE (ADR-0001, backlog 331508ac): `better-sqlite3`-as-the-store is
+ * RETIRED. The sanctioned substrate is the sox store adapter (Turso) — see
+ * `open-registry-store.ts` (the adapter-backed open, applying the same
+ * `busy_timeout` via `adapter.pragmaSet`) and `store-transaction.ts` (the
+ * `BEGIN IMMEDIATE` + bounded busy-only retry contract, on top of the adapter).
+ *
+ * This module remains ONLY for the `better-sqlite3` consumers the ADR's D4
+ * sequence has not yet migrated (Drizzle-based stores still receive a
+ * better-sqlite3 handle). It is not a second locking implementation: it is the
+ * connect-time pragma trio applied to the not-yet-migrated substrate. New
+ * stores MUST start on the adapter (ADR-0001 D1).
+ */
+/** Default `busy_timeout` budget in milliseconds. Long enough to absorb a
+ *  sibling process's short write transaction, short enough that a genuinely
+ *  wedged holder still surfaces as an error rather than an infinite hang. */
+export declare const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+/** Minimal structural type for a better-sqlite3 connection — avoids importing
+ *  the runtime class merely to type the pragma call. */
+export interface ISqliteConn {
+    pragma(source: string, options?: {
+        simple: boolean;
+    }): unknown;
+}
+export interface LockingPragmaOpts {
+    /** `busy_timeout` budget in ms. Defaults to {@link DEFAULT_BUSY_TIMEOUT_MS}. */
+    busyTimeoutMs?: number;
+}
+/**
+ * Applies the connect-time locking pragmas to a raw SQLite connection:
+ * `journal_mode = WAL`, `foreign_keys = ON`, `busy_timeout = N`. Safe to call
+ * more than once. This is the ONE place the pragma trio is defined so every
+ * agent-* client stays in sync.
+ */
+export declare function applyLockingPragmas(sqlite: ISqliteConn, opts?: LockingPragmaOpts): void;

package/store-transaction.d.ts

@@ -0,0 +1,36 @@
+import { AdapterTransaction, StoreAdapter } from '@adhd/sox-store-adapter';
+
+/** Total attempts (first try + retries). Default 5 — the backlog precedent. */
+export declare const DEFAULT_BUSY_MAX_ATTEMPTS = 5;
+/** Base backoff in ms (doubles per attempt, then jittered). Default 20. */
+export declare const DEFAULT_BUSY_RETRY_BASE_DELAY_MS = 20;
+/** Per-sleep cap in ms. Default 500. */
+export declare const DEFAULT_BUSY_RETRY_MAX_DELAY_MS = 500;
+/** Default `busy_timeout` (ms) applied to every migrated registry connection. */
+export declare const DEFAULT_REGISTRY_BUSY_TIMEOUT_MS = 5000;
+export interface BusyRetryConfig {
+    /** Total attempts. Default {@link DEFAULT_BUSY_MAX_ATTEMPTS}; clamped to ≥1. */
+    maxAttempts?: number;
+    /** Base backoff in ms. Default {@link DEFAULT_BUSY_RETRY_BASE_DELAY_MS}. */
+    baseDelayMs?: number;
+    /** Per-sleep cap in ms. Default {@link DEFAULT_BUSY_RETRY_MAX_DELAY_MS}. */
+    maxDelayMs?: number;
+}
+/**
+ * True iff `err` is a busy/locked contention shape worth retrying — the
+ * adapter's portable classification (`isBusyError` / `isConcurrentConflict`),
+ * so the taxonomy stays driver-agnostic and single-sourced.
+ */
+export declare function isBusyContention(err: unknown): boolean;
+/**
+ * Run `fn` inside `adapter.transaction(fn, { mode: 'immediate' })`, retrying the
+ * WHOLE transaction a bounded number of times ONLY when it throws a busy-shaped
+ * error (see {@link isBusyContention}). Any other error propagates immediately,
+ * unretried; after the final attempt still fails busy, the last busy error is
+ * re-thrown (a sustained pileup is a real failure — this bounds the wait, it
+ * does not hide contention forever).
+ *
+ * `adapter` is narrowed to the one method this needs, so a test double can
+ * supply a minimal `{ transaction }` shape.
+ */
+export declare function withImmediateRetry<T>(adapter: Pick<StoreAdapter, 'transaction'>, fn: (tx: AdapterTransaction) => T | Promise<T>, opts?: BusyRetryConfig): Promise<T>;