@decibelsystems/tools 2.1.4 → 3.0.0

package/dist/decibelPaths.js

@@ -14,13 +14,33 @@ import { log } from './config.js';
 /**
  * Check if a directory exists
  */
+/**
+ * Does this directory exist — and say so only when we could actually tell.
+ *
+ * ISS-0153, second round. The readdir calls below were made to THROW on an
+ * unreadable store rather than return empty, and the fix was reported as
+ * landed. It never fired: every one of them sits behind this guard, and this
+ * guard caught everything. A store at chmod 000 makes stat() fail with EACCES
+ * on the directory INSIDE it, so `dirExists` answered false, the readdir was
+ * skipped, and the throw was unreachable. The result was the exact behaviour
+ * the fix was written to remove — "no issues" for a project whose issues could
+ * not be read — with the code that says otherwise sitting right there.
+ *
+ * ENOENT and ENOTDIR mean the directory genuinely is not there, which is what
+ * an untouched project looks like. Every other errno means it may well be
+ * there and this process cannot see it, and that is not an answer this
+ * function is entitled to give.
+ */
 async function dirExists(dirPath) {
     try {
         const stat = await fs.stat(dirPath);
         return stat.isDirectory();
     }
-    catch {
-        return false;
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return false;
+        throw new Error(`STORE_UNREADABLE: cannot stat ${dirPath} (${code ?? 'unknown'})`);
     }
 }
 // ============================================================================
@@ -107,6 +127,17 @@ export async function readFilesFromBothPaths(projectId, subpath, extensions = ['
     const paths = await resolveDecibelPaths(projectId, subpath);
     const seen = new Set();
     const results = [];
+    // ISS-0153: a directory that exists but cannot be opened is NOT an empty
+    // directory. Both reads below used to `catch { /* Directory read failed */ }`
+    // and return whatever had been collected — which, for an unreadable store,
+    // was nothing. Every caller then reported "no issues" for a project whose
+    // issues it simply could not see.
+    //
+    // These now THROW. "I could not look" is an exceptional condition, not an
+    // empty result, and letting it propagate turns it into a loud tool failure at
+    // no cost to the six call sites. Note the dirExists() guard above already
+    // handles the ordinary not-created-yet case, so reaching the readdir at all
+    // means the directory is really there.
     // Read primary first (takes precedence)
     if (await dirExists(paths.primary)) {
         try {
@@ -121,8 +152,9 @@ export async function readFilesFromBothPaths(projectId, subpath, extensions = ['
                 }
             }
         }
-        catch {
-            // Directory read failed
+        catch (err) {
+            const code = err.code ?? 'unknown';
+            throw new Error(`STORE_UNREADABLE: cannot read ${paths.primary} (${code})`);
         }
     }
     // Read legacy, skip duplicates
@@ -141,8 +173,9 @@ export async function readFilesFromBothPaths(projectId, subpath, extensions = ['
                 }
             }
         }
-        catch {
-            // Directory read failed
+        catch (err) {
+            const code = err.code ?? 'unknown';
+            throw new Error(`STORE_UNREADABLE: cannot read ${paths.legacy} (${code})`);
         }
     }
     return results;

package/dist/decibelPaths.js.map

@@ -1 +1 @@
-{"version":3,"file":"decibelPaths.js","sourceRoot":"","sources":["../src/decibelPaths.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,wCAAwC;AACxC,+EAA+E;AAC/E,8EAA8E;AAC9E,uDAAuD;AACvD,+EAA+E;AAE/E,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAiBlC,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;GAEG;AACH,KAAK,UAAU,SAAS,CAAC,OAAe;IACtC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAiB,EACjB,OAAe;IAEf,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAEpD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAE3D,MAAM,aAAa,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;IAE7C,IAAI,YAAY,GAAkC,MAAM,CAAC;IACzD,IAAI,kBAAsC,CAAC;IAE3C,IAAI,aAAa,EAAE,CAAC;QAClB,YAAY,GAAG,SAAS,CAAC;QACzB,0EAA0E;QAC1E,IAAI,YAAY,EAAE,CAAC;YACjB,kBAAkB,GAAG,4CAA4C,SAAS,8DAA8D,CAAC;YACzI,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;SAAM,IAAI,YAAY,EAAE,CAAC;QACxB,YAAY,GAAG,QAAQ,CAAC;QACxB,kBAAkB,GAAG,qCAAqC,SAAS,mCAAmC,CAAC;QACvG,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO;QACL,OAAO;QACP,MAAM;QACN,YAAY;QACZ,kBAAkB;KACnB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAAiB,EACjB,OAAe;IAEf,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAE5D,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;SAAM,IAAI,KAAK,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC,MAAM,CAAC;IACtB,CAAC;IAED,mEAAmE;IACnE,OAAO,KAAK,CAAC,OAAO,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAiB,EACjB,OAAe;IAEf,MAAM,OAAO,GAAG,MAAM,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACpD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,SAAiB,EACjB,OAAe;IAEf,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,MAAM,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,MAAM,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,SAAiB,EACjB,OAAe,EACf,aAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC;IAE/C,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,OAAO,GAAyD,EAAE,CAAC;IAEzE,wCAAwC;IACxC,IAAI,MAAM,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;oBAC/C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBACf,OAAO,CAAC,IAAI,CAAC;wBACX,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC;wBACxC,MAAM,EAAE,SAAS;qBAClB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,IAAI,MAAM,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBAClE,OAAO,CAAC,IAAI,CAAC;wBACX,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC;wBACvC,MAAM,EAAE,QAAQ;qBACjB,CAAC,CAAC;oBACH,IAAI,KAAK,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;wBAC3C,GAAG,CAAC,cAAc,IAAI,kCAAkC,SAAS,EAAE,CAAC,CAAC;oBACvE,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"decibelPaths.js","sourceRoot":"","sources":["../src/decibelPaths.ts"],"names":[],"mappings":"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"}

package/dist/domain/issue.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The complete status vocabulary. Closed set — if a value is not here, it is
+ * not a status, and normalizeStatus decides what to do about it.
+ */
+export declare const ISSUE_STATUSES: readonly ["open", "in_progress", "blocked", "closed", "wontfix"];
+export type IssueStatus = (typeof ISSUE_STATUSES)[number];
+/** Statuses meaning "no longer needs work". Everything else is live. */
+export declare const TERMINAL_STATUSES: ReadonlySet<IssueStatus>;
+export declare function isTerminal(status: IssueStatus): boolean;
+export declare function isLive(status: IssueStatus): boolean;
+export interface NormalizedStatus {
+    status: IssueStatus;
+    /** Set when the raw value was not already canonical. */
+    normalizedFrom?: string;
+    /**
+     * True when the raw value matched nothing and the fallback was used. The
+     * caller decides whether that is a warning or a hard error; the model will
+     * not invent a meaning for a value it does not recognize.
+     */
+    unrecognized?: boolean;
+}
+/**
+ * Map any on-disk status to the canonical vocabulary.
+ *
+ * Missing status defaults to `open` — that matches the previous reader's
+ * behaviour and is the safe direction: a record wrongly shown as open gets
+ * triaged, whereas one wrongly shown as closed disappears.
+ */
+export declare function normalizeStatus(raw: unknown): NormalizedStatus;
+export declare const ISSUE_SEVERITIES: readonly ["low", "med", "high", "critical"];
+export type IssueSeverity = (typeof ISSUE_SEVERITIES)[number];
+export declare const ISSUE_PRIORITIES: readonly ["low", "medium", "high", "critical"];
+export type IssuePriority = (typeof ISSUE_PRIORITIES)[number];
+/**
+ * A stable identifier that survives everything the human-facing id does not.
+ *
+ * ISS-NNNN is a display name: it is derived from a directory scan, it is
+ * reassigned when duplicates are repaired (four were, in Phase 2), and it is
+ * allocated independently per checkout — which is exactly how the same issue
+ * came to exist as ISS-0112 on one volume and ISS-0115 on another with nothing
+ * in the data connecting them. `uid` is the identity; `id` is the label.
+ *
+ * UUIDv7 rather than v4 because it is time-ordered: records sort by creation
+ * without consulting a timestamp field, and a Postgres index on it stays local
+ * rather than scattering writes across the tree when this reaches HQ sync.
+ */
+export declare function newUid(now?: number): string;
+export declare function isUid(value: unknown): value is string;
+/**
+ * One issue, as the rest of the system should think about it.
+ *
+ * Deliberately absent: file path, file format, frontmatter layout, and the
+ * `**Status:**` line that markdown records carry in their body. That line is a
+ * rendering of `status`, not a second copy of it — treating it as data is what
+ * let sixteen records drift into saying `open` while the tools read them as
+ * closed. The codec regenerates it on write; nothing else may touch it.
+ */
+export interface Issue {
+    /** Stable identity. Optional only until the backfill completes. */
+    uid?: string;
+    /** Human-facing label, e.g. ISS-0112. Renumberable; not identity. */
+    id: string;
+    title: string;
+    status: IssueStatus;
+    severity?: IssueSeverity;
+    priority?: IssuePriority;
+    tags?: string[];
+    epicId?: string;
+    project?: string;
+    /** Prose body: the markdown after the header block, or `description:`. */
+    details?: string;
+    resolution?: string;
+    created_at?: string;
+    updated_at?: string;
+    closed_at?: string;
+}
+//# sourceMappingURL=issue.d.ts.map

package/dist/domain/issue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../src/domain/issue.ts"],"names":[],"mappings":"AA8BA;;;GAGG;AACH,eAAO,MAAM,cAAc,kEAMjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,WAAW,CAGrD,CAAC;AAEH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEvD;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEnD;AA2BD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAmB9D;AAED,eAAO,MAAM,gBAAgB,6CAA8C,CAAC;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,eAAO,MAAM,gBAAgB,gDAAiD,CAAC;AAC/E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAgBvD;AAID,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAErD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,KAAK;IACpB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/domain/issue.js

@@ -0,0 +1,134 @@
+// ============================================================================
+// Canonical issue model — EPIC-0038 Phase 3
+// ============================================================================
+// The one definition of what an issue IS, independent of how it is stored.
+//
+// Before this file there were three, and they disagreed:
+//
+//   src/sentinelIssues.ts   'open' | 'in_progress' | 'done' | 'blocked'
+//   src/tools/sentinel.ts   'open' | 'in_progress' | 'blocked' | 'closed' | 'wontfix'
+//   src/store/types.ts      both unions merged, plus 'done'
+//
+// No two agree. `update_issue` could write `done`, which the reader's type did
+// not contain; `close_issue` wrote `closed`, which the updater's type did not
+// contain. Neither was a type error, because status crossed the boundary as a
+// bare string: buildIssueSummary read it with `typeof parsed.status === 'string'`
+// and the list filter compared it with `!==`. An out-of-vocabulary value was
+// therefore not rejected and not normalized — it was stored, returned, and
+// matched by no query.
+//
+// ISS-0026 is the proof. It sits on disk with `status: resolved`, a value no
+// writer in this codebase can produce and no filter can select. It is finished
+// work that is invisible to `list_issues(status: 'open')` and equally invisible
+// to `list_issues(status: 'closed')`.
+//
+// So the vocabulary is closed, and everything entering the model goes through
+// normalizeStatus(). Unknown values are mapped or flagged, never passed through.
+// ============================================================================
+import { randomBytes } from 'crypto';
+/**
+ * The complete status vocabulary. Closed set — if a value is not here, it is
+ * not a status, and normalizeStatus decides what to do about it.
+ */
+export const ISSUE_STATUSES = [
+    'open',
+    'in_progress',
+    'blocked',
+    'closed',
+    'wontfix',
+];
+/** Statuses meaning "no longer needs work". Everything else is live. */
+export const TERMINAL_STATUSES = new Set([
+    'closed',
+    'wontfix',
+]);
+export function isTerminal(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+export function isLive(status) {
+    return !isTerminal(status);
+}
+/**
+ * Values seen on disk that predate the closed vocabulary, and what they meant.
+ *
+ * `done` came from sentinelIssues.updateIssue, whose union had it. `resolved`
+ * came from a hand-edit or an older tool; ISS-0026 is the only instance. Both
+ * mean the work finished, so both map to `closed` — the mapping is recorded on
+ * the decoded record rather than applied silently, so a caller can tell the
+ * difference between a record that said `closed` and one that was interpreted.
+ */
+const STATUS_ALIASES = {
+    done: 'closed',
+    resolved: 'closed',
+    complete: 'closed',
+    completed: 'closed',
+    fixed: 'closed',
+    wont_fix: 'wontfix',
+    'wont-fix': 'wontfix',
+    duplicate: 'closed',
+    reopened: 'open',
+    todo: 'open',
+    new: 'open',
+    active: 'in_progress',
+    in_review: 'in_progress',
+};
+/**
+ * Map any on-disk status to the canonical vocabulary.
+ *
+ * Missing status defaults to `open` — that matches the previous reader's
+ * behaviour and is the safe direction: a record wrongly shown as open gets
+ * triaged, whereas one wrongly shown as closed disappears.
+ */
+export function normalizeStatus(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        // Absent is not the same as wrong: a record with no status is defaulted
+        // quietly, while a record whose status is an empty string or a number is
+        // flagged, because something wrote that on purpose.
+        if (raw === undefined || raw === null)
+            return { status: 'open' };
+        return { status: 'open', normalizedFrom: String(raw), unrecognized: true };
+    }
+    const key = raw.trim().toLowerCase();
+    if (ISSUE_STATUSES.includes(key)) {
+        const status = key;
+        return key === raw ? { status } : { status, normalizedFrom: raw };
+    }
+    const aliased = STATUS_ALIASES[key];
+    if (aliased)
+        return { status: aliased, normalizedFrom: raw };
+    return { status: 'open', normalizedFrom: raw, unrecognized: true };
+}
+export const ISSUE_SEVERITIES = ['low', 'med', 'high', 'critical'];
+export const ISSUE_PRIORITIES = ['low', 'medium', 'high', 'critical'];
+/**
+ * A stable identifier that survives everything the human-facing id does not.
+ *
+ * ISS-NNNN is a display name: it is derived from a directory scan, it is
+ * reassigned when duplicates are repaired (four were, in Phase 2), and it is
+ * allocated independently per checkout — which is exactly how the same issue
+ * came to exist as ISS-0112 on one volume and ISS-0115 on another with nothing
+ * in the data connecting them. `uid` is the identity; `id` is the label.
+ *
+ * UUIDv7 rather than v4 because it is time-ordered: records sort by creation
+ * without consulting a timestamp field, and a Postgres index on it stays local
+ * rather than scattering writes across the tree when this reaches HQ sync.
+ */
+export function newUid(now = Date.now()) {
+    const bytes = randomBytes(16);
+    // 48-bit big-endian millisecond timestamp.
+    bytes[0] = (now / 2 ** 40) & 0xff;
+    bytes[1] = (now / 2 ** 32) & 0xff;
+    bytes[2] = (now / 2 ** 24) & 0xff;
+    bytes[3] = (now / 2 ** 16) & 0xff;
+    bytes[4] = (now / 2 ** 8) & 0xff;
+    bytes[5] = now & 0xff;
+    bytes[6] = (bytes[6] & 0x0f) | 0x70; // version 7
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+const UID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function isUid(value) {
+    return typeof value === 'string' && UID_RE.test(value);
+}
+//# sourceMappingURL=issue.js.map

package/dist/domain/issue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.js","sourceRoot":"","sources":["../../src/domain/issue.ts"],"names":[],"mappings":"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"}

package/dist/domain/issueCodec.d.ts

@@ -0,0 +1,39 @@
+import { Issue } from './issue.js';
+export type IssueFormat = 'md' | 'yaml';
+export interface DecodedIssue {
+    issue: Issue;
+    format: IssueFormat;
+    /**
+     * Everything needed to reconstruct the file byte-for-byte apart from the
+     * fields the model owns. Callers should treat this as opaque and pass it back
+     * to encodeIssue unchanged.
+     */
+    raw: {
+        data: Record<string, unknown>;
+        body: string;
+    };
+    /**
+     * Non-fatal observations: a normalized status, an unrecognized value, a
+     * missing title. Surfaced so callers can report integrity problems rather
+     * than discovering them months later.
+     */
+    warnings: string[];
+}
+/**
+ * Split a bare-YAML record into its YAML head and any markdown tail at column 0.
+ *
+ * The column-0 anchor is load-bearing and must not gain `\s*`: headings indented
+ * inside a `description:` block scalar are body text, not a tail, and matching
+ * them would truncate the record at parse time. Phase 2 verified no record in
+ * the store relies on the difference, but nothing else pins it, so it is pinned
+ * by test here.
+ */
+export declare function splitBareYaml(content: string): {
+    head: string;
+    tail: string;
+};
+export declare function decodeIssue(filename: string, content: string): DecodedIssue;
+export declare function encodeIssue(decoded: DecodedIssue): string;
+/** Apply changes to a decoded record, keeping derived state consistent. */
+export declare function applyIssueChanges(decoded: DecodedIssue, changes: Partial<Issue>): DecodedIssue;
+//# sourceMappingURL=issueCodec.d.ts.map

package/dist/domain/issueCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issueCodec.d.ts","sourceRoot":"","sources":["../../src/domain/issueCodec.ts"],"names":[],"mappings":"AAyBA,OAAO,EACL,KAAK,EAKN,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,MAAM,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,GAAG,EAAE;QACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAK7E;AA8BD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CA4G3E;AA0CD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAuDzD;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,CAE9F"}