@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.1

package/dist/ideas/format.js

@@ -0,0 +1,194 @@
+/**
+ * Idea file format: Markdown with a small frontmatter block.
+ *
+ *   ---
+ *   type: idea
+ *   id: "IDEA-001"
+ *   title: "..."            (JSON string: any character survives a round trip)
+ *   status: inbox
+ *   createdAt: "2026-..."
+ *   context: "..."          (optional)
+ *   tags: ["a", "b"]        (optional)
+ *   ---
+ *
+ *   ## Description
+ *
+ *   <description, verbatim>
+ *
+ * Strings are written as JSON strings, which are also valid YAML double-quoted
+ * scalars, so ERG/Scriptorium read the file too. The reader additionally accepts
+ * a plain unquoted value, because a person edits these files by hand.
+ * The description is the body: no escaping, no trimming.
+ */
+import { IDEA_LIMITS, IDEA_STATUSES, IdeaError } from './types.js';
+const BODY_HEADING = '\n## Description\n\n';
+const ID_RE = /^IDEA-(\d{3,9})$/;
+const FILE_RE = /^(IDEA-\d{3,9})\.md$/;
+// C0 controls, DEL and C1 controls (a title is shown in a terminal).
+// eslint-disable-next-line no-control-regex
+const CONTROL_RE = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+export function isIdeaId(value) {
+    return ID_RE.test(value);
+}
+export function ideaNumber(id) {
+    const m = ID_RE.exec(id);
+    if (!m)
+        throw new IdeaError('IDEA_INVALID_ID', `"${id}" is not an idea id (expected IDEA-NNN).`);
+    return Number(m[1]);
+}
+export function formatIdeaId(n) {
+    return `IDEA-${String(n).padStart(3, '0')}`;
+}
+/** `IDEA-007.md` -> `IDEA-007`; anything else (temp files, other documents) -> null. */
+export function ideaIdFromFileName(name) {
+    const m = FILE_RE.exec(name);
+    return m ? m[1] : null;
+}
+export function ideaFileName(id) {
+    ideaNumber(id);
+    return `${id}.md`;
+}
+function invalid(message) {
+    return new IdeaError('IDEA_INVALID_INPUT', message);
+}
+const LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** An unpaired surrogate would be rewritten to U+FFFD by UTF-8 encoding: not lossless. */
+function wellFormed(s) {
+    return !LONE_SURROGATE_RE.test(s);
+}
+/** Validates user input; returns it unchanged (content is never trimmed or rewritten). */
+export function validateNewIdea(input) {
+    const { title, description, context } = input;
+    if (typeof title !== 'string' || title.trim() === '')
+        throw invalid('title must not be empty.');
+    if (typeof description !== 'string' || description.trim() === '')
+        throw invalid('description must not be empty.');
+    if (CONTROL_RE.test(title))
+        throw invalid('title must be a single line without control characters.');
+    if (title.length > IDEA_LIMITS.title)
+        throw invalid(`title is too long (${title.length} > ${IDEA_LIMITS.title} characters).`);
+    if (description.length > IDEA_LIMITS.description) {
+        throw invalid(`description is too long (${description.length} > ${IDEA_LIMITS.description} characters).`);
+    }
+    if (context !== undefined) {
+        if (typeof context !== 'string' || context.trim() === '')
+            throw invalid('context, when given, must not be empty.');
+        if (context.length > IDEA_LIMITS.context) {
+            throw invalid(`context is too long (${context.length} > ${IDEA_LIMITS.context} characters).`);
+        }
+    }
+    for (const [name, v] of [['title', title], ['description', description], ['context', context]]) {
+        if (v !== undefined && !wellFormed(v))
+            throw invalid(`${name} contains an unpaired surrogate and cannot be stored losslessly.`);
+    }
+    return input;
+}
+export function serializeIdea(idea) {
+    const lines = [
+        '---',
+        'type: idea',
+        `id: ${JSON.stringify(idea.id)}`,
+        `title: ${JSON.stringify(idea.title)}`,
+        `status: ${idea.status}`,
+        `createdAt: ${JSON.stringify(idea.createdAt)}`,
+    ];
+    if (idea.context !== undefined)
+        lines.push(`context: ${JSON.stringify(idea.context)}`);
+    if (idea.tags !== undefined && idea.tags.length > 0)
+        lines.push(`tags: ${JSON.stringify(idea.tags)}`);
+    lines.push('---');
+    return `${lines.join('\n')}\n${BODY_HEADING}${idea.description}\n`;
+}
+function corrupt(id, reason) {
+    return new IdeaError('IDEA_CORRUPT', `${id}: ${reason}`);
+}
+function scalar(raw) {
+    const v = raw.trim();
+    if (v.startsWith('"')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(v);
+        }
+        catch {
+            throw new Error('malformed quoted string');
+        }
+        if (typeof parsed !== 'string')
+            throw new Error('malformed quoted string');
+        return parsed;
+    }
+    return v;
+}
+/**
+ * Parse an idea file. `expectedId` is the id implied by the file name; a
+ * mismatch with the `id:` field is corruption, never silently "fixed".
+ */
+export function parseIdea(expectedId, text) {
+    const normalized = text.startsWith('') ? text.slice(1) : text;
+    if (!normalized.startsWith('---\n'))
+        throw corrupt(expectedId, 'missing frontmatter.');
+    const end = normalized.indexOf('\n---\n', 3);
+    if (end === -1)
+        throw corrupt(expectedId, 'frontmatter is not terminated.');
+    const fm = Object.create(null);
+    for (const line of normalized.slice(4, end).split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const colon = line.indexOf(':');
+        if (colon <= 0)
+            throw corrupt(expectedId, `unreadable frontmatter line ${JSON.stringify(line.slice(0, 60))}.`);
+        const key = line.slice(0, colon).trim();
+        if (key in fm)
+            throw corrupt(expectedId, `duplicate frontmatter key "${key}".`);
+        fm[key] = line.slice(colon + 1);
+    }
+    const field = (key) => {
+        if (!(key in fm))
+            throw corrupt(expectedId, `missing "${key}".`);
+        try {
+            return scalar(fm[key]);
+        }
+        catch (err) {
+            throw corrupt(expectedId, `"${key}": ${err.message}.`);
+        }
+    };
+    if ('type' in fm && field('type') !== 'idea')
+        throw corrupt(expectedId, `type is "${field('type')}", expected "idea".`);
+    const id = field('id');
+    if (id !== expectedId)
+        throw corrupt(expectedId, `file name says ${expectedId} but the id field says ${JSON.stringify(id)}.`);
+    const title = field('title');
+    if (title.trim() === '')
+        throw corrupt(expectedId, 'title is empty.');
+    const status = field('status');
+    if (!IDEA_STATUSES.includes(status)) {
+        throw corrupt(expectedId, `unknown status ${JSON.stringify(status)} (expected ${IDEA_STATUSES.join(' | ')}).`);
+    }
+    const createdAt = field('createdAt');
+    if (Number.isNaN(Date.parse(createdAt)))
+        throw corrupt(expectedId, `createdAt ${JSON.stringify(createdAt)} is not a date.`);
+    const body = normalized.slice(end + 5); // right after the closing "---\n"
+    if (!body.startsWith(BODY_HEADING))
+        throw corrupt(expectedId, 'missing "## Description" section.');
+    let description = body.slice(BODY_HEADING.length);
+    if (description.endsWith('\n'))
+        description = description.slice(0, -1);
+    if (description.trim() === '')
+        throw corrupt(expectedId, 'description is empty.');
+    const idea = { id, title, description, createdAt, status: status };
+    if ('context' in fm)
+        idea.context = field('context');
+    if ('tags' in fm) {
+        let tags;
+        try {
+            tags = JSON.parse(fm.tags);
+        }
+        catch {
+            throw corrupt(expectedId, '"tags" is not a JSON array of strings.');
+        }
+        if (!Array.isArray(tags) || !tags.every((t) => typeof t === 'string')) {
+            throw corrupt(expectedId, '"tags" is not a JSON array of strings.');
+        }
+        idea.tags = tags;
+    }
+    return idea;
+}

package/dist/ideas/index.d.ts

@@ -0,0 +1,6 @@
+export { IDEA_STATUSES, IDEA_LIMITS, IdeaError } from './types.js';
+export type { Idea, IdeaStatus, IdeaEntry, NewIdea, IdeaErrorCode } from './types.js';
+export { ideaStore, addIdea, getIdea, listIdeas } from './store.js';
+export type { IdeaStore, AddIdeaOptions, AddIdeaResult } from './store.js';
+export { serializeIdea, parseIdea, isIdeaId } from './format.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ideas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ideas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACnE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/ideas/index.js

@@ -0,0 +1,3 @@
+export { IDEA_STATUSES, IDEA_LIMITS, IdeaError } from './types.js';
+export { ideaStore, addIdea, getIdea, listIdeas } from './store.js';
+export { serializeIdea, parseIdea, isIdeaId } from './format.js';

package/dist/ideas/store.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Idea store (IDEA-001A): one Markdown file per idea in `<monolithRoot>/memory/long-term/ideas/`.
+ *
+ * - Writes go through the safe-write primitive in `src/root/` (PROJECT scope:
+ *   a symlink anywhere below the project root is refused; the file is created
+ *   exclusively via `link()`, so an existing file is never overwritten).
+ * - Reads go through the unified bounded reader (`readBoundedFile`).
+ * - Ids are allocated by exclusive creation, not by trusting a counter: the
+ *   next number is only a candidate, and a lost race (`WRITE_TARGET_EXISTS`)
+ *   re-scans and tries again. Two processes can therefore never publish the same id.
+ *
+ * - Ids are permanently reserved (IDEA-001D): before an idea file is written, an
+ *   empty-ish marker `ideas/.ids/IDEA-NNN` is created exclusively. The next id is
+ *   `max(idea files, markers) + 1`, so deleting an idea file never frees its id.
+ *   A crash between marker and file leaves an orphaned marker: that id is simply
+ *   burned (a gap), never reused. Existing ideas without a marker (created before
+ *   IDEA-001D) get one on the next `add`. No shared counter, no lock.
+ *
+ * Not defended: a local actor swapping directories concurrently (SEC-001B.3,
+ * TM-C unsupported). Deleting the `.ids` directory by hand forgets the
+ * reservations of ideas that no longer have a file.
+ */
+import { type WriteBoundary, type WriteWarning } from '../root/index.js';
+import type { FsOps } from '../root/index.js';
+import { type Idea, type IdeaEntry, type NewIdea } from './types.js';
+export interface IdeaStore {
+    projectRoot: string;
+    rootAbs: string;
+    dirAbs: string;
+    boundary: WriteBoundary;
+}
+/** Resolve (and contain) the ideas directory of the instance rooted at `targetDir`. */
+export declare function ideaStore(targetDir: string): IdeaStore;
+export interface AddIdeaOptions {
+    /** Clock seam for tests. */
+    now?: () => Date;
+    /** Fault-injection seam for tests (forwarded to the safe-write primitive). */
+    ops?: Partial<FsOps>;
+    /** Receives post-publication findings (the idea IS saved when these fire). */
+    onWarning?: (w: WriteWarning) => void;
+}
+export interface AddIdeaResult {
+    idea: Idea;
+    path: string;
+}
+export declare function addIdea(store: IdeaStore, input: NewIdea, opts?: AddIdeaOptions): AddIdeaResult;
+/** Read one idea. Throws IDEA_INVALID_ID / IDEA_NOT_FOUND / IDEA_UNSAFE_PATH / IDEA_CORRUPT. Never writes. */
+export declare function getIdea(store: IdeaStore, id: string): Idea;
+/**
+ * All ideas, ordered by number. A file that cannot be read as an idea appears as
+ * a non-ok entry instead of aborting the listing. A symlinked ideas directory
+ * is refused as a whole. Never writes.
+ */
+export declare function listIdeas(store: IdeaStore): IdeaEntry[];
+//# sourceMappingURL=store.d.ts.map

package/dist/ideas/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ideas/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAWL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAA0B,KAAK,IAAI,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAQ7F,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAetD;AAED,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACrB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AA+DD,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CA4ElG;AAsBD,8GAA8G;AAC9G,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,CAiBvD"}

package/dist/ideas/store.js

@@ -0,0 +1,262 @@
+/**
+ * Idea store (IDEA-001A): one Markdown file per idea in `<monolithRoot>/memory/long-term/ideas/`.
+ *
+ * - Writes go through the safe-write primitive in `src/root/` (PROJECT scope:
+ *   a symlink anywhere below the project root is refused; the file is created
+ *   exclusively via `link()`, so an existing file is never overwritten).
+ * - Reads go through the unified bounded reader (`readBoundedFile`).
+ * - Ids are allocated by exclusive creation, not by trusting a counter: the
+ *   next number is only a candidate, and a lost race (`WRITE_TARGET_EXISTS`)
+ *   re-scans and tries again. Two processes can therefore never publish the same id.
+ *
+ * - Ids are permanently reserved (IDEA-001D): before an idea file is written, an
+ *   empty-ish marker `ideas/.ids/IDEA-NNN` is created exclusively. The next id is
+ *   `max(idea files, markers) + 1`, so deleting an idea file never frees its id.
+ *   A crash between marker and file leaves an orphaned marker: that id is simply
+ *   burned (a gap), never reused. Existing ideas without a marker (created before
+ *   IDEA-001D) get one on the next `add`. No shared counter, no lock.
+ *
+ * Not defended: a local actor swapping directories concurrently (SEC-001B.3,
+ * TM-C unsupported). Deleting the `.ids` directory by hand forgets the
+ * reservations of ideas that no longer have a file.
+ */
+import { lstatSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { RootContainmentError, SafeWriteError, assertContainedFile, createFile, openParent, projectBoundary, readBoundedFile, resolveMonolithRoot, } from '../root/index.js';
+import { formatIdeaId, ideaFileName, ideaIdFromFileName, ideaNumber, isIdeaId, parseIdea, serializeIdea, validateNewIdea } from './format.js';
+import { IDEA_LIMITS, IdeaError } from './types.js';
+const IDEAS_REL = 'memory/long-term/ideas';
+const IDS_DIR = '.ids';
+const MARKER_RE = /^(IDEA-\d{3,9})$/;
+const MAX_IDEA_NUMBER = 999_999_999;
+const MAX_ALLOCATION_ATTEMPTS = 64;
+/** Resolve (and contain) the ideas directory of the instance rooted at `targetDir`. */
+export function ideaStore(targetDir) {
+    let root;
+    try {
+        root = resolveMonolithRoot(targetDir);
+        assertContainedFile(root, IDEAS_REL);
+    }
+    catch (err) {
+        if (err instanceof RootContainmentError)
+            throw new IdeaError('IDEA_UNSAFE_PATH', err.message, { cause: err });
+        throw err;
+    }
+    return {
+        projectRoot: root.projectRoot,
+        rootAbs: root.rootAbs,
+        dirAbs: join(root.rootAbs, IDEAS_REL),
+        boundary: projectBoundary(root.projectRoot),
+    };
+}
+function unsafe(err) {
+    return new IdeaError('IDEA_UNSAFE_PATH', err.message, { cause: err });
+}
+/** Ids of the idea files in the ideas directory, ordered by number. Missing directory -> empty. */
+function scanIds(store) {
+    let names;
+    try {
+        names = readdirSync(store.dirAbs);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const ids = [];
+    for (const name of names) {
+        const id = ideaIdFromFileName(name);
+        if (id !== null)
+            ids.push(id);
+    }
+    return ids.sort((a, b) => ideaNumber(a) - ideaNumber(b) || (a < b ? -1 : a > b ? 1 : 0));
+}
+/** Ids with a reservation marker in `ideas/.ids/`. Missing directory -> empty. Names that are not `IDEA-NNN` are ignored. */
+function scanReservedIds(store) {
+    let names;
+    try {
+        names = readdirSync(join(store.dirAbs, IDS_DIR));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const ids = [];
+    for (const name of names) {
+        const m = MARKER_RE.exec(name);
+        if (m !== null)
+            ids.push(m[1]);
+    }
+    return ids;
+}
+/** Highest number that is in use or reserved (0 when none). */
+function highestNumber(ids) {
+    return ids.reduce((max, id) => Math.max(max, ideaNumber(id)), 0);
+}
+/** Create the marker for `id`. Returns false when it already exists (never overwritten). */
+function reserveId(markers, id, createdAt, opts) {
+    try {
+        const outcome = createFile(markers, id, `reserved ${createdAt}\n`, {
+            mode: 0o666,
+            exactMode: false,
+            durability: 'full',
+            maxBytes: 256,
+            ops: opts.ops,
+        });
+        for (const w of outcome.warnings)
+            opts.onWarning?.(w);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof SafeWriteError && err.code === 'WRITE_TARGET_EXISTS')
+            return false;
+        throw err;
+    }
+}
+export function addIdea(store, input, opts = {}) {
+    validateNewIdea(input);
+    // `add` only creates `memory/long-term/ideas` inside an existing instance; it never invents `.monolith/`.
+    let rootStat;
+    try {
+        rootStat = lstatSync(store.rootAbs);
+    }
+    catch {
+        rootStat = null;
+    }
+    if (rootStat === null || !rootStat.isDirectory()) {
+        throw new IdeaError('IDEA_NOT_INITIALIZED', `"${store.rootAbs}" is not a MONOLITH instance directory. Run \`monolith init\` first.`);
+    }
+    let parent;
+    try {
+        parent = openParent(store.boundary, store.dirAbs, { create: true, ops: opts.ops });
+    }
+    catch (err) {
+        if (err instanceof SafeWriteError)
+            throw unsafe(err);
+        throw err;
+    }
+    let markers;
+    try {
+        markers = openParent(store.boundary, join(store.dirAbs, IDS_DIR), { create: true, ops: opts.ops });
+    }
+    catch (err) {
+        if (err instanceof SafeWriteError)
+            throw unsafe(err);
+        throw err;
+    }
+    const createdAt = (opts.now ?? (() => new Date()))().toISOString();
+    try {
+        // Ideas created before IDEA-001D have no marker: protect them from now on.
+        for (const existing of scanIds(store))
+            reserveId(markers, existing, createdAt, opts);
+    }
+    catch (err) {
+        if (err instanceof SafeWriteError)
+            throw unsafe(err);
+        throw err;
+    }
+    for (let attempt = 0; attempt < MAX_ALLOCATION_ATTEMPTS; attempt++) {
+        const next = Math.max(highestNumber(scanIds(store)), highestNumber(scanReservedIds(store))) + 1;
+        if (next > MAX_IDEA_NUMBER)
+            throw new IdeaError('IDEA_ID_EXHAUSTED', 'the idea id space is exhausted; nothing was written.');
+        const id = formatIdeaId(next);
+        const idea = { id, title: input.title, description: input.description, createdAt, status: 'inbox' };
+        if (input.context !== undefined)
+            idea.context = input.context;
+        const text = serializeIdea(idea);
+        // The character limits do not bound the file (UTF-8 and JSON escaping expand text), and the reader refuses
+        // files over `fileBytes`: refuse here, before an id is reserved, so nothing is saved that cannot be read back.
+        const bytes = Buffer.byteLength(text, 'utf8');
+        if (bytes > IDEA_LIMITS.fileBytes) {
+            throw new IdeaError('IDEA_INVALID_INPUT', `the idea is too large once stored (${bytes} > ${IDEA_LIMITS.fileBytes} bytes in UTF-8); shorten the description or context. Nothing was written.`);
+        }
+        // Reserve first: once the marker exists the id is never handed out again, whatever happens next.
+        try {
+            if (!reserveId(markers, id, createdAt, opts))
+                continue; // lost the race for this number
+        }
+        catch (err) {
+            if (err instanceof SafeWriteError)
+                throw unsafe(err);
+            throw err;
+        }
+        try {
+            const outcome = createFile(parent, ideaFileName(id), text, {
+                mode: 0o666,
+                exactMode: false,
+                durability: 'full',
+                maxBytes: IDEA_LIMITS.fileBytes,
+                ops: opts.ops,
+            });
+            for (const w of outcome.warnings)
+                opts.onWarning?.(w);
+            return { idea, path: join(store.dirAbs, ideaFileName(id)) };
+        }
+        catch (err) {
+            // Lost the race for this number (or a stray entry holds it): take the next one.
+            if (err instanceof SafeWriteError && err.code === 'WRITE_TARGET_EXISTS')
+                continue;
+            throw err;
+        }
+    }
+    throw new IdeaError('IDEA_ID_EXHAUSTED', `could not allocate an idea id after ${MAX_ALLOCATION_ATTEMPTS} attempts; nothing was written.`);
+}
+function readIdeaFile(store, id) {
+    const abs = join(store.dirAbs, ideaFileName(id));
+    return readBoundedFile(abs, id, { boundary: store.projectRoot, maxBytes: IDEA_LIMITS.fileBytes }, true);
+}
+function loadIdea(store, id) {
+    const read = readIdeaFile(store, id);
+    if (!read.ok) {
+        if (read.code === 'FILE_MISSING')
+            return { missing: true };
+        const security = ['FILE_SYMLINK', 'FILE_HARDLINKED', 'FILE_NOT_REGULAR', 'FILE_OUTSIDE_PROJECT', 'READ_BOUNDARY_INVALID', 'READ_UNSUPPORTED_PLATFORM'];
+        return { ok: false, id, code: security.includes(read.code) ? 'IDEA_UNSAFE_PATH' : 'IDEA_CORRUPT', reason: `${read.code}: ${read.detail}` };
+    }
+    try {
+        return { ok: true, idea: parseIdea(id, read.content) };
+    }
+    catch (err) {
+        if (err instanceof IdeaError)
+            return { ok: false, id, code: 'IDEA_CORRUPT', reason: err.message };
+        throw err;
+    }
+}
+/** Read one idea. Throws IDEA_INVALID_ID / IDEA_NOT_FOUND / IDEA_UNSAFE_PATH / IDEA_CORRUPT. Never writes. */
+export function getIdea(store, id) {
+    if (!isIdeaId(id))
+        throw new IdeaError('IDEA_INVALID_ID', `"${id}" is not an idea id (expected IDEA-NNN, e.g. IDEA-001).`);
+    const loaded = loadIdea(store, id);
+    if ('missing' in loaded)
+        throw new IdeaError('IDEA_NOT_FOUND', `No idea ${id}.`);
+    if (!loaded.ok)
+        throw new IdeaError(loaded.code, loaded.reason);
+    return loaded.idea;
+}
+/**
+ * All ideas, ordered by number. A file that cannot be read as an idea appears as
+ * a non-ok entry instead of aborting the listing. A symlinked ideas directory
+ * is refused as a whole. Never writes.
+ */
+export function listIdeas(store) {
+    try {
+        openParent(store.boundary, store.dirAbs); // every component below the project root: a real directory
+    }
+    catch (err) {
+        if (err instanceof SafeWriteError) {
+            if (err.code === 'WRITE_PARENT_MISSING')
+                return [];
+            throw unsafe(err);
+        }
+        throw err;
+    }
+    const entries = [];
+    for (const id of scanIds(store)) {
+        const loaded = loadIdea(store, id);
+        if ('missing' in loaded)
+            continue; // vanished between readdir and read
+        entries.push(loaded);
+    }
+    return entries;
+}

package/dist/ideas/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Manual Idea Capture (IDEA-001A) — types.
+ *
+ * An idea is a deferred thought saved without leaving the current task. It is
+ * NOT a task, a hypothesis or a Durable State record: it does not touch
+ * `active.md`, `state.json` or any mission.
+ */
+export declare const IDEA_STATUSES: readonly ["inbox", "planned", "archived"];
+export type IdeaStatus = (typeof IDEA_STATUSES)[number];
+export interface Idea {
+    /** `IDEA-NNN` (at least three digits; grows past 999). Never reused while its file exists. */
+    id: string;
+    /** Single line. */
+    title: string;
+    /** Free text, stored verbatim (newlines, markdown, CRLF preserved). */
+    description: string;
+    /** ISO-8601 UTC timestamp, set once at creation. */
+    createdAt: string;
+    status: IdeaStatus;
+    context?: string;
+    tags?: string[];
+}
+/** What a caller supplies; `id`, `createdAt` and `status` are assigned by the store. */
+export interface NewIdea {
+    title: string;
+    description: string;
+    context?: string;
+}
+/** Limits are protective ceilings (a CLI argument, not a document store). */
+export declare const IDEA_LIMITS: {
+    readonly title: 300;
+    readonly description: 100000;
+    readonly context: 20000;
+    /** Upper bound of one idea file, in bytes (frontmatter + body). */
+    readonly fileBytes: number;
+};
+export type IdeaErrorCode = 'IDEA_INVALID_INPUT' | 'IDEA_INVALID_ID' | 'IDEA_NOT_FOUND' | 'IDEA_CORRUPT' | 'IDEA_UNSAFE_PATH' | 'IDEA_NOT_INITIALIZED' | 'IDEA_ID_EXHAUSTED';
+export declare class IdeaError extends Error {
+    readonly code: IdeaErrorCode;
+    constructor(code: IdeaErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** One directory entry of `list`: a readable idea, or a file that could not be read as one. */
+export type IdeaEntry = {
+    ok: true;
+    idea: Idea;
+} | {
+    ok: false;
+    id: string;
+    code: 'IDEA_CORRUPT' | 'IDEA_UNSAFE_PATH';
+    reason: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/ideas/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ideas/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,aAAa,2CAA4C,CAAC;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,IAAI;IACnB,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAC;IACX,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wFAAwF;AACxF,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,eAAO,MAAM,WAAW;;;;IAItB,mEAAmE;;CAE3D,CAAC;AAEX,MAAM,MAAM,aAAa,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,kBAAkB,GAClB,sBAAsB,GACtB,mBAAmB,CAAC;AAExB,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBACjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAMhF;AAED,+FAA+F;AAC/F,MAAM,MAAM,SAAS,GACjB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,GAAG,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/ideas/types.js

@@ -0,0 +1,26 @@
+/**
+ * Manual Idea Capture (IDEA-001A) — types.
+ *
+ * An idea is a deferred thought saved without leaving the current task. It is
+ * NOT a task, a hypothesis or a Durable State record: it does not touch
+ * `active.md`, `state.json` or any mission.
+ */
+export const IDEA_STATUSES = ['inbox', 'planned', 'archived'];
+/** Limits are protective ceilings (a CLI argument, not a document store). */
+export const IDEA_LIMITS = {
+    title: 300,
+    description: 100_000,
+    context: 20_000,
+    /** Upper bound of one idea file, in bytes (frontmatter + body). */
+    fileBytes: 256 * 1024,
+};
+export class IdeaError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message);
+        this.name = 'IdeaError';
+        this.code = code;
+        if (options?.cause !== undefined)
+            this.cause = options.cause;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @latysh-development/monolith — Public API surface
+ *
+ * This file is the package entrypoint. Exports grow here as Kernel modules
+ * are extracted from project instances into this package.
+ *
+ * Current state: Phase 6 — validate implemented; Scriptorium (Story 1.2) and
+ * Explicit Relationship Graph (Story 1.3) integrated.
+ * See Phase 7+ roadmap for Kernel extraction.
+ *
+ * Webway (the frequency-based "meaning linker" prototype from Story 1.1) was
+ * extracted into its own repository: https://github.com/Demion-L/webway —
+ * it was an independent research track with zero runtime coupling to
+ * Scriptorium/Graph, see docs/webway-v0.md for the historical record.
+ */
+export type { ProjectDefinition } from './types/project-definition.js';
+export type { GateCheckResult } from './types/enforcement.js';
+export type { VerificationContext, VerificationReport } from './types/integrity.js';
+export type { ProjectConfig, InitOptions } from './init/types.js';
+export { MONOLITH_VERSION } from './version.js';
+export { runInit } from './init/index.js';
+export type { ScriptoriumInput, ScriptoriumResult, ConceptCandidate, RelationshipCandidate, Evidence, SourceReference, ScriptoriumDiagnostic, ConceptSource, EvidenceSource, HeadingLevel, ObjectDeclaration, DeclaredObjectKind, } from './scriptorium/index.js';
+export { compileMarkdownArtifact, isStructuralHeadingNoise } from './scriptorium/index.js';
+export type { GraphNode, GraphEdge, GraphDiagnostic, ExplicitRelationshipGraph, UnresolvedReference, IdentityConflict, KnowledgeObject, KnowledgeObjectKind, Resolution, UnresolvedResolution, ObjectIndex, } from './graph/index.js';
+export { buildGraph, buildObjectIndex, resolveRef, makeRef, parseRef, isValidIdentifier } from './graph/index.js';
+export type { CoordinatoriumState, Mission, MissionStatus, MissionResult, CoordinatoriumErrorCode, StartMissionInput, FinishMissionInput, StateWriteTarget, StateReadTarget, } from './coordinatorium/index.js';
+export { createInitialState, CoordinatoriumError, StateCorruptedError, StateSchemaError, LockTimeoutError, MissionNotFoundError, InvalidTransitionError, ValidationError, readState, mutateState, projectTarget, trustedDirectoryTarget, startMission, listMissions, getMission, finishMission, } from './coordinatorium/index.js';
+export { SafeWriteError } from './root/index.js';
+export type { WriteErrorCode, WriteWarning, WriteWarningCode, PublicationState } from './root/index.js';
+export * as durable from './durable/index.js';
+export * as ideas from './ideas/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACpF,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG1C,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAG3F,YAAY,EACV,SAAS,EACT,SAAS,EACT,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,oBAAoB,EACpB,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIlH,YAAY,EACV,mBAAmB,EACnB,OAAO,EACP,aAAa,EACb,aAAa,EACb,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,SAAS,EACT,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,aAAa,GACd,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKxG,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAG9C,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC"}