brainclaw 1.24.0 → 1.25.0

package/dist/core/code-map/lang/typescript/config.js

@@ -0,0 +1,271 @@
+/**
+ * Bounded, local TypeScript/JavaScript resolver configuration.
+ *
+ * Only root tsconfig/jsconfig, local extends, baseUrl and paths are supported.
+ * Package extends and node_modules are deliberately never read. Any malformed,
+ * escaping, cyclic, or ambiguous configuration is invalid so callers abstain.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_EXTENDS_DEPTH = 8;
+const CONFIG_FILENAMES = ['tsconfig.json', 'jsconfig.json'];
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function toPosix(value) {
+    return value.replace(/\\/g, '/');
+}
+function configFingerprint(parts) {
+    return `sha256:${crypto.createHash('sha256').update(parts.join('\n'), 'utf8').digest('hex')}`;
+}
+/** Strip JSONC comments without changing comment-looking text inside strings. */
+function stripJsonComments(source) {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        const next = source[i + 1];
+        if (inString) {
+            out += ch;
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            i++;
+            while (i + 1 < source.length && source[i + 1] !== '\n' && source[i + 1] !== '\r')
+                i++;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            const close = source.indexOf('*/', i + 2);
+            if (close < 0)
+                return null;
+            i = close + 1;
+            continue;
+        }
+        out += ch;
+    }
+    return inString ? null : out;
+}
+/** JSONC permits trailing commas; remove them only outside quoted strings. */
+function stripTrailingCommas(source) {
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (inString) {
+            out += ch;
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === ',') {
+            let next = i + 1;
+            while (next < source.length && /\s/.test(source[next]))
+                next++;
+            if (source[next] === '}' || source[next] === ']')
+                continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+function parseJsonc(source) {
+    const withoutComments = stripJsonComments(source);
+    if (withoutComments === null)
+        return null;
+    try {
+        const parsed = JSON.parse(stripTrailingCommas(withoutComments));
+        return isObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isWithin(root, absolute) {
+    const rel = path.relative(root, absolute);
+    return rel === '' || (!path.isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${path.sep}`));
+}
+function projectRelative(root, absolute) {
+    return isWithin(root, absolute) ? toPosix(path.relative(root, absolute)) : null;
+}
+/** Resolve a config-local directory, refusing absolute and project-escaping values. */
+function localDirectory(root, configDir, value) {
+    if (path.isAbsolute(value))
+        return null;
+    return projectRelative(root, path.resolve(configDir, value));
+}
+function starCount(value) {
+    return [...value].filter((c) => c === '*').length;
+}
+function parsePaths(raw, root, configDir, baseUrl) {
+    if (!isObject(raw))
+        return null;
+    const targetDir = baseUrl === null ? configDir : path.resolve(root, baseUrl);
+    const mappings = [];
+    for (const pattern of Object.keys(raw).sort()) {
+        const values = raw[pattern];
+        const stars = starCount(pattern);
+        if (pattern.length === 0 || stars > 1 || !Array.isArray(values) || values.length === 0)
+            return null;
+        const targets = [];
+        for (const value of values) {
+            if (typeof value !== 'string' || starCount(value) > 1 || (stars === 0 && starCount(value) !== 0))
+                return null;
+            const target = localDirectory(root, targetDir, value);
+            if (target === null)
+                return null;
+            targets.push(target);
+        }
+        mappings.push({ pattern, targets });
+    }
+    return mappings;
+}
+function localExtendsPath(root, configDir, value) {
+    // Bare values name packages; never follow them, even if node_modules is present.
+    if (!value.startsWith('./') && !value.startsWith('../'))
+        return null;
+    const candidate = path.resolve(configDir, value);
+    if (!isWithin(root, candidate))
+        return null;
+    const jsonPath = path.extname(candidate) ? candidate : `${candidate}.json`;
+    return isWithin(root, jsonPath) ? jsonPath : null;
+}
+function readConfig(filename, depth, state) {
+    const empty = { baseUrl: null, paths: [] };
+    if (depth > MAX_EXTENDS_DEPTH || state.seen.has(filename) || !isWithin(state.root, filename)) {
+        return { valid: false, options: empty };
+    }
+    state.seen.add(filename);
+    let source;
+    try {
+        source = fs.readFileSync(filename, 'utf8');
+    }
+    catch {
+        return { valid: false, options: empty };
+    }
+    state.fingerprintParts.push(`${projectRelative(state.root, filename) ?? filename}\u0000${source}`);
+    const json = parseJsonc(source);
+    if (!json)
+        return { valid: false, options: empty };
+    const configDir = path.dirname(filename);
+    let inherited = empty;
+    if (json.extends !== undefined) {
+        if (typeof json.extends !== 'string')
+            return { valid: false, options: empty };
+        const parent = localExtendsPath(state.root, configDir, json.extends);
+        if (!parent)
+            return { valid: false, options: empty };
+        const parentResult = readConfig(parent, depth + 1, state);
+        if (!parentResult.valid)
+            return { valid: false, options: empty };
+        inherited = parentResult.options;
+    }
+    if (json.compilerOptions !== undefined && !isObject(json.compilerOptions))
+        return { valid: false, options: empty };
+    const options = json.compilerOptions ?? {};
+    let baseUrl = inherited.baseUrl;
+    if (options.baseUrl !== undefined) {
+        if (typeof options.baseUrl !== 'string')
+            return { valid: false, options: empty };
+        baseUrl = localDirectory(state.root, configDir, options.baseUrl);
+        if (baseUrl === null)
+            return { valid: false, options: empty };
+    }
+    let paths = inherited.paths;
+    if (options.paths !== undefined) {
+        const parsedPaths = parsePaths(options.paths, state.root, configDir, baseUrl);
+        if (!parsedPaths)
+            return { valid: false, options: empty };
+        paths = parsedPaths;
+    }
+    return { valid: true, options: { baseUrl, paths } };
+}
+/**
+ * Read exactly one root configuration. Two root configs are intentionally
+ * ambiguous: TypeScript tooling can choose based on invocation, Code Map cannot.
+ */
+export function loadTypeScriptResolutionConfig(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const found = CONFIG_FILENAMES.map((name) => path.join(root, name)).filter((filename) => fs.existsSync(filename));
+    if (found.length === 0) {
+        return { kind: 'typescript-resolution-config', fingerprint: configFingerprint([]), valid: true, baseUrl: null, paths: [] };
+    }
+    if (found.length > 1) {
+        const parts = found.map((filename) => {
+            try {
+                return `${path.basename(filename)}\u0000${fs.readFileSync(filename, 'utf8')}`;
+            }
+            catch {
+                return `${path.basename(filename)}\u0000<unreadable>`;
+            }
+        });
+        return { kind: 'typescript-resolution-config', fingerprint: configFingerprint(parts), valid: false, baseUrl: null, paths: [] };
+    }
+    const state = { root, seen: new Set(), fingerprintParts: [] };
+    const result = readConfig(found[0], 0, state);
+    return {
+        kind: 'typescript-resolution-config',
+        fingerprint: configFingerprint(state.fingerprintParts),
+        valid: result.valid,
+        baseUrl: result.valid ? result.options.baseUrl : null,
+        paths: result.valid ? result.options.paths : [],
+    };
+}
+export function isTypeScriptResolutionConfig(value) {
+    return !!value && typeof value === 'object' && value.kind === 'typescript-resolution-config';
+}
+function matchPattern(pattern, specifier) {
+    const star = pattern.indexOf('*');
+    if (star < 0)
+        return pattern === specifier ? '' : null;
+    const prefix = pattern.slice(0, star);
+    const suffix = pattern.slice(star + 1);
+    if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix))
+        return null;
+    return specifier.slice(prefix.length, specifier.length - suffix.length);
+}
+/** Map a bare specifier to project-relative candidate bases, or no candidates. */
+export function typeScriptSpecifierBases(specifier, config) {
+    if (!config?.valid)
+        return [];
+    const matches = config.paths
+        .map((mapping) => ({ mapping, wildcard: matchPattern(mapping.pattern, specifier) }))
+        .filter((match) => match.wildcard !== null);
+    // Overlapping paths patterns are intentionally not ranked: ambiguity abstains.
+    if (matches.length > 1)
+        return [];
+    if (matches.length === 1) {
+        const { mapping, wildcard } = matches[0];
+        // `parsePaths` garantit AU PLUS une `*` par cible (starCount > 1 ⇒ config invalide,
+        // donc abstention totale) : split/join et replace-première-occurrence sont ici
+        // équivalents. split/join est préféré parce qu'il reste correct même si cet
+        // invariant bougeait — et il est lisible par l'analyse statique (js/incomplete-
+        // sanitization signalait le replace sans pouvoir voir l'invariant amont).
+        return mapping.targets.map((target) => target.split('*').join(wildcard));
+    }
+    return config.baseUrl === null ? [] : [path.posix.join(config.baseUrl, specifier)];
+}
+//# sourceMappingURL=config.js.map

package/dist/core/code-map/lang/typescript/index.js

@@ -26,6 +26,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { grammarHash, grammarName, loadGrammar } from '../../wasm-loader.js';
 import { extractWithQueries } from '../query-runtime.js';
+import { isTypeScriptResolutionConfig, typeScriptSpecifierBases, } from './config.js';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** Resolve a vendored `.scm` next to this module (dist) or from the source tree. */
 function readScm(basename) {
@@ -173,10 +174,7 @@ const JS_LIKE_EXTS = new Set(['.js', '.jsx', '.mjs', '.cjs']);
  * extension, then `<candidate>/index.<ext>`. Return the FIRST that is an indexed
  * file. Bare/external specifiers (`react`, `@scope/x`) → no resolution (no edge).
  */
-function resolveTsImport(spec, fromPath, ctx) {
-    if (!spec.startsWith('./') && !spec.startsWith('../'))
-        return null; // external/bare → no edge
-    const base = path.posix.join(path.posix.dirname(fromPath), spec); // normalized project-relative
+function resolveTsCandidate(base, ctx) {
     const ext = path.posix.extname(base);
     const candidates = [];
     if (ext) {
@@ -198,6 +196,24 @@ function resolveTsImport(spec, fromPath, ctx) {
     }
     return null;
 }
+function resolveTsImport(spec, fromPath, ctx) {
+    if (spec.startsWith('./') || spec.startsWith('../')) {
+        return resolveTsCandidate(path.posix.join(path.posix.dirname(fromPath), spec), ctx);
+    }
+    const config = isTypeScriptResolutionConfig(ctx.resolverConfig) ? ctx.resolverConfig : undefined;
+    const candidates = typeScriptSpecifierBases(spec, config);
+    if (candidates.length === 0)
+        return null; // external, invalid, or ambiguous config
+    const resolved = new Set();
+    for (const candidate of candidates) {
+        const target = resolveTsCandidate(candidate, ctx);
+        if (target)
+            resolved.add(target);
+    }
+    // Do not adopt TypeScript's fallback preference when config candidates produce
+    // different indexed files: Code Map is deliberately soundness-first.
+    return resolved.size === 1 ? [...resolved][0] : null;
+}
 function isDefSourceNode(v) {
     return (typeof v === 'object' &&
         v !== null &&

package/dist/core/code-map/query.js

@@ -277,6 +277,58 @@ export function scoreEntry(entry, query) {
         score *= 0.4;
     return score;
 }
+/**
+ * Number of distinct indexed files that import a symbol (or its defining file).
+ *
+ * This is deliberately a tie-breaker, not a broad popularity boost: a precise
+ * textual match must always beat a merely popular substring match. The symbol
+ * and file reverse indexes can name the same importer, so count their UNION to
+ * avoid giving named imports a double bonus over namespace/default imports.
+ */
+export function importCentrality(entry, resolutionIndex) {
+    if (!resolutionIndex)
+        return 0;
+    const importers = new Set();
+    for (const dep of resolutionIndex.dependents_by_symbol[entry.node_id] ?? [])
+        importers.add(dep.path);
+    for (const dep of resolutionIndex.dependents_by_file[entry.path] ?? [])
+        importers.add(dep.path);
+    return importers.size;
+}
+/** A test-only helper is a weak orientation point when a file has real exports too. */
+function isTestHelperSymbol(name) {
+    const normalized = normIdent(name);
+    return (name.startsWith('_') ||
+        /(?:^|_)(?:test|tests|mock|stub|fixture|reset)(?:_|$)/i.test(name) ||
+        normalized.includes('fortest') ||
+        normalized.includes('fortests'));
+}
+/**
+ * Pick one meaningful definition per file for the reading-list explanation.
+ * A path brief resolves all symbols in that file; repeatedly adding +12 for
+ * each one made the result's reason depend on index order, which could select
+ * an internal `__reset…ForTests` helper ahead of the public entry point.
+ */
+function representativeDefinitions(defining) {
+    const byPath = new Map();
+    const relevance = (entry) => {
+        let score = entry.score_hint * 100; // public definitions before internals
+        if (entry.subtype === 'component' || entry.subtype === 'hook')
+            score += 2;
+        if (isTestHelperSymbol(entry.name))
+            score -= 50;
+        return score;
+    };
+    for (const entry of defining) {
+        const previous = byPath.get(entry.path);
+        if (!previous ||
+            relevance(entry) > relevance(previous) ||
+            (relevance(entry) === relevance(previous) && entry.name.localeCompare(previous.name) < 0)) {
+            byPath.set(entry.path, entry);
+        }
+    }
+    return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
 function resolveRoot(ctx) {
     if (ctx.projectRoot)
         return ctx.projectRoot;
@@ -325,6 +377,7 @@ export function findInStore(query, ctx, checker, acc) {
     const root = resolveRoot(ctx);
     const maxBytes = maxParseBytes(ctx);
     const candidates = gatherSymbolEntries(index, query);
+    const resolutionIndex = readResolutionIndex(ctx.cwd, ctx.preferredDirName);
     const ranked = [];
     for (const entry of candidates) {
         // §6.1 — lazy validate before serving as confident.
@@ -332,17 +385,23 @@ export function findInStore(query, ctx, checker, acc) {
         if (!confident)
             continue;
         ranked.push({
-            node_id: entry.node_id,
-            name: entry.name,
-            path: entry.path,
-            file_id: entry.file_id,
-            kind: entry.kind,
-            subtype: entry.subtype ?? null,
-            score: scoreEntry(entry, query),
+            match: {
+                node_id: entry.node_id,
+                name: entry.name,
+                path: entry.path,
+                file_id: entry.file_id,
+                kind: entry.kind,
+                subtype: entry.subtype ?? null,
+                score: scoreEntry(entry, query),
+            },
+            centrality: importCentrality(entry, resolutionIndex),
         });
     }
-    ranked.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.name.localeCompare(b.name));
-    return { matches: ranked, base, hasIndex: true, emptyCandidates: candidates.length === 0, acc };
+    ranked.sort((a, b) => b.match.score - a.match.score ||
+        b.centrality - a.centrality ||
+        a.match.path.localeCompare(b.match.path) ||
+        a.match.name.localeCompare(b.match.name));
+    return { matches: ranked.map(({ match }) => match), base, hasIndex: true, emptyCandidates: candidates.length === 0, acc };
 }
 export function find(query, limit, ctx) {
     const checker = makeLazyChecker();
@@ -436,7 +495,7 @@ function rankFiles(defining, forwardRows, reverseRows, symbolsIndex, importsInde
     };
     // 1. defining files — strongest, non-graph.
     const definingDirs = new Set();
-    for (const entry of defining) {
+    for (const entry of representativeDefinitions(defining)) {
         const subtypeNote = entry.subtype ? ` (${entry.subtype})` : '';
         bump(entry.path, entry.file_id, `defines matching symbol ${entry.name}${subtypeNote}`, 12, false);
         definingDirs.add(path.posix.dirname(entry.path.replace(/\\/g, '/')));
@@ -604,13 +663,17 @@ function looksLikePathTarget(target) {
 /** Find files whose path matches the target directly (path-target briefs). */
 function filesMatchingPath(symbolsIndex, target) {
     const norm = target.replace(/\\/g, '/');
-    const seenPaths = new Set();
+    // Keep every symbol in the matching file. `rankFiles()` selects the one
+    // meaningful representative for the reason; deduping by path here used to
+    // retain whichever token bucket happened to be visited first (often an
+    // internal `__reset…ForTests` helper) and discarded the public entry point.
+    const seenNodeIds = new Set();
     const out = [];
     for (const bucket of Object.values(symbolsIndex.entries)) {
         for (const entry of bucket) {
             const p = entry.path.replace(/\\/g, '/');
-            if ((p === norm || p.endsWith(`/${norm}`) || p.includes(norm)) && !seenPaths.has(entry.path)) {
-                seenPaths.add(entry.path);
+            if ((p === norm || p.endsWith(`/${norm}`) || p.includes(norm)) && !seenNodeIds.has(entry.node_id)) {
+                seenNodeIds.add(entry.node_id);
                 out.push(entry);
             }
         }

package/dist/core/code-map/resolve.js

@@ -77,6 +77,7 @@ export async function resolveProjectImports(input) {
     const ctx = {
         fileExists: (rel) => fileLang.has(toPosix(rel)),
         langOfFile: (rel) => fileLang.get(toPosix(rel)),
+        resolverConfig: input.resolverConfig,
     };
     // Target-file lookups for B: path -> shard, and a memoized importable index
     // (name -> importable symbols) per target file (built lazily, reused across importers).

package/dist/core/code-map/types.js

@@ -243,6 +243,19 @@ export const ImportsIndexSchema = z.object({
     entries: z.record(z.string(), z.array(ImportIndexEntrySchema)).default({}),
 });
 // --- resolution index (P1d) — reverse dependency maps over the P1c graph ---
+/**
+ * One concrete resolved edge which made an importer depend on a target. Kept
+ * alongside the compact aggregate fields on {@link DependencyIndexEntrySchema}
+ * so impact analysis can explain every relation without re-reading all shards.
+ */
+export const DependencyReasonSchema = z.object({
+    kind: z.enum(['resolves_to', 'imports_symbol']),
+    module: z.string().optional(),
+    imported: z.array(z.string()).default([]),
+    confidence: z.number().optional(),
+    /** Source line of the import edge when the extractor supplied one. */
+    source_line: z.number().int().nullable().optional(),
+});
 /**
  * One DEPENDENT of a target (file or symbol): the importing file + enough metadata
  * to lazy-validate it (file_id) and explain WHY it appears (module specifier the
@@ -259,6 +272,8 @@ export const DependencyIndexEntrySchema = z.object({
     imported: z.array(z.string()).default([]),
     /** Resolution edge confidence (inherited from the A file resolution). */
     confidence: z.number().optional(),
+    /** Every resolved edge merged into this importer/target row, source ordered. */
+    reasons: z.array(DependencyReasonSchema).default([]),
 });
 /**
  * Reverse dependency index (P1d): "who imports this target". Built at refresh from

package/dist/core/federation-pull.js

@@ -10,8 +10,14 @@ import { verifyInboundBatch } from './federation-inbound.js';
 import { loadEpochPrivateKey } from './federation-keyring.js';
 import { localIdForOpaque, rememberOpaqueId } from './federation-opaque-ids.js';
 import { addStep, createPlan, updatePlan, updateStep } from './operations/plan.js';
+import { createConstraint, createDecision, createTrap } from './operations/memory-write.js';
+import { updateMemoryItem } from './operations/memory-mutation.js';
+import { createSequence, updateSequence } from './sequence.js';
+import { generateRuntimeNoteId, listRuntimeNotes, saveRuntimeNote } from './runtime.js';
+import { HandoffSchema } from './schema.js';
+import { generateIdWithLabel, nowISO } from './ids.js';
+import { mutateState } from './state.js';
 import { memoryDir, writeFileAtomic } from './io.js';
-import { nowISO } from './ids.js';
 import { loadConnectionState, recordRevision, saveConnectionState } from './federation-state.js';
 const INBOUND_SCHEMA = 'brainclaw.federation-inbound-pull/v1';
 const INBOUND_FILE = 'inbound-pull.json';
@@ -164,6 +170,55 @@ function tagsOf(content) {
 function priorityOf(value) {
     return value === 'low' || value === 'medium' || value === 'high' || value === 'critical' ? value : undefined;
 }
+function statusOf(value, accepted) {
+    return typeof value === 'string' && accepted.includes(value) ? value : undefined;
+}
+function authorOf(accepted) {
+    // L'identité de signature a été vérifiée par verifyInboundBatch contre le roster :
+    // elle est sûre à conserver comme provenance locale, sans prétendre connaître un nom.
+    return `federation:${accepted.envelope.origin_sig.key_id}`;
+}
+function textAndTagsPatch(text, tags) {
+    return { text, ...(tags ? { tags } : {}) };
+}
+/**
+ * Handoff has no standalone create operation yet. This goes through mutateState, the same
+ * canonical mutation pipeline used by its lifecycle operations: it never writes an entity
+ * JSON file directly. The remote projection does not carry `from`/`to`, so their local
+ * receiver values deliberately describe the federation hop rather than invent source data.
+ */
+function saveFederatedHandoff(input, cwd) {
+    if (input.id) {
+        mutateState((state) => {
+            const current = state.open_handoffs.find((handoff) => handoff.id === input.id);
+            if (!current)
+                throw new Error(`handoff with id '${input.id}' not found locally despite its opaque mapping`);
+            const next = HandoffSchema.parse({
+                ...current,
+                text: input.text,
+                tags: input.tags ?? current.tags,
+                status: input.status ?? current.status,
+            });
+            Object.assign(current, next);
+        }, cwd);
+        return input.id;
+    }
+    const { id, short_label } = generateIdWithLabel('open_handoffs', cwd);
+    mutateState((state) => {
+        state.open_handoffs.push(HandoffSchema.parse({
+            id,
+            short_label,
+            from: input.author,
+            to: 'local',
+            text: input.text,
+            created_at: nowISO(),
+            author: input.author,
+            status: input.status ?? 'open',
+            tags: input.tags ?? [],
+        }));
+    }, cwd);
+    return id;
+}
 class DeferredMaterialization extends Error {
 }
 /**
@@ -213,8 +268,101 @@ function materialize(accepted, state, cwd) {
         rememberOpaqueId(state.cloud_project_id, created.stepId, opaque, cwd);
         return;
     }
-    // Les familles sans mutation canonique correspondante sont différées. Les accepter dans
-    // high_water les ferait disparaître du feed sans jamais atteindre le magasin local.
+    const author = authorOf(accepted);
+    const text = content['text'];
+    if (accepted.kind === 'decision') {
+        if (existing) {
+            updateMemoryItem({ id: existing, type: 'decision', patch: textAndTagsPatch(text, tags) }, cwd);
+            return;
+        }
+        const created = createDecision({ text, author, tags }, cwd);
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'constraint') {
+        const status = statusOf(accepted.envelope.meta.status.object, ['active', 'resolved', 'expired']);
+        if (existing) {
+            updateMemoryItem({
+                id: existing,
+                type: 'constraint',
+                patch: { ...textAndTagsPatch(text, tags), ...(status ? { status } : {}) },
+            }, cwd);
+            return;
+        }
+        const created = createConstraint({ text, author, tags }, cwd);
+        // createConstraint correctly owns ID/provenance creation; its lifecycle starts at active,
+        // so apply a projected terminal state through the same mutation path afterwards.
+        if (status && status !== 'active') {
+            updateMemoryItem({ id: created.id, type: 'constraint', patch: { status } }, cwd);
+        }
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'trap') {
+        const status = statusOf(accepted.envelope.meta.status.object, ['active', 'resolved', 'expired']);
+        const severity = accepted.envelope.meta.priority === 'low' || accepted.envelope.meta.priority === 'medium'
+            ? accepted.envelope.meta.priority
+            : accepted.envelope.meta.priority === 'high' || accepted.envelope.meta.priority === 'critical'
+                ? 'high'
+                : undefined;
+        if (existing) {
+            updateMemoryItem({
+                id: existing,
+                type: 'trap',
+                patch: {
+                    ...textAndTagsPatch(text, tags),
+                    ...(status ? { status } : {}),
+                    ...(severity ? { severity } : {}),
+                },
+            }, cwd);
+            return;
+        }
+        const created = createTrap({ text, author, tags, status, severity }, cwd);
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'handoff') {
+        const status = statusOf(accepted.envelope.meta.status.object, ['open', 'accepted', 'closed']);
+        const id = saveFederatedHandoff({ id: existing, text, tags, status, author }, cwd);
+        if (!existing)
+            rememberOpaqueId(state.cloud_project_id, id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'sequence') {
+        const status = statusOf(accepted.envelope.meta.status.object, ['draft', 'active', 'archived']);
+        if (existing) {
+            updateSequence({ id: existing, name: text, tags, status }, cwd);
+            return;
+        }
+        const created = createSequence({ name: text, author, tags, status }, cwd);
+        rememberOpaqueId(state.cloud_project_id, created.id, opaque, cwd);
+        return;
+    }
+    if (accepted.kind === 'runtime_note') {
+        if (existing) {
+            const current = listRuntimeNotes({ visibility: 'all', includeAllHosts: true }, cwd)
+                .find((note) => note.id === existing);
+            if (!current)
+                throw new Error(`runtime_note with id '${existing}' not found locally despite its opaque mapping`);
+            saveRuntimeNote({ ...current, text, tags: tags ?? current.tags }, cwd);
+            return;
+        }
+        const id = generateRuntimeNoteId();
+        saveRuntimeNote({
+            id,
+            agent: 'federation',
+            agent_id: accepted.envelope.origin_sig.key_id,
+            text,
+            created_at: nowISO(),
+            tags: tags ?? [],
+            visibility: 'shared',
+            note_type: 'observation',
+        }, cwd);
+        rememberOpaqueId(state.cloud_project_id, id, opaque, cwd);
+        return;
+    }
+    // Les familles hors projection restent dans le journal : les accepter dans high_water
+    // les ferait disparaître du feed sans jamais atteindre le magasin local.
     throw new DeferredMaterialization(`kind '${accepted.kind}' sans mutation canonique de réception.`);
 }
 /**