@lumenflow/memory 1.0.0

package/dist/mem-create-core.js

@@ -0,0 +1,369 @@
+/**
+ * Memory Create Core (WU-1469)
+ *
+ * Core logic for creating memory nodes with discovered-from provenance.
+ * KEY DIFFERENTIATOR: supports discovered-from relationship for scope-creep
+ * forensics. Creates audit trail of WHY work expanded, not just WHAT changed.
+ *
+ * Features:
+ * - Creates all 5 node types: session, discovery, checkpoint, note, summary
+ * - Auto-generates hash-based ID using mem-id
+ * - Validates node against memory-schema
+ * - Supports discovered-from relationship for provenance tracking
+ *
+ * @see {@link tools/mem-create.mjs} - CLI wrapper
+ * @see {@link tools/__tests__/mem-create.test.mjs} - Tests
+ * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { generateMemId } from './mem-id.js';
+import { appendNode } from './memory-store.js';
+import { MEMORY_NODE_TYPES, MEMORY_PATTERNS, validateMemoryNode, validateRelationship, } from './memory-schema.js';
+/**
+ * Memory directory path relative to base directory
+ */
+const MEMORY_DIR = '.beacon/memory';
+/**
+ * Relationships file name
+ */
+const RELATIONSHIPS_FILE_NAME = 'relationships.jsonl';
+/**
+ * Default node type
+ */
+const DEFAULT_NODE_TYPE = 'discovery';
+/**
+ * Session file path relative to main checkout
+ */
+const SESSION_FILE_PATH = '.beacon/sessions/current.json';
+/**
+ * Type aliases for user-friendly CLI experience (WU-1762)
+ * Maps alias names to canonical types and additional tags
+ */
+const TYPE_ALIASES = {
+    bug: { type: 'discovery', tag: 'bug' },
+    idea: { type: 'discovery', tag: 'idea' },
+    question: { type: 'discovery', tag: 'question' },
+    dependency: { type: 'discovery', tag: 'dependency' },
+};
+/**
+ * Lifecycle mapping by node type
+ * - session: Lives for WU duration (wu)
+ * - discovery: Lives for WU duration (wu)
+ * - checkpoint: Lives for session (session)
+ * - note: Lives for session (session)
+ * - summary: Persists across WUs (project)
+ */
+const LIFECYCLE_BY_TYPE = {
+    session: 'wu',
+    discovery: 'wu',
+    checkpoint: 'session',
+    note: 'session',
+    summary: 'project',
+};
+/**
+ * Error messages for validation
+ */
+const ERROR_MESSAGES = {
+    TITLE_REQUIRED: 'title is required',
+    TITLE_EMPTY: 'title cannot be empty',
+    INVALID_TYPE: `Invalid node type. Must be one of: ${MEMORY_NODE_TYPES.join(', ')}`,
+    WU_ID_INVALID: 'Invalid WU ID format. Expected pattern: WU-XXX (e.g., WU-123)',
+    MEMORY_ID_INVALID: 'Invalid memory ID format. Expected pattern: mem-XXXX (e.g., mem-a1b2)',
+};
+/**
+ * Normalizes type aliases to canonical types (WU-1762)
+ *
+ * Converts user-friendly type aliases (bug, idea) to canonical types (discovery)
+ * and returns the tag to be added.
+ *
+ * @param inputType - User-provided type (may be alias)
+ * @returns Normalized type and optional tag
+ */
+function normalizeType(inputType) {
+    const alias = TYPE_ALIASES[inputType];
+    if (alias) {
+        return { type: alias.type, aliasTag: alias.tag };
+    }
+    return { type: inputType, aliasTag: null };
+}
+/**
+ * Checks if a path is a git worktree (has .git file pointing to main)
+ *
+ * @param dir - Directory to check
+ * @returns Path to main checkout or null if not a worktree
+ */
+async function getMainCheckoutFromWorktree(dir) {
+    const gitPath = path.join(dir, '.git');
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Known path
+        const stat = await fs.stat(gitPath);
+        if (stat.isFile()) {
+            // .git is a file = we're in a worktree
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- Known path
+            const gitContent = await fs.readFile(gitPath, { encoding: 'utf-8' });
+            // Format: "gitdir: /path/to/main/.git/worktrees/name"
+            const match = gitContent.match(/^gitdir:\s*(.+)/);
+            if (match && match[1]) {
+                const gitDir = match[1].trim();
+                // Extract main checkout: /path/to/main/.git/worktrees/name → /path/to/main
+                const worktreesIndex = gitDir.indexOf('/.git/worktrees/');
+                if (worktreesIndex !== -1) {
+                    return gitDir.substring(0, worktreesIndex);
+                }
+            }
+        }
+    }
+    catch {
+        // Not a worktree or .git doesn't exist
+    }
+    return null;
+}
+/**
+ * Reads the current session from session file
+ *
+ * @param baseDir - Base directory (main checkout)
+ * @returns Session data or null
+ */
+async function readCurrentSession(baseDir) {
+    const sessionPath = path.join(baseDir, SESSION_FILE_PATH);
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Known session path
+        const content = await fs.readFile(sessionPath, { encoding: 'utf-8' });
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Auto-infers WU ID from current session (WU-1762)
+ *
+ * Checks for session file in:
+ * 1. Current baseDir (if running in main checkout)
+ * 2. Main checkout (if running in worktree)
+ *
+ * @param baseDir - Current working directory
+ * @returns Session data from session file or null
+ */
+async function inferSessionFromSessionFile(baseDir) {
+    // First, try to read session from current directory
+    let session = await readCurrentSession(baseDir);
+    if (session) {
+        return session;
+    }
+    // If not found, check if we're in a worktree and look in main checkout
+    const mainCheckout = await getMainCheckoutFromWorktree(baseDir);
+    if (mainCheckout) {
+        session = await readCurrentSession(mainCheckout);
+        if (session) {
+            return session;
+        }
+    }
+    return null;
+}
+function isValidSessionId(value) {
+    if (!value)
+        return false;
+    if (typeof value !== 'string')
+        return false;
+    // UUID v4 format (sufficient for validation here; actual schema validates uuid too)
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+/**
+ * Validates WU ID format if provided
+ *
+ * @param wuId - WU ID to validate
+ * @returns True if valid or not provided
+ */
+function isValidWuId(wuId) {
+    if (!wuId)
+        return true;
+    return MEMORY_PATTERNS.WU_ID.test(wuId);
+}
+/**
+ * Validates memory ID format
+ *
+ * @param memId - Memory ID to validate
+ * @returns True if valid
+ */
+function isValidMemoryId(memId) {
+    return MEMORY_PATTERNS.MEMORY_ID.test(memId);
+}
+/**
+ * Ensures the memory directory exists
+ *
+ * @param baseDir - Base directory
+ * @returns Memory directory path
+ */
+async function ensureMemoryDir(baseDir) {
+    const memoryDir = path.join(baseDir, MEMORY_DIR);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Known directory path
+    await fs.mkdir(memoryDir, { recursive: true });
+    return memoryDir;
+}
+/**
+ * Appends a relationship to the relationships.jsonl file
+ *
+ * @param memoryDir - Memory directory path
+ * @param relationship - Relationship object
+ * @returns The appended relationship
+ */
+async function appendRelationship(memoryDir, relationship) {
+    // Validate relationship before appending
+    const validation = validateRelationship(relationship);
+    if (!validation.success) {
+        const issues = validation.error.issues
+            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+            .join(', ');
+        throw new Error(`Relationship validation error: ${issues}`);
+    }
+    const filePath = path.join(memoryDir, RELATIONSHIPS_FILE_NAME);
+    const line = `${JSON.stringify(relationship)}\n`;
+    // Use append flag to avoid rewriting the file
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes known file
+    await fs.appendFile(filePath, line, { encoding: 'utf-8' });
+    return relationship;
+}
+/**
+ * Gets the lifecycle for a node type
+ *
+ * @param type - Node type
+ * @returns Lifecycle value
+ */
+function getLifecycleForType(type) {
+    return LIFECYCLE_BY_TYPE[type];
+}
+/**
+ * Creates a new memory node with optional discovered-from provenance.
+ *
+ * Creates a memory node with:
+ * - Unique ID (mem-XXXX format) generated from content hash
+ * - User-provided title as content
+ * - Type-appropriate lifecycle
+ * - Optional discovered-from relationship for provenance tracking
+ *
+ * @param {string} baseDir - Base directory containing .beacon/memory/
+ * @param {CreateMemoryNodeOptions} options - Node creation options
+ * @returns {Promise<CreateMemoryNodeResult>} Result with created node and optional relationship
+ * @throws {Error} If title is missing, type is invalid, or IDs are malformed
+ *
+ * @example
+ * // Create a simple discovery node
+ * const result = await createMemoryNode(baseDir, {
+ *   title: 'Found relevant file at src/utils.mjs',
+ *   type: 'discovery',
+ *   wuId: 'WU-1469',
+ * });
+ *
+ * @example
+ * // Create a node with provenance (scope-creep tracking)
+ * const parent = await createMemoryNode(baseDir, {
+ *   title: 'Found src/components/',
+ *   type: 'discovery',
+ * });
+ * const child = await createMemoryNode(baseDir, {
+ *   title: 'Found src/components/Button.tsx',
+ *   type: 'discovery',
+ *   discoveredFrom: parent.node.id, // Track where this came from
+ * });
+ */
+export async function createMemoryNode(baseDir, options) {
+    const { title, type: inputType = DEFAULT_NODE_TYPE, wuId: explicitWuId, sessionId: explicitSessionId, discoveredFrom, tags: inputTags, priority, } = options;
+    // Validate required fields
+    if (title === undefined || title === null) {
+        throw new Error(ERROR_MESSAGES.TITLE_REQUIRED);
+    }
+    if (title === '') {
+        throw new Error(ERROR_MESSAGES.TITLE_EMPTY);
+    }
+    // Normalize type aliases (WU-1762): bug → discovery + tag, idea → discovery + tag
+    const { type: normalizedType, aliasTag } = normalizeType(inputType);
+    // Validate node type (after alias normalization) and narrow type
+    if (!MEMORY_NODE_TYPES.includes(normalizedType)) {
+        throw new Error(ERROR_MESSAGES.INVALID_TYPE);
+    }
+    // Type is now validated - safe to cast
+    const type = normalizedType;
+    // Merge tags: alias tag + user-provided tags, deduplicated (WU-1762)
+    let tags = inputTags ? [...inputTags] : [];
+    if (aliasTag && !tags.includes(aliasTag)) {
+        tags = [aliasTag, ...tags];
+    }
+    // Remove duplicates while preserving order
+    tags = [...new Set(tags)];
+    // Auto-infer WU ID and session ID from current session if not provided (WU-1762)
+    const inferredSession = explicitWuId && explicitSessionId ? null : await inferSessionFromSessionFile(baseDir);
+    const wuId = explicitWuId || inferredSession?.wu_id;
+    const sessionId = explicitSessionId ||
+        (isValidSessionId(inferredSession?.session_id) ? inferredSession.session_id : undefined);
+    // Validate WU ID format if provided
+    if (wuId && !isValidWuId(wuId)) {
+        throw new Error(ERROR_MESSAGES.WU_ID_INVALID);
+    }
+    // Validate discovered-from ID format if provided
+    if (discoveredFrom && !isValidMemoryId(discoveredFrom)) {
+        throw new Error(ERROR_MESSAGES.MEMORY_ID_INVALID);
+    }
+    // Ensure memory directory exists
+    const memoryDir = await ensureMemoryDir(baseDir);
+    // Generate node
+    const timestamp = new Date().toISOString();
+    // Generate deterministic ID from content + timestamp for uniqueness
+    const idContent = `${title}-${timestamp}`;
+    const id = generateMemId(idContent);
+    // Get lifecycle for this type
+    const lifecycle = getLifecycleForType(type);
+    // Build metadata object
+    const metadata = {};
+    if (priority) {
+        metadata.priority = priority;
+    }
+    const node = {
+        id,
+        type,
+        lifecycle,
+        content: title,
+        created_at: timestamp,
+    };
+    // Add optional fields
+    if (wuId) {
+        node.wu_id = wuId;
+    }
+    if (sessionId) {
+        node.session_id = sessionId;
+    }
+    if (Object.keys(metadata).length > 0) {
+        node.metadata = metadata;
+    }
+    if (tags && tags.length > 0) {
+        node.tags = tags;
+    }
+    // Validate node against schema
+    const nodeValidation = validateMemoryNode(node);
+    if (!nodeValidation.success) {
+        const issues = nodeValidation.error.issues
+            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+            .join(', ');
+        throw new Error(`Node validation error: ${issues}`);
+    }
+    // Persist node to memory store
+    await appendNode(memoryDir, node);
+    // Build result
+    const result = {
+        success: true,
+        node,
+    };
+    // Create discovered-from relationship if parent specified
+    if (discoveredFrom) {
+        const relationship = {
+            from_id: node.id,
+            to_id: discoveredFrom,
+            type: 'discovered_from',
+            created_at: timestamp,
+        };
+        await appendRelationship(memoryDir, relationship);
+        result.relationship = relationship;
+    }
+    return result;
+}

package/dist/mem-create-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-create-core.js","sourceRoot":"","sources":["../src/mem-create-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAEpC;;GAEG;AACH,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAEtD;;GAEG;AACH,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAEtC;;GAEG;AACH,MAAM,iBAAiB,GAAG,+BAA+B,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,YAAY,GAAG;IACnB,GAAG,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,KAAK,EAAE;IACtC,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE;IACxC,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,EAAE;IAChD,UAAU,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,EAAE;CACrD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAG;IACxB,OAAO,EAAE,IAAI;IACb,SAAS,EAAE,IAAI;IACf,UAAU,EAAE,SAAS;IACrB,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,cAAc,GAAG;IACrB,cAAc,EAAE,mBAAmB;IACnC,WAAW,EAAE,uBAAuB;IACpC,YAAY,EAAE,sCAAsC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;IAClF,aAAa,EAAE,+DAA+D;IAC9E,iBAAiB,EAAE,uEAAuE;CAC3F,CAAC;AAEF;;;;;;;;GAQG;AACH,SAAS,aAAa,CAAC,SAAS;IAC9B,wGAAwG;IACxG,MAAM,KAAK,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,2BAA2B,CAAC,GAAG;IAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,iFAAiF;QACjF,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YAClB,uCAAuC;YACvC,iFAAiF;YACjF,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACvD,sDAAsD;YACtD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;YAClD,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC/B,2EAA2E;gBAC3E,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;gBAC1D,IAAI,cAAc,KAAK,CAAC,CAAC,EAAE,CAAC;oBAC1B,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;gBAC7C,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,uCAAuC;IACzC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,kBAAkB,CAAC,OAAO;IACvC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC1D,IAAI,CAAC;QACH,yFAAyF;QACzF,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,2BAA2B,CAAC,OAAO;IAChD,oDAAoD;IACpD,IAAI,OAAO,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,uEAAuE;IACvE,MAAM,YAAY,GAAG,MAAM,2BAA2B,CAAC,OAAO,CAAC,CAAC;IAChE,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,GAAG,MAAM,kBAAkB,CAAC,YAAY,CAAC,CAAC;QACjD,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAK;IAC7B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,oFAAoF;IACpF,OAAO,iEAAiE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACvF,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,IAAI;IACvB,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAK;IAC5B,OAAO,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,eAAe,CAAC,OAAO;IACpC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACjD,2FAA2F;IAC3F,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,kBAAkB,CAAC,SAAS,EAAE,YAAY;IACvD,yCAAyC;IACzC,MAAM,UAAU,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM;aACnC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;aAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC;IAEjD,8CAA8C;IAC9C,iGAAiG;IACjG,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAE7C,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,IAAI;IAC/B,2GAA2G;IAC3G,OAAO,iBAAiB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAO,EAAE,OAAO;IACrD,MAAM,EACJ,KAAK,EACL,IAAI,EAAE,SAAS,GAAG,iBAAiB,EACnC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,iBAAiB,EAC5B,cAAc,EACd,IAAI,EAAE,SAAS,EACf,QAAQ,GACT,GAAG,OAAO,CAAC;IAEZ,2BAA2B;IAC3B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;IAED,kFAAkF;IAClF,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAEpD,iDAAiD;IACjD,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAC/C,CAAC;IAED,qEAAqE;IACrE,IAAI,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3C,IAAI,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzC,IAAI,GAAG,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,2CAA2C;IAC3C,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAE1B,iFAAiF;IACjF,MAAM,eAAe,GAAG,YAAY,IAAI,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,2BAA2B,CAAC,OAAO,CAAC,CAAC;IAC9G,MAAM,IAAI,GAAG,YAAY,IAAI,eAAe,EAAE,KAAK,CAAC;IACpD,MAAM,SAAS,GACb,iBAAiB,IAAI,CAAC,gBAAgB,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAEhH,oCAAoC;IACpC,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAChD,CAAC;IAED,iDAAiD;IACjD,IAAI,cAAc,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC;IACpD,CAAC;IAED,iCAAiC;IACjC,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IAEjD,gBAAgB;IAChB,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAE3C,oEAAoE;IACpE,MAAM,SAAS,GAAG,GAAG,KAAK,IAAI,SAAS,EAAE,CAAC;IAC1C,MAAM,EAAE,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAEpC,8BAA8B;IAC9B,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAE5C,wBAAwB;IACxB,MAAM,QAAQ,GAAG,EAAE,CAAC;IACpB,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC/B,CAAC;IAED,uDAAuD;IACvD,MAAM,IAAI,GAAG;QACX,EAAE;QACF,IAAI;QACJ,SAAS;QACT,OAAO,EAAE,KAAK;QACd,UAAU,EAAE,SAAS;KACtB,CAAC;IAEF,sBAAsB;IACtB,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IACD,IAAI,SAAS,EAAE,CAAC;QACd,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IACD,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,+BAA+B;IAC/B,MAAM,cAAc,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM;aACvC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;aAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,+BAA+B;IAC/B,MAAM,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAElC,eAAe;IACf,MAAM,MAAM,GAAG;QACb,OAAO,EAAE,IAAI;QACb,IAAI;KACL,CAAC;IAEF,0DAA0D;IAC1D,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,YAAY,GAAG;YACnB,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,KAAK,EAAE,cAAc;YACrB,IAAI,EAAE,iBAAiB;YACvB,UAAU,EAAE,SAAS;SACtB,CAAC;QAEF,MAAM,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;QAClD,MAAM,CAAC,YAAY,GAAG,YAAY,CAAC;IACrC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/mem-id.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Memory ID Generator (WU-1465)
+ *
+ * Hash-based collision-free ID generation for memory nodes.
+ * Format: mem-[4 hex chars] derived from content hash.
+ * Supports hierarchical IDs (mem-a1b2.1.2) for sub-task decomposition.
+ *
+ * @see {@link tools/lib/__tests__/mem-id.test.mjs} - Tests
+ * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
+ */
+/**
+ * Regex patterns for memory ID validation
+ */
+export declare const MEM_ID_PATTERNS: {
+    /**
+     * Base memory ID format: mem-[a-f0-9]{4}
+     * Only lowercase hex characters (0-9, a-f)
+     */
+    BASE_ID: RegExp;
+    /**
+     * Hierarchical memory ID format: mem-[a-f0-9]{4}(.[1-9][0-9]*)*
+     * Base ID followed by optional dot-separated positive integers
+     * Examples: mem-a1b2, mem-a1b2.1, mem-a1b2.1.2
+     */
+    HIERARCHICAL_ID: RegExp;
+};
+/**
+ * Generates a deterministic memory ID from content.
+ *
+ * Uses SHA-256 hash of the content, taking the first 4 hex characters.
+ * Same content always produces the same ID (deterministic).
+ *
+ * @param content - Content to hash for ID generation
+ * @returns Memory ID in format mem-[a-f0-9]{4}
+ *
+ * @example
+ * const id = generateMemId('discovered file at src/utils.mjs');
+ * // Returns something like 'mem-a3f2'
+ */
+export declare function generateMemId(content: string): string;
+/**
+ * Generates a hierarchical memory ID by appending an index to a parent ID.
+ *
+ * Used for sub-task decomposition where a parent task (mem-a1b2) has
+ * child tasks (mem-a1b2.1, mem-a1b2.2) and grandchildren (mem-a1b2.1.1).
+ *
+ * @param parentId - Parent memory ID (base or hierarchical)
+ * @param index - Positive integer index (1-based)
+ * @returns Hierarchical memory ID
+ * @throws If parentId is invalid or index is not positive
+ *
+ * @example
+ * generateHierarchicalId('mem-a1b2', 1);     // 'mem-a1b2.1'
+ * generateHierarchicalId('mem-a1b2.1', 2);  // 'mem-a1b2.1.2'
+ */
+export declare function generateHierarchicalId(parentId: string, index: number): string;
+/**
+ * Validation result from validateMemId
+ */
+export interface MemIdValidationResult {
+    /** Whether the ID is valid */
+    valid: boolean;
+    /** Type of ID if valid */
+    type?: 'base' | 'hierarchical';
+    /** Base ID portion if hierarchical */
+    baseId?: string;
+    /** Hierarchical indices (empty for base IDs) */
+    indices: number[];
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Validates a memory ID and extracts its components.
+ *
+ * Returns validation result with type classification and parsed components.
+ * Compatible with MEMORY_PATTERNS.MEMORY_ID from memory-schema.mjs.
+ *
+ * @param id - Memory ID to validate
+ * @returns Validation result with parsed components
+ *
+ * @example
+ * validateMemId('mem-a1b2');
+ * // { valid: true, type: 'base', baseId: 'mem-a1b2', indices: [] }
+ *
+ * validateMemId('mem-a1b2.1.2');
+ * // { valid: true, type: 'hierarchical', baseId: 'mem-a1b2', indices: [1, 2] }
+ *
+ * validateMemId('invalid');
+ * // { valid: false, error: 'Invalid memory ID format', indices: [] }
+ */
+export declare function validateMemId(id: string): MemIdValidationResult;

package/dist/mem-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-id.d.ts","sourceRoot":"","sources":["../src/mem-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH;;GAEG;AACH,eAAO,MAAM,eAAe;IAC1B;;;OAGG;;IAGH;;;;OAIG;;CAEJ,CAAC;AAWF;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,OAAO,KAAA,UAOpC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,KAAA,EAAE,KAAK,KAAA,UAYrD;AAED;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAA;;;;;;;;;;;;EA+B/B"}

package/dist/mem-id.js

@@ -0,0 +1,136 @@
+/**
+ * Memory ID Generator (WU-1465)
+ *
+ * Hash-based collision-free ID generation for memory nodes.
+ * Format: mem-[4 hex chars] derived from content hash.
+ * Supports hierarchical IDs (mem-a1b2.1.2) for sub-task decomposition.
+ *
+ * @see {@link tools/lib/__tests__/mem-id.test.mjs} - Tests
+ * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Memory ID prefix constant
+ */
+const MEM_ID_PREFIX = 'mem-';
+/**
+ * Number of hex characters in base ID suffix
+ */
+const HEX_SUFFIX_LENGTH = 4;
+/**
+ * Regex patterns for memory ID validation
+ */
+export const MEM_ID_PATTERNS = {
+    /**
+     * Base memory ID format: mem-[a-f0-9]{4}
+     * Only lowercase hex characters (0-9, a-f)
+     */
+    BASE_ID: /^mem-[a-f0-9]{4}$/,
+    /**
+     * Hierarchical memory ID format: mem-[a-f0-9]{4}(.[1-9][0-9]*)*
+     * Base ID followed by optional dot-separated positive integers
+     * Examples: mem-a1b2, mem-a1b2.1, mem-a1b2.1.2
+     */
+    HIERARCHICAL_ID: /^mem-[a-f0-9]{4}(\.[1-9][0-9]*)*$/,
+};
+/**
+ * Error messages for validation and exceptions
+ */
+const ERROR_MESSAGES = {
+    INVALID_ID: 'Invalid memory ID format',
+    INVALID_BASE_ID: 'Invalid base memory ID format',
+    INVALID_INDEX: 'Index must be a positive integer',
+};
+/**
+ * Generates a deterministic memory ID from content.
+ *
+ * Uses SHA-256 hash of the content, taking the first 4 hex characters.
+ * Same content always produces the same ID (deterministic).
+ *
+ * @param content - Content to hash for ID generation
+ * @returns Memory ID in format mem-[a-f0-9]{4}
+ *
+ * @example
+ * const id = generateMemId('discovered file at src/utils.mjs');
+ * // Returns something like 'mem-a3f2'
+ */
+export function generateMemId(content) {
+    const hash = createHash('sha256').update(content, 'utf-8').digest('hex');
+    // Take first 4 hex characters from hash
+    const suffix = hash.slice(0, HEX_SUFFIX_LENGTH);
+    return `${MEM_ID_PREFIX}${suffix}`;
+}
+/**
+ * Generates a hierarchical memory ID by appending an index to a parent ID.
+ *
+ * Used for sub-task decomposition where a parent task (mem-a1b2) has
+ * child tasks (mem-a1b2.1, mem-a1b2.2) and grandchildren (mem-a1b2.1.1).
+ *
+ * @param parentId - Parent memory ID (base or hierarchical)
+ * @param index - Positive integer index (1-based)
+ * @returns Hierarchical memory ID
+ * @throws If parentId is invalid or index is not positive
+ *
+ * @example
+ * generateHierarchicalId('mem-a1b2', 1);     // 'mem-a1b2.1'
+ * generateHierarchicalId('mem-a1b2.1', 2);  // 'mem-a1b2.1.2'
+ */
+export function generateHierarchicalId(parentId, index) {
+    // Validate parent ID
+    if (!MEM_ID_PATTERNS.HIERARCHICAL_ID.test(parentId)) {
+        throw new Error(`${ERROR_MESSAGES.INVALID_BASE_ID}: ${parentId}`);
+    }
+    // Validate index is positive integer
+    if (!Number.isInteger(index) || index < 1) {
+        throw new Error(`${ERROR_MESSAGES.INVALID_INDEX}: ${index}`);
+    }
+    return `${parentId}.${index}`;
+}
+/**
+ * Validates a memory ID and extracts its components.
+ *
+ * Returns validation result with type classification and parsed components.
+ * Compatible with MEMORY_PATTERNS.MEMORY_ID from memory-schema.mjs.
+ *
+ * @param id - Memory ID to validate
+ * @returns Validation result with parsed components
+ *
+ * @example
+ * validateMemId('mem-a1b2');
+ * // { valid: true, type: 'base', baseId: 'mem-a1b2', indices: [] }
+ *
+ * validateMemId('mem-a1b2.1.2');
+ * // { valid: true, type: 'hierarchical', baseId: 'mem-a1b2', indices: [1, 2] }
+ *
+ * validateMemId('invalid');
+ * // { valid: false, error: 'Invalid memory ID format', indices: [] }
+ */
+export function validateMemId(id) {
+    // Quick validation using regex
+    if (!MEM_ID_PATTERNS.HIERARCHICAL_ID.test(id)) {
+        return {
+            valid: false,
+            error: ERROR_MESSAGES.INVALID_ID,
+            indices: [],
+        };
+    }
+    // Check if it's a base ID (no dots after the prefix)
+    if (MEM_ID_PATTERNS.BASE_ID.test(id)) {
+        return {
+            valid: true,
+            type: 'base',
+            baseId: id,
+            indices: [],
+        };
+    }
+    // It's a hierarchical ID - parse components
+    const parts = id.split('.');
+    const baseId = parts[0];
+    const indices = parts.slice(1).map((part) => parseInt(part, 10));
+    return {
+        valid: true,
+        type: 'hierarchical',
+        baseId,
+        indices,
+    };
+}

package/dist/mem-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-id.js","sourceRoot":"","sources":["../src/mem-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;GAEG;AACH,MAAM,aAAa,GAAG,MAAM,CAAC;AAE7B;;GAEG;AACH,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;;;OAGG;IACH,OAAO,EAAE,mBAAmB;IAE5B;;;;OAIG;IACH,eAAe,EAAE,mCAAmC;CACrD,CAAC;AAEF;;GAEG;AACH,MAAM,cAAc,GAAG;IACrB,UAAU,EAAE,0BAA0B;IACtC,eAAe,EAAE,+BAA+B;IAChD,aAAa,EAAE,kCAAkC;CAClD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,OAAO;IACnC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEzE,wCAAwC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAEhD,OAAO,GAAG,aAAa,GAAG,MAAM,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAQ,EAAE,KAAK;IACpD,qBAAqB;IACrB,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,GAAG,cAAc,CAAC,eAAe,KAAK,QAAQ,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,qCAAqC;IACrC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,cAAc,CAAC,aAAa,KAAK,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,EAAE;IAC9B,+BAA+B;IAC/B,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC9C,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,cAAc,CAAC,UAAU;YAChC,OAAO,EAAE,EAAE;SACZ,CAAC;IACJ,CAAC;IAED,qDAAqD;IACrD,IAAI,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACrC,OAAO;YACL,KAAK,EAAE,IAAI;YACX,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,EAAE;SACZ,CAAC;IACJ,CAAC;IAED,4CAA4C;IAC5C,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAEjE,OAAO;QACL,KAAK,EAAE,IAAI;QACX,IAAI,EAAE,cAAc;QACpB,MAAM;QACN,OAAO;KACR,CAAC;AACJ,CAAC"}