@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/core/item-raw.js

@@ -0,0 +1,98 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read-only access to stored metadata, including schema-invalid JSON (TASK-1069).
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { ItemMetadata } from '../schemas/index.js';
+import { itemPaths, listAttachments } from './item-paths.js';
+import { StaleItemError } from './item-store.js';
+import { describeZodIssues } from './item-validation.js';
+function sameStamp(left, right) {
+    return left.mtimeMs === right.mtimeMs && left.size === right.size;
+}
+function isMissing(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+/** Read only metadata, rejecting a change between the surrounding stat calls. */
+function readSnapshotText(devstepsDir, id, expected) {
+    const path = itemPaths(devstepsDir, id).metadata;
+    let before;
+    try {
+        const stat = statSync(path);
+        before = { mtimeMs: stat.mtimeMs, size: stat.size };
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        if (expected)
+            throw new StaleItemError(id);
+        throw new Error(`Item not found: ${id}`);
+    }
+    try {
+        const bytes = readFileSync(path);
+        const text = bytes.toString('utf-8');
+        const stat = statSync(path);
+        const stamp = { mtimeMs: stat.mtimeMs, size: stat.size };
+        if (!sameStamp(before, stamp) ||
+            (expected && (!sameStamp(expected.stamp, stamp) || expected.text !== text))) {
+            throw new StaleItemError(id);
+        }
+        if (!Buffer.from(text, 'utf-8').equals(bytes)) {
+            if (expected)
+                throw new StaleItemError(id);
+            throw new Error(`Item ${id} is not valid UTF-8 JSON; raw inspection requires valid UTF-8.`);
+        }
+        return { text, stamp };
+    }
+    catch (error) {
+        if (isMissing(error))
+            throw new StaleItemError(id);
+        throw error;
+    }
+}
+/**
+ * Load the stored JSON without interpreting or repairing its domain fields.
+ * Parser diagnostics are omitted because they can include metadata contents.
+ */
+export function readRawItemSnapshot(devstepsDir, id) {
+    const snapshot = readSnapshotText(devstepsDir, id);
+    let raw;
+    try {
+        raw = JSON.parse(snapshot.text);
+    }
+    catch {
+        throw new Error(`Item ${id} is not valid JSON; raw inspection requires valid JSON.`);
+    }
+    return { ...snapshot, raw };
+}
+/** Compare both the loaded source and stamp; a missing target is also stale. */
+export function assertRawItemSnapshot(devstepsDir, id, snapshot) {
+    readSnapshotText(devstepsDir, id, snapshot);
+}
+/**
+ * Inspect stored data without inventing work-item identity, defaults or lifecycle intent.
+ * Validation supplies issues only; its parsed/defaulted output is never returned.
+ */
+export function inspectRawItem(devstepsDir, id) {
+    const snapshot = readRawItemSnapshot(devstepsDir, id);
+    const parsed = ItemMetadata.safeParse(snapshot.raw);
+    let description = '';
+    try {
+        description = readFileSync(itemPaths(devstepsDir, id).description, 'utf-8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    return {
+        requested_id: id,
+        raw_metadata: snapshot.raw,
+        schema_valid: parsed.success,
+        schema_issues: parsed.success ? [] : describeZodIssues(parsed.error.issues, snapshot.raw),
+        description,
+        attachments: listAttachments(devstepsDir, id),
+    };
+}
+//# sourceMappingURL=item-raw.js.map

package/dist/core/item-raw.js.map

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

package/dist/core/item-store.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Item store — the in-memory, file-validated view of every item in a project.
+ *
+ * The item files are the only source of truth (STORY-426). This module keeps one
+ * store per `.devsteps` directory: an entry is served from memory while the item's
+ * JSON and Markdown files still carry the `mtime` and `size` recorded at the last
+ * read, and is re-read otherwise. Nothing on disk has to be kept in step with it,
+ * so an edit in the editor, a `git checkout`, or a write from another process is
+ * seen on the next call — and there is no tracked index left that could drift.
+ *
+ * The same stamps guard the writers (STORY-428): a write that expects the stamp it
+ * read is refused when another process wrote the file in between.
+ *
+ * Metadata and description are cached apart, each under its own stamp (TASK-914):
+ * `readAllItemMetadata` — the path `list` and everything built on it take — never
+ * opens an `<ID>.md`, and a description is read only when a caller asks for it.
+ *
+ * Measured on 1653 items: a cold read takes ~200 ms, the warm stat pass ~15 ms,
+ * and the whole store ~7.5 MB of heap.
+ */
+import { ItemMetadata, type ItemType } from '../schemas/index.js';
+/**
+ * Descriptions retained in memory per store. Metadata is always retained; a
+ * description beyond this budget is read from disk on each call instead.
+ */
+export declare const DESCRIPTION_RETENTION_LIMIT: number;
+/** What identifies one version of a file: enough to notice any write to it. */
+export interface FileStamp {
+    mtimeMs: number;
+    size: number;
+}
+/**
+ * An item as the store holds it. `readAllItems` hands out the store's own objects
+ * for speed: project them, never mutate them. `readItem` returns a copy.
+ */
+export interface StoredItemMetadata {
+    readonly metadata: ItemMetadata;
+    /** Stamp of the metadata file as read — pass it to `writeItemMetadata` to guard the write. */
+    readonly stamp: FileStamp;
+}
+export interface StoredItem extends StoredItemMetadata {
+    readonly description: string;
+    /**
+     * Stamp of the `<ID>.md` as read; null when the item has no Markdown file. Pass it with
+     * `stamp` to `writeItemDescription` to guard the write against a change in between.
+     */
+    readonly descriptionStamp: FileStamp | null;
+}
+/** The stamps a guarded description write expects to find still on disk. */
+export interface ExpectedItemStamps {
+    metadata: FileStamp;
+    description: FileStamp | null;
+}
+export interface ReadAllItemsResult<T extends StoredItemMetadata = StoredItem> {
+    items: T[];
+    /** IDs whose file exists but could not be parsed (STORY-391) — never silently dropped. */
+    unreadable: string[];
+}
+export interface ItemStoreStats {
+    entries: number;
+    retainedDescriptionBytes: number;
+}
+/** Thrown when a guarded write finds the file changed since it was read. */
+export declare class StaleItemError extends Error {
+    readonly itemId: string;
+    readonly code = "STALE_ITEM";
+    constructor(itemId: string);
+}
+/** Test hook: lower the description budget without touching the constant. */
+export declare function configureItemStore(options: {
+    descriptionRetentionBytes?: number;
+}): void;
+/** Every item ID on disk, discovered from the item folders — no index involved. */
+export declare function listItemIds(devstepsDir: string, type?: ItemType): string[];
+/**
+ * Read one item. Throws for an unknown ID, a missing file, or a schema violation —
+ * the strictness `getItem()` has always had. The metadata is a copy the caller may
+ * patch and write back through `writeItemMetadata`.
+ */
+export declare function readItem(devstepsDir: string, id: string): StoredItem;
+/** `readItem` without the description: never opens the `<ID>.md`. Same errors, a copy too. */
+export declare function readItemMetadata(devstepsDir: string, id: string): StoredItemMetadata;
+/**
+ * Read every item, or every item of one type. An entry the store still holds for
+ * an ID that is no longer on disk is dropped on the way.
+ *
+ * A folder without its `<ID>.json` is skipped, not reported: a parallel `add` has
+ * claimed it and not written yet (STORY-428). `doctor` names one that stays empty.
+ */
+export declare function readAllItems(devstepsDir: string, type?: ItemType): ReadAllItemsResult;
+/**
+ * `readAllItems` without descriptions: reads and validates only the `<ID>.json`
+ * files, so it never opens an `<ID>.md`. Same discovery, skipping, and reporting.
+ */
+export declare function readAllItemMetadata(devstepsDir: string, type?: ItemType): ReadAllItemsResult<StoredItemMetadata>;
+/** Throw `StaleItemError` when the item's metadata file no longer carries `expected`. */
+export declare function assertItemUnchanged(devstepsDir: string, id: string, expected: FileStamp): void;
+/** Refuses with `StaleItemError` when the metadata or the `<ID>.md` changed since `expected`. */
+export declare function assertItemStamps(devstepsDir: string, id: string, expected: ExpectedItemStamps): void;
+/**
+ * Write an item's metadata atomically (STORY-428). With `expected`, the write is
+ * refused when the file changed since that stamp was read — the caller re-reads
+ * and retries instead of overwriting another process's change.
+ */
+export declare function writeItemMetadata(devstepsDir: string, metadata: ItemMetadata, expected?: FileStamp): void;
+/**
+ * Write an item's master document atomically. With `expected`, both the metadata and the
+ * `<ID>.md` stamp are checked immediately before the temp-file rename and the write is
+ * refused with `StaleItemError` when either changed; without it the write is blind.
+ */
+export declare function writeItemDescription(devstepsDir: string, id: string, description: string, expected?: ExpectedItemStamps): void;
+/** Drop one entry; writers call this after touching the item's files. */
+export declare function invalidateItem(devstepsDir: string, id: string): void;
+/** Drop a whole store — after a migration, or when a test wants a cold start. */
+export declare function invalidateStore(devstepsDir: string): void;
+export declare function itemStoreStats(devstepsDir: string): ItemStoreStats;
+//# sourceMappingURL=item-store.d.ts.map

package/dist/core/item-store.d.ts.map

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

package/dist/core/item-store.js

@@ -0,0 +1,269 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Item store — the in-memory, file-validated view of every item in a project.
+ *
+ * The item files are the only source of truth (STORY-426). This module keeps one
+ * store per `.devsteps` directory: an entry is served from memory while the item's
+ * JSON and Markdown files still carry the `mtime` and `size` recorded at the last
+ * read, and is re-read otherwise. Nothing on disk has to be kept in step with it,
+ * so an edit in the editor, a `git checkout`, or a write from another process is
+ * seen on the next call — and there is no tracked index left that could drift.
+ *
+ * The same stamps guard the writers (STORY-428): a write that expects the stamp it
+ * read is refused when another process wrote the file in between.
+ *
+ * Metadata and description are cached apart, each under its own stamp (TASK-914):
+ * `readAllItemMetadata` — the path `list` and everything built on it take — never
+ * opens an `<ID>.md`, and a description is read only when a caller asks for it.
+ *
+ * Measured on 1653 items: a cold read takes ~200 ms, the warm stat pass ~15 ms,
+ * and the whole store ~7.5 MB of heap.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { ItemMetadata } from '../schemas/index.js';
+import { writeFileAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
+import { TYPE_TO_DIRECTORY } from '../utils/index.js';
+import { itemPaths, listItemFolders, typeDirectory } from './item-paths.js';
+/**
+ * Descriptions retained in memory per store. Metadata is always retained; a
+ * description beyond this budget is read from disk on each call instead.
+ */
+export const DESCRIPTION_RETENTION_LIMIT = 64 * 1024 * 1024;
+/** Thrown when a guarded write finds the file changed since it was read. */
+export class StaleItemError extends Error {
+    itemId;
+    code = 'STALE_ITEM';
+    constructor(itemId) {
+        super(`${itemId} changed on disk since it was read — re-read the item and retry`);
+        this.itemId = itemId;
+        this.name = 'StaleItemError';
+    }
+}
+const stores = new Map();
+let descriptionRetentionLimit = DESCRIPTION_RETENTION_LIMIT;
+/** Test hook: lower the description budget without touching the constant. */
+export function configureItemStore(options) {
+    descriptionRetentionLimit = options.descriptionRetentionBytes ?? DESCRIPTION_RETENTION_LIMIT;
+}
+function storeFor(devstepsDir) {
+    let store = stores.get(devstepsDir);
+    if (!store) {
+        store = { entries: new Map(), retainedDescriptionBytes: 0 };
+        stores.set(devstepsDir, store);
+    }
+    return store;
+}
+function stampOf(filePath) {
+    try {
+        const stat = statSync(filePath);
+        return { mtimeMs: stat.mtimeMs, size: stat.size };
+    }
+    catch {
+        return null;
+    }
+}
+function sameStamp(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.mtimeMs === b.mtimeMs && a.size === b.size;
+}
+/** Give back the retention budget a cached description holds. */
+function release(store, description) {
+    if (description && description.text !== null) {
+        store.retainedDescriptionBytes -= description.stamp?.size ?? 0;
+    }
+}
+function forget(store, id) {
+    const entry = store.entries.get(id);
+    if (!entry)
+        return;
+    release(store, entry.description);
+    store.entries.delete(id);
+}
+/** Every item ID on disk, discovered from the item folders — no index involved. */
+export function listItemIds(devstepsDir, type) {
+    const types = type ? [type] : Object.keys(TYPE_TO_DIRECTORY);
+    const ids = [];
+    for (const itemType of types) {
+        ids.push(...listItemFolders(typeDirectory(devstepsDir, itemType), itemType));
+    }
+    return ids;
+}
+/** The item's store entry with current metadata; null when its metadata file does not exist. */
+function readEntry(devstepsDir, id) {
+    const store = storeFor(devstepsDir);
+    const metadataStamp = stampOf(itemPaths(devstepsDir, id).metadata);
+    if (!metadataStamp) {
+        forget(store, id);
+        return null;
+    }
+    const cached = store.entries.get(id);
+    if (cached && sameStamp(cached.metadataStamp, metadataStamp))
+        return cached;
+    const metadata = ItemMetadata.parse(JSON.parse(readFileSync(itemPaths(devstepsDir, id).metadata, 'utf-8')));
+    const entry = { metadata, metadataStamp, description: cached?.description };
+    store.entries.set(id, entry);
+    return entry;
+}
+/** The entry's description, re-read when its `<ID>.md` changed since it was cached. */
+function readDescription(devstepsDir, id, entry) {
+    const file = itemPaths(devstepsDir, id).description;
+    const stamp = stampOf(file);
+    const cached = entry.description;
+    if (cached && sameStamp(cached.stamp, stamp)) {
+        return { text: cached.text ?? readFileSync(file, 'utf-8'), stamp };
+    }
+    const store = storeFor(devstepsDir);
+    const text = stamp ? readFileSync(file, 'utf-8') : '';
+    release(store, cached);
+    const size = stamp?.size ?? 0;
+    const retain = store.retainedDescriptionBytes + size <= descriptionRetentionLimit;
+    entry.description = { text: retain ? text : null, stamp };
+    if (retain)
+        store.retainedDescriptionBytes += size;
+    return { text, stamp };
+}
+/** Read one item through the store; null when its metadata file does not exist. */
+function readStored(devstepsDir, id) {
+    const entry = readEntry(devstepsDir, id);
+    if (!entry)
+        return null;
+    const description = readDescription(devstepsDir, id, entry);
+    return {
+        metadata: entry.metadata,
+        description: description.text,
+        descriptionStamp: description.stamp,
+        stamp: entry.metadataStamp,
+    };
+}
+/**
+ * Read one item. Throws for an unknown ID, a missing file, or a schema violation —
+ * the strictness `getItem()` has always had. The metadata is a copy the caller may
+ * patch and write back through `writeItemMetadata`.
+ */
+export function readItem(devstepsDir, id) {
+    const stored = readStored(devstepsDir, id);
+    if (!stored) {
+        throw new Error(`Item not found: ${id}`);
+    }
+    return {
+        metadata: structuredClone(stored.metadata),
+        description: stored.description,
+        descriptionStamp: stored.descriptionStamp,
+        stamp: stored.stamp,
+    };
+}
+/** Every current item ID of the store's scope; drops entries whose folder is gone. */
+function currentIds(devstepsDir, type) {
+    const ids = listItemIds(devstepsDir, type);
+    if (!type) {
+        const store = storeFor(devstepsDir);
+        const onDisk = new Set(ids);
+        for (const id of [...store.entries.keys()]) {
+            if (!onDisk.has(id))
+                forget(store, id);
+        }
+    }
+    return ids;
+}
+function readAll(ids, read) {
+    const items = [];
+    const unreadable = [];
+    for (const id of ids) {
+        try {
+            const stored = read(id);
+            if (stored)
+                items.push(stored);
+        }
+        catch {
+            unreadable.push(id);
+        }
+    }
+    return { items, unreadable };
+}
+/** `readItem` without the description: never opens the `<ID>.md`. Same errors, a copy too. */
+export function readItemMetadata(devstepsDir, id) {
+    const entry = readEntry(devstepsDir, id);
+    if (!entry) {
+        throw new Error(`Item not found: ${id}`);
+    }
+    return { metadata: structuredClone(entry.metadata), stamp: entry.metadataStamp };
+}
+/**
+ * Read every item, or every item of one type. An entry the store still holds for
+ * an ID that is no longer on disk is dropped on the way.
+ *
+ * A folder without its `<ID>.json` is skipped, not reported: a parallel `add` has
+ * claimed it and not written yet (STORY-428). `doctor` names one that stays empty.
+ */
+export function readAllItems(devstepsDir, type) {
+    return readAll(currentIds(devstepsDir, type), (id) => readStored(devstepsDir, id));
+}
+/**
+ * `readAllItems` without descriptions: reads and validates only the `<ID>.json`
+ * files, so it never opens an `<ID>.md`. Same discovery, skipping, and reporting.
+ */
+export function readAllItemMetadata(devstepsDir, type) {
+    return readAll(currentIds(devstepsDir, type), (id) => {
+        const entry = readEntry(devstepsDir, id);
+        return entry && { metadata: entry.metadata, stamp: entry.metadataStamp };
+    });
+}
+/** Throw `StaleItemError` when the item's metadata file no longer carries `expected`. */
+export function assertItemUnchanged(devstepsDir, id, expected) {
+    if (!sameStamp(stampOf(itemPaths(devstepsDir, id).metadata), expected)) {
+        throw new StaleItemError(id);
+    }
+}
+/** Refuses with `StaleItemError` when the metadata or the `<ID>.md` changed since `expected`. */
+export function assertItemStamps(devstepsDir, id, expected) {
+    assertItemUnchanged(devstepsDir, id, expected.metadata);
+    if (!sameStamp(stampOf(itemPaths(devstepsDir, id).description), expected.description)) {
+        throw new StaleItemError(id);
+    }
+}
+/**
+ * Write an item's metadata atomically (STORY-428). With `expected`, the write is
+ * refused when the file changed since that stamp was read — the caller re-reads
+ * and retries instead of overwriting another process's change.
+ */
+export function writeItemMetadata(devstepsDir, metadata, expected) {
+    if (expected)
+        assertItemUnchanged(devstepsDir, metadata.id, expected);
+    writeJsonAtomic(itemPaths(devstepsDir, metadata.id).metadata, metadata);
+    invalidateItem(devstepsDir, metadata.id);
+}
+/**
+ * Write an item's master document atomically. With `expected`, both the metadata and the
+ * `<ID>.md` stamp are checked immediately before the temp-file rename and the write is
+ * refused with `StaleItemError` when either changed; without it the write is blind.
+ */
+export function writeItemDescription(devstepsDir, id, description, expected) {
+    const file = itemPaths(devstepsDir, id).description;
+    try {
+        writeFileAtomic(file, description, expected ? { beforeRename: () => assertItemStamps(devstepsDir, id, expected) } : undefined);
+    }
+    finally {
+        invalidateItem(devstepsDir, id);
+    }
+}
+/** Drop one entry; writers call this after touching the item's files. */
+export function invalidateItem(devstepsDir, id) {
+    const store = stores.get(devstepsDir);
+    if (store)
+        forget(store, id);
+}
+/** Drop a whole store — after a migration, or when a test wants a cold start. */
+export function invalidateStore(devstepsDir) {
+    stores.delete(devstepsDir);
+}
+export function itemStoreStats(devstepsDir) {
+    const store = stores.get(devstepsDir);
+    return {
+        entries: store?.entries.size ?? 0,
+        retainedDescriptionBytes: store?.retainedDescriptionBytes ?? 0,
+    };
+}
+//# sourceMappingURL=item-store.js.map

package/dist/core/item-store.js.map

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

package/dist/core/item-type-availability.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Creation respects the project's work-item vocabulary before any write (BUG-252).
+ */
+import { type DevStepsConfig } from '../schemas/index.js';
+export declare function assertItemTypeOffered(config: DevStepsConfig, type: unknown): void;
+//# sourceMappingURL=item-type-availability.d.ts.map

package/dist/core/item-type-availability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-type-availability.d.ts","sourceRoot":"","sources":["../../src/core/item-type-availability.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,qBAAqB,CAAC;AAIjF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAmBjF"}

package/dist/core/item-type-availability.js

@@ -0,0 +1,29 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Creation respects the project's work-item vocabulary before any write (BUG-252).
+ */
+import { ItemType, Methodology } from '../schemas/index.js';
+import { getMethodologyConfig } from '../utils/index.js';
+import { CROSS_CUTTING_TYPES } from './decision-question.js';
+export function assertItemTypeOffered(config, type) {
+    const methodology = config.settings?.methodology ?? 'hybrid';
+    const parsed = Methodology.safeParse(methodology);
+    if (!parsed.success)
+        throw new Error(`Unknown project methodology: ${methodology}`);
+    const vocabulary = getMethodologyConfig(parsed.data).item_types;
+    const declared = config.settings?.item_types;
+    if (declared !== undefined && !Array.isArray(declared)) {
+        throw new Error('Project settings.item_types must be an array of item types.');
+    }
+    // Decisions, questions and documents predate their presence in some project configs.
+    const configured = new Set([...(declared ?? vocabulary), ...CROSS_CUTTING_TYPES]);
+    const allowed = vocabulary.filter((candidate) => configured.has(candidate));
+    const item = ItemType.safeParse(type);
+    if (!item.success || !allowed.includes(item.data)) {
+        throw new Error(`Item type ${JSON.stringify(type)} is not offered by methodology ${methodology}. ` +
+            `Allowed types: ${allowed.join(', ')}.`);
+    }
+}
+//# sourceMappingURL=item-type-availability.js.map

package/dist/core/item-type-availability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-type-availability.js","sourceRoot":"","sources":["../../src/core/item-type-availability.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAuB,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,UAAU,qBAAqB,CAAC,MAAsB,EAAE,IAAa;IACzE,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,EAAE,WAAW,IAAI,QAAQ,CAAC;IAC7D,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,WAAW,EAAE,CAAC,CAAC;IACpF,MAAM,UAAU,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC;IAChE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC7C,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IACD,qFAAqF;IACrF,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,IAAI,UAAU,CAAC,EAAE,GAAG,mBAAmB,CAAC,CAAC,CAAC;IAClF,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IAC5E,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,kCAAkC,WAAW,IAAI;YAChF,kBAAkB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/item-validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Write-path guard for item metadata (BUG-115 / STORY-382)
+ * `getItem()` parses every item against `ItemMetadata` and throws on any violation.
+ * Until this guard existed, no write path checked the same contract, so a single
+ * `add` could persist an item that could never be read, updated, linked, archived
+ * or purged again. Every writer runs this before it touches the filesystem.
+ */
+import type { ZodError } from 'zod';
+import { ItemMetadata } from '../schemas/index.js';
+type ItemIssue = ZodError['issues'][number];
+/** Field name → where the offending value came from, e.g. a config default. */
+export type FieldOrigins = Readonly<Record<string, string>>;
+/**
+ * Raised when metadata would be persisted in a shape the read path rejects.
+ * Carries the readable per-field lines so adapters can present them as they like.
+ */
+export declare class ItemValidationError extends Error {
+    readonly issues: readonly string[];
+    constructor(message: string, issues: readonly string[]);
+}
+/** One readable line per Zod issue, resolving each offending value from `input`. */
+export declare function describeZodIssues(issues: readonly ItemIssue[], input: unknown, origins?: FieldOrigins): string[];
+/**
+ * Validate metadata about to be written and return the parsed value.
+ * Throws `ItemValidationError` with one readable line per violation instead of
+ * the raw Zod JSON, which is what reached the caller before this guard existed.
+ */
+export declare function assertValidItemMetadata(metadata: unknown, options?: {
+    readonly origins?: FieldOrigins;
+}): ItemMetadata;
+export {};
+//# sourceMappingURL=item-validation.d.ts.map

package/dist/core/item-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-validation.d.ts","sourceRoot":"","sources":["../../src/core/item-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,KAAK,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE5D;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAIrD;CACF;AAgDD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,YAAiB,GACzB,MAAM,EAAE,CAEV;AAuBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;CAAO,GAChD,YAAY,CAYd"}