@adhd/backlog 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/backlog",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "bin": {
     "backlog": "index.js"
   },
@@ -15,9 +15,9 @@
     "@adhd/apigen-plugin-openapi": "^0.2.2",
     "@adhd/environment": "^0.1.5",
     "@adhd/environment-base-spec": "^0.1.0",
-    "@adhd/sox-graph-store": "^0.8.4",
-    "@adhd/sox-store-adapter": "^0.5.8",
-    "@adhd/sox-telemetry": "^0.2.0",
+    "@adhd/sox-graph-store": "^0.8.6",
+    "@adhd/sox-store-adapter": "^0.7.0",
+    "@adhd/sox-telemetry": "^0.2.1",
     "pino": "10.3.1",
     "pino-pretty": "13.1.3",
     "yaml": "1.10.3"

package/store/serve-lock.d.ts

@@ -0,0 +1,42 @@
+/** Thrown when another live process already holds the serve lock for this
+ *  store. Carries the holder's pid and the lock file path so callers can
+ *  surface both — refusing SILENTLY (a bare non-zero exit with no reason)
+ *  is exactly the failure mode that let this incident go undetected. */
+export declare class ServeLockHeldError extends Error {
+    readonly holderPid: number;
+    readonly lockPath: string;
+    constructor(holderPid: number, lockPath: string);
+}
+export interface ServeLockHandle {
+    /** Idempotent. Removes the lock file ONLY if it still names this process
+     *  as holder (never deletes a lock a later process legitimately took over
+     *  after detecting this one as stale — that would delete a live peer's
+     *  lock out from under it). */
+    release: () => void;
+}
+/** `:memory:` has no filesystem identity — no cross-process concern, no lock. */
+export declare function isLockableDbPath(dbPath: string): boolean;
+/** Canonicalizes to the realpath when the file (or its parent dir) exists,
+ *  so two spellings of the same store collapse to one lock identity; falls
+ *  back to a plain absolute resolve when nothing on disk exists yet (a
+ *  not-yet-created db is still a valid lock anchor — mirrors sox-ecosystem's
+ *  `singleton.ts` `canonicalizePath`, reimplemented here for the same reason
+ *  noted in this file's header). */
+export declare function canonicalDbPath(dbPath: string): string;
+export declare function serveLockPath(dbPath: string): string;
+/**
+ * Acquire the `backlog serve` writer lock for `dbPath`. Fails LOUD and
+ * IMMEDIATELY (no spin-wait/retry-until-timeout — a refused `serve` should
+ * say why right now, not silently poll and eventually give up) when a live
+ * holder is found: throws {@link ServeLockHeldError} naming the holder's
+ * pid. A lock file whose recorded pid is no longer alive (crash, SIGKILL,
+ * native panic — the same "can't run cleanup code" cases
+ * `signal-cleanup.ts`'s own doc comment is honest about) is detected via a
+ * liveness probe on READ, not relied on to have been cleaned up by the dead
+ * process, and is reclaimed automatically.
+ *
+ * Call this BEFORE opening the store; release the returned handle only
+ * AFTER the store is fully closed (see this file's header re: the
+ * shutdown-window).
+ */
+export declare function acquireServeLock(dbPath: string): ServeLockHandle;

package/version-info.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reports this running package's own real `name`/`version`, read fresh from
+ * `package.json` on every call (never a compiled-in constant, so a
+ * republished build can never drift from what this reports). Store-free —
+ * callable by `client.ts`'s `version()` (apigen-dispatched, ctx-carrying) and
+ * by `cli.ts`'s `version` short-circuit (never opens the store) identically.
+ * Returns the same `{ name, version }` shape `client.ts`'s `BacklogVersionInfo`
+ * declares; the return type is deliberately structural (not an import of that
+ * interface) so `client.ts`'s own extraction surface (`client.d.ts`) is
+ * byte-for-byte unchanged by this extraction.
+ */
+export declare function readBacklogVersionInfo(): {
+    name: string;
+    version: string;
+};