@exellix/graph-engine 6.0.0

package/dist/src/runtime/localSkills/deterministicRule.js

@@ -0,0 +1,196 @@
+/**
+ * deterministic-rule — local deterministic skill.
+ *
+ * Evaluates a rule table against executionMemory (or a custom root path) and returns
+ * the first matching rule's output, a full evaluation trace, and optional sensitivity
+ * analysis for UNKNOWN-tagged inputs (DQ-1 swing calculation).
+ *
+ * Node config (in node.taskConfiguration):
+ *   rules            : Rule[]    — ordered list of rules
+ *   firstMatchWins   : boolean   — default true; when false all matching rules fire
+ *   defaultOutput    : object?   — emitted when no rule matches
+ *   sensitivityAnalysis : SensitivityAnalysisConfig? — only used by DQ-1
+ *
+ * Each rule:
+ *   id        : string
+ *   label?    : string         — human-readable description
+ *   condition : Condition      — nested logical condition
+ *   output    : Record<string,unknown>  — merged into result when this rule fires
+ *   stopOnMatch? : boolean     — default true (respected when firstMatchWins=true)
+ *
+ * Condition operators (leaf):
+ *   { path, eq }       — strict equality
+ *   { path, in }       — value in array
+ *   { path, gte }      — >= number
+ *   { path, gt }       — > number
+ *   { path, lte }      — <= number
+ *   { path, lt }       — < number
+ *   { path, exists }   — boolean (truthy check when true, falsy check when false)
+ *   { path, contains } — string or array contains value
+ *   { path, regex }    — string matches pattern
+ * Compound:
+ *   { all: Condition[] }
+ *   { any: Condition[] }
+ *   { not: Condition }
+ *
+ * Output:
+ * {
+ *   matched        : boolean
+ *   rule_id        : string | null
+ *   rule_label     : string | null
+ *   output         : Record<string,unknown>
+ *   evaluation_trace : { ruleId, matched, shortCircuited }[]
+ *   sensitivity?   : SensitivityResult      — only when sensitivityAnalysis is configured
+ * }
+ */
+import { resolveDotPath } from './utils.js';
+// ─── Condition evaluation ──────────────────────────────────────────────────────
+function evalCondition(cond, root, pathOpts) {
+    if ('all' in cond) {
+        return cond.all.every((c) => evalCondition(c, root, pathOpts));
+    }
+    if ('any' in cond) {
+        return cond.any.some((c) => evalCondition(c, root, pathOpts));
+    }
+    if ('not' in cond) {
+        return !evalCondition(cond.not, root, pathOpts);
+    }
+    const leaf = cond;
+    const val = resolveDotPath(root, leaf.path, pathOpts);
+    if ('exists' in leaf) {
+        const e = leaf.exists;
+        return e ? val != null : val == null;
+    }
+    if ('eq' in leaf)
+        return val === leaf.eq;
+    if ('in' in leaf) {
+        const arr = leaf.in;
+        return Array.isArray(arr) && arr.includes(val);
+    }
+    if ('gte' in leaf)
+        return typeof val === 'number' && val >= leaf.gte;
+    if ('gt' in leaf)
+        return typeof val === 'number' && val > leaf.gt;
+    if ('lte' in leaf)
+        return typeof val === 'number' && val <= leaf.lte;
+    if ('lt' in leaf)
+        return typeof val === 'number' && val < leaf.lt;
+    if ('contains' in leaf) {
+        const target = leaf.contains;
+        if (Array.isArray(val))
+            return val.includes(target);
+        if (typeof val === 'string' && typeof target === 'string')
+            return val.includes(target);
+        return false;
+    }
+    if ('regex' in leaf) {
+        if (typeof val !== 'string')
+            return false;
+        return new RegExp(leaf.regex).test(val);
+    }
+    return false;
+}
+// ─── Rule evaluation (single pass) ────────────────────────────────────────────
+function evaluateRules(rules, root, firstMatchWins, pathOpts) {
+    const trace = [];
+    let mergedOutput = {};
+    let matchedId = null;
+    let matchedLabel = null;
+    let anyMatched = false;
+    for (const rule of rules) {
+        const hit = evalCondition(rule.condition, root, pathOpts);
+        trace.push({ ruleId: rule.id, matched: hit });
+        if (hit) {
+            anyMatched = true;
+            matchedId = rule.id;
+            matchedLabel = rule.label ?? null;
+            mergedOutput = { ...mergedOutput, ...rule.output };
+            if (firstMatchWins) {
+                // Mark remaining rules as short-circuited
+                for (let i = trace.length; i < rules.length; i++) {
+                    trace.push({ ruleId: rules[i].id, matched: false, shortCircuited: true });
+                }
+                break;
+            }
+        }
+    }
+    return {
+        matched: anyMatched,
+        rule_id: matchedId,
+        rule_label: matchedLabel,
+        output: mergedOutput,
+        trace,
+    };
+}
+// ─── Sensitivity analysis ──────────────────────────────────────────────────────
+function runSensitivity(cfg, rules, baseRoot, firstMatchWins, basePriority, pathOpts) {
+    const unknowns = (resolveDotPath(baseRoot, cfg.unknownsPath, pathOpts) ?? []);
+    const rankOf = (p) => {
+        if (p == null)
+            return cfg.priorityRank.length;
+        const idx = cfg.priorityRank.indexOf(p);
+        return idx === -1 ? cfg.priorityRank.length : idx;
+    };
+    const entries = [];
+    for (const u of unknowns) {
+        if (u.tag !== 'UNKNOWN' || !u.path)
+            continue;
+        const rootStr = JSON.stringify(baseRoot);
+        const applySubstitute = (rootObj, path, value) => {
+            const parts = path.split('.');
+            const clone = JSON.parse(JSON.stringify(rootObj));
+            let cur = clone;
+            for (let i = 0; i < parts.length - 1; i++) {
+                if (cur[parts[i]] == null)
+                    cur[parts[i]] = {};
+                cur = cur[parts[i]];
+            }
+            cur[parts[parts.length - 1]] = value;
+            return clone;
+        };
+        const upRoot = applySubstitute(JSON.parse(rootStr), u.path, u.up_substitute);
+        const downRoot = applySubstitute(JSON.parse(rootStr), u.path, u.down_substitute);
+        const upResult = evaluateRules(rules, upRoot, firstMatchWins, pathOpts);
+        const downResult = evaluateRules(rules, downRoot, firstMatchWins, pathOpts);
+        const upPriority = upResult.matched
+            ? (String(upResult.output[cfg.priorityField] ?? '') || null)
+            : null;
+        const downPriority = downResult.matched
+            ? (String(downResult.output[cfg.priorityField] ?? '') || null)
+            : null;
+        const swing = Math.abs(rankOf(upPriority) - rankOf(downPriority));
+        entries.push({
+            unknown_id: u.id,
+            up_substitute: u.up_substitute,
+            down_substitute: u.down_substitute,
+            up_priority: upPriority,
+            down_priority: downPriority,
+            swing,
+        });
+    }
+    return {
+        any_high_swing: entries.some((e) => e.swing >= 2),
+        entries,
+    };
+}
+// ─── Public entry point ────────────────────────────────────────────────────────
+export function runDeterministicRule(cfg, executionMemory, pathOpts) {
+    const rules = Array.isArray(cfg.rules) ? cfg.rules : [];
+    const firstMatchWins = cfg.firstMatchWins !== false;
+    const { matched, rule_id, rule_label, output, trace } = evaluateRules(rules, executionMemory, firstMatchWins, pathOpts);
+    const finalOutput = matched ? output : (cfg.defaultOutput ?? {});
+    const result = {
+        matched,
+        rule_id,
+        rule_label,
+        output: finalOutput,
+        evaluation_trace: trace,
+    };
+    if (cfg.sensitivityAnalysis) {
+        const basePriority = matched
+            ? (String(output[cfg.sensitivityAnalysis.priorityField] ?? '') || null)
+            : null;
+        result.sensitivity = runSensitivity(cfg.sensitivityAnalysis, rules, executionMemory, firstMatchWins, basePriority, pathOpts);
+    }
+    return result;
+}

package/dist/src/runtime/localSkills/index.d.ts

@@ -0,0 +1,12 @@
+export { resolveDotPath } from './utils.js';
+export { runScopedDataReader, scopedAnswerDocToFlatFields, runScopedDataReaderPack } from './scopedDataReader.js';
+export type { ScopedDataReaderConfig, ScopedDataReaderOutput, ScopedDataReaderPackOutput, ScopedDataReaderPackSlot, } from './scopedDataReader.js';
+export { runDeterministicRule } from './deterministicRule.js';
+export type { DeterministicRuleConfig, DeterministicRuleOutput, Rule, Condition, SensitivityAnalysisConfig, SensitivityResult, } from './deterministicRule.js';
+export { runScopedAnswerWriter } from './scopedAnswerWriter.js';
+export type { ScopedAnswerWriterConfig, ScopedAnswerWriterOutput, } from './scopedAnswerWriter.js';
+export { runScopedAnswerAssembler } from './scopedAnswerAssembler.js';
+export type { ScopedAnswerAssemblerConfig, ScopedAnswerAssemblerOutput, } from './scopedAnswerAssembler.js';
+export declare const LOCAL_SKILL_KEYS: readonly ["scoped-data-reader", "deterministic-rule", "scoped-answer-writer", "scoped-answer-assembler"];
+export type LocalSkillKey = (typeof LOCAL_SKILL_KEYS)[number];
+export declare function isLocalSkillKey(key: string): key is LocalSkillKey;

package/dist/src/runtime/localSkills/index.js

@@ -0,0 +1,14 @@
+export { resolveDotPath } from './utils.js';
+export { runScopedDataReader, scopedAnswerDocToFlatFields, runScopedDataReaderPack } from './scopedDataReader.js';
+export { runDeterministicRule } from './deterministicRule.js';
+export { runScopedAnswerWriter } from './scopedAnswerWriter.js';
+export { runScopedAnswerAssembler } from './scopedAnswerAssembler.js';
+export const LOCAL_SKILL_KEYS = [
+    'scoped-data-reader',
+    'deterministic-rule',
+    'scoped-answer-writer',
+    'scoped-answer-assembler',
+];
+export function isLocalSkillKey(key) {
+    return LOCAL_SKILL_KEYS.includes(key);
+}

package/dist/src/runtime/localSkills/memorixItemToScopedOutput.d.ts

@@ -0,0 +1,7 @@
+import type { FetchMemorixItemResponse } from '@x12i/memorix-retrieval';
+import type { ScopedDataReaderOutput } from './scopedDataReader.js';
+/**
+ * Flatten {@link fetchMemorixItem} sections into graph `fields.*` paths.
+ * Works across content types — whatever the item descriptor surfaces in sections.
+ */
+export declare function memorixItemToScopedOutput(item: FetchMemorixItemResponse, entityId: string): ScopedDataReaderOutput;

package/dist/src/runtime/localSkills/memorixItemToScopedOutput.js

@@ -0,0 +1,104 @@
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function looksLikeFieldEnvelope(v) {
+    return isPlainObject(v) && 'value' in v;
+}
+/** Expand a Memorix content-type object map into flat execution fields. */
+function mergeContentTypeBucket(bucketName, raw, fields, unknowns) {
+    for (const [leafKey, leafVal] of Object.entries(raw)) {
+        const outKey = `${bucketName}.${leafKey}`;
+        if (looksLikeFieldEnvelope(leafVal)) {
+            const f = leafVal;
+            fields[outKey] = {
+                value: f.value,
+                fieldPath: typeof f.fieldPath === 'string' ? f.fieldPath : outKey,
+                ...(f.description != null ? { description: f.description } : {}),
+                ...(f.reasoning != null ? { reasoning: f.reasoning } : {}),
+                ...(f.linked != null ? { linked: f.linked } : {}),
+            };
+            if (f.value == null)
+                unknowns.push(outKey);
+        }
+        else if (leafVal !== undefined) {
+            fields[outKey] = { value: leafVal, fieldPath: outKey };
+            if (leafVal == null)
+                unknowns.push(outKey);
+        }
+    }
+}
+function addScalarOrEnvelope(key, raw, fields, unknowns) {
+    if (looksLikeFieldEnvelope(raw)) {
+        const f = raw;
+        fields[key] = {
+            value: f.value,
+            fieldPath: typeof f.fieldPath === 'string' ? f.fieldPath : '',
+            ...(f.description != null ? { description: f.description } : {}),
+            ...(f.reasoning != null ? { reasoning: f.reasoning } : {}),
+            ...(f.linked != null ? { linked: f.linked } : {}),
+        };
+        if (f.value == null)
+            unknowns.push(key);
+        return;
+    }
+    if (raw !== undefined) {
+        fields[key] = { value: raw, fieldPath: '' };
+        if (raw == null)
+            unknowns.push(key);
+    }
+}
+/**
+ * Flatten {@link fetchMemorixItem} sections into graph `fields.*` paths.
+ * Works across content types — whatever the item descriptor surfaces in sections.
+ */
+export function memorixItemToScopedOutput(item, entityId) {
+    const errors = item.issues?.filter((i) => i.severity === 'error') ?? [];
+    if (errors.length > 0) {
+        return {
+            answer_status: 'error',
+            fields: {},
+            freshness: null,
+            unknowns: [],
+            entity_id: entityId,
+            error: errors.map((e) => e.message).join('; '),
+        };
+    }
+    const fields = {};
+    const unknowns = [];
+    for (const section of item.sections) {
+        for (const [key, raw] of Object.entries(section.fields)) {
+            if (isPlainObject(raw) && !looksLikeFieldEnvelope(raw)) {
+                const keys = Object.keys(raw);
+                const looksLikeBucket = keys.length > 0 &&
+                    (key === 'inferences' ||
+                        key === 'decisions' ||
+                        keys.every((k) => looksLikeFieldEnvelope(raw[k]) || raw[k] === null || typeof raw[k] !== 'object'));
+                if (looksLikeBucket) {
+                    mergeContentTypeBucket(key, raw, fields, unknowns);
+                    continue;
+                }
+            }
+            addScalarOrEnvelope(key, raw, fields, unknowns);
+        }
+    }
+    const hasData = Object.keys(fields).length > 0;
+    if (!hasData) {
+        return {
+            answer_status: 'not_found',
+            fields: {},
+            freshness: null,
+            unknowns: [],
+            entity_id: entityId,
+        };
+    }
+    const flat = item.sections.flatMap((s) => Object.entries(s.fields));
+    const scopedAtRaw = flat.find(([k]) => k === 'scopedAt')?.[1] ?? flat.find(([k]) => k === 'modifiedAt')?.[1];
+    const scopedAt = typeof scopedAtRaw === 'string' ? scopedAtRaw : undefined;
+    return {
+        answer_status: 'answered',
+        fields,
+        freshness: scopedAt ? { scopedAt } : null,
+        unknowns,
+        entity_id: entityId,
+    };
+}

package/dist/src/runtime/localSkills/memorixRuntime.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lazy Memorix retrieval + writer clients for local scoped-data skills.
+ */
+import { type MemorixRetrievalClient } from '@x12i/memorix-retrieval';
+import { type MemorixWriterClient } from '@x12i/memorix-writer';
+export declare function getMemorixRetrievalClient(): Promise<MemorixRetrievalClient>;
+export declare function getMemorixWriterClient(): Promise<MemorixWriterClient>;
+/** Closes Memorix retrieval + writer clients. Call on shutdown. */
+export declare function shutdownMemorixRuntime(): Promise<void>;

package/dist/src/runtime/localSkills/memorixRuntime.js

@@ -0,0 +1,70 @@
+/**
+ * Lazy Memorix retrieval + writer clients for local scoped-data skills.
+ */
+import { applyMemorixEnvBridgeToProcess, createMemorixRetrievalStackFromEnv, fetchMemorixItem, } from '@x12i/memorix-retrieval';
+import { createMemorixWriterFromEnv, } from '@x12i/memorix-writer';
+function cataloxForWriter(retrievalCatalox, appId) {
+    return {
+        async getCatalogItem(catalogId, itemId) {
+            const result = await retrievalCatalox.getCatalogItem({ appId }, catalogId, itemId);
+            if (result.outcome !== 'found')
+                return null;
+            return { data: result.item.data };
+        },
+    };
+}
+let _stack = null;
+let _stackPromise = null;
+let _writer = null;
+let _writerPromise = null;
+async function getOrInitStack() {
+    if (_stack)
+        return _stack;
+    if (_stackPromise)
+        return _stackPromise;
+    _stackPromise = (async () => {
+        applyMemorixEnvBridgeToProcess();
+        const stack = await createMemorixRetrievalStackFromEnv();
+        _stack = stack;
+        _stackPromise = null;
+        return stack;
+    })();
+    return _stackPromise;
+}
+export async function getMemorixRetrievalClient() {
+    const stack = await getOrInitStack();
+    return stack.client;
+}
+export async function getMemorixWriterClient() {
+    if (_writer)
+        return _writer;
+    if (_writerPromise)
+        return _writerPromise;
+    _writerPromise = (async () => {
+        const stack = await getOrInitStack();
+        const retrievalClient = stack.client;
+        const writer = await createMemorixWriterFromEnv({
+            appId: stack.appId,
+            catalox: cataloxForWriter(stack.catalox, stack.appId),
+            processEnv: stack.client.processEnv,
+            retrieval: {
+                fetchMemorixItem: (args) => fetchMemorixItem(retrievalClient, args),
+            },
+        });
+        _writer = writer;
+        _writerPromise = null;
+        return writer;
+    })();
+    return _writerPromise;
+}
+/** Closes Memorix retrieval + writer clients. Call on shutdown. */
+export async function shutdownMemorixRuntime() {
+    const writer = _writer;
+    const stack = _stack;
+    _writer = null;
+    _writerPromise = null;
+    _stack = null;
+    _stackPromise = null;
+    await writer?.close?.().catch(() => undefined);
+    await stack?.client.close?.().catch(() => undefined);
+}

package/dist/src/runtime/localSkills/memorixScopedConfig.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Memorix descriptor ids for scoped local skills (Catalox-backed).
+ */
+export declare const DEFAULT_SCOPED_CONTENT_TYPES: readonly ["inferences", "decisions"];
+export type ScopedContentType = (typeof DEFAULT_SCOPED_CONTENT_TYPES)[number];
+export type MemorixScopedSkillConfig = {
+    memorixItemDescriptorId?: string;
+    itemDescriptorId?: string;
+    /** Per content-type write descriptor ids (default: content type name, e.g. `inferences`). */
+    memorixWriteDescriptors?: Partial<Record<string, string>>;
+    /** @deprecated Use {@link memorixWriteDescriptors}. */
+    memorixWriteDescriptorId?: string;
+    writeDescriptorId?: string;
+};
+export declare function resolveMemorixItemDescriptorId(cfg: MemorixScopedSkillConfig): string | undefined;
+export declare function resolveMemorixWriteDescriptorId(cfg: MemorixScopedSkillConfig, contentType: string): string;

package/dist/src/runtime/localSkills/memorixScopedConfig.js

@@ -0,0 +1,18 @@
+/**
+ * Memorix descriptor ids for scoped local skills (Catalox-backed).
+ */
+export const DEFAULT_SCOPED_CONTENT_TYPES = ['inferences', 'decisions'];
+export function resolveMemorixItemDescriptorId(cfg) {
+    return cfg.memorixItemDescriptorId?.trim() || cfg.itemDescriptorId?.trim() || undefined;
+}
+export function resolveMemorixWriteDescriptorId(cfg, contentType) {
+    const mapped = cfg.memorixWriteDescriptors?.[contentType]?.trim();
+    if (mapped)
+        return mapped;
+    if (contentType === 'inferences' || contentType === 'decisions') {
+        const legacy = cfg.memorixWriteDescriptorId?.trim() || cfg.writeDescriptorId?.trim();
+        if (legacy && contentType === 'inferences')
+            return legacy;
+    }
+    return contentType;
+}

package/dist/src/runtime/localSkills/scopedAnswerAssembler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * scoped-answer-assembler — local skill.
+ *
+ * Builds the object **`{ inferences, decisions }`** from executionMemory paths
+ * before **`scoped-answer-writer`** persists it to Memorix entity content types. Names reflect
+ * that we store **learned inferences** and **decisions**, not “verdicts” alone.
+ *
+ * Metadata:
+ *   mergeInferencePaths?: string[]  — dot-paths to plain objects (shallow-merge keys into inferences)
+ *   mergeDecisionPaths?: string[]    — same for decisions (later paths win on key collision)
+ *
+ * Skill key: **`scoped-answer-assembler`**.
+ */
+import { type ResolveDotPathOpts } from './utils.js';
+export type ScopedAnswerAssemblerConfig = {
+    mergeInferencePaths?: string[];
+    mergeDecisionPaths?: string[];
+};
+export type ScopedAnswerAssemblerOutput = {
+    inferences: Record<string, unknown>;
+    decisions: Record<string, unknown>;
+};
+export declare function runScopedAnswerAssembler(cfg: ScopedAnswerAssemblerConfig, executionMemory: unknown, pathOpts?: ResolveDotPathOpts): ScopedAnswerAssemblerOutput;

package/dist/src/runtime/localSkills/scopedAnswerAssembler.js

@@ -0,0 +1,35 @@
+/**
+ * scoped-answer-assembler — local skill.
+ *
+ * Builds the object **`{ inferences, decisions }`** from executionMemory paths
+ * before **`scoped-answer-writer`** persists it to Memorix entity content types. Names reflect
+ * that we store **learned inferences** and **decisions**, not “verdicts” alone.
+ *
+ * Metadata:
+ *   mergeInferencePaths?: string[]  — dot-paths to plain objects (shallow-merge keys into inferences)
+ *   mergeDecisionPaths?: string[]    — same for decisions (later paths win on key collision)
+ *
+ * Skill key: **`scoped-answer-assembler`**.
+ */
+import { resolveDotPath } from './utils.js';
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function mergeFromPaths(executionMemory, paths, bucket, pathOpts) {
+    for (const p of paths ?? []) {
+        const v = resolveDotPath(executionMemory, p, pathOpts);
+        if (!isPlainObject(v))
+            continue;
+        for (const [k, val] of Object.entries(v)) {
+            if (val !== undefined)
+                bucket[k] = val;
+        }
+    }
+}
+export function runScopedAnswerAssembler(cfg, executionMemory, pathOpts) {
+    const inferences = {};
+    const decisions = {};
+    mergeFromPaths(executionMemory, cfg.mergeInferencePaths, inferences, pathOpts);
+    mergeFromPaths(executionMemory, cfg.mergeDecisionPaths, decisions, pathOpts);
+    return { inferences, decisions };
+}

package/dist/src/runtime/localSkills/scopedAnswerFields.d.ts

@@ -0,0 +1,12 @@
+export type ScopedAnswerField = {
+    value: unknown;
+    fieldPath: string;
+    description?: string;
+    reasoning?: string;
+    linked?: boolean;
+};
+/** Flatten nested or legacy `answer` documents into graph execution field maps. */
+export declare function scopedAnswerDocToFlatFields(rawAnswer: Record<string, unknown>): {
+    fields: Record<string, ScopedAnswerField>;
+    unknowns: string[];
+};

package/dist/src/runtime/localSkills/scopedAnswerFields.js

@@ -0,0 +1,66 @@
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function looksLikeFieldEnvelope(v) {
+    return isPlainObject(v) && 'value' in v;
+}
+function isNestedAnswerShape(raw) {
+    const inf = raw.inferences;
+    const dec = raw.decisions;
+    if (inf !== undefined && isPlainObject(inf))
+        return true;
+    if (dec !== undefined && isPlainObject(dec))
+        return true;
+    return false;
+}
+function mergeBucketIntoFields(fields, unknowns, bucket, bucketObj) {
+    const disambig = new Set(Object.keys(fields));
+    for (const [leafKey, field] of Object.entries(bucketObj)) {
+        if (!looksLikeFieldEnvelope(field))
+            continue;
+        const f = field;
+        let outKey = leafKey;
+        if (disambig.has(leafKey)) {
+            outKey = `${bucket}_${leafKey}`;
+        }
+        disambig.add(outKey);
+        fields[outKey] = {
+            value: f.value,
+            fieldPath: typeof f.fieldPath === 'string' ? f.fieldPath : '',
+            ...(f.description != null ? { description: f.description } : {}),
+            ...(f.reasoning != null ? { reasoning: f.reasoning } : {}),
+            ...(f.linked != null ? { linked: f.linked } : {}),
+        };
+        if (f.value == null) {
+            unknowns.push(outKey);
+        }
+    }
+}
+/** Flatten nested or legacy `answer` documents into graph execution field maps. */
+export function scopedAnswerDocToFlatFields(rawAnswer) {
+    const fields = {};
+    const unknowns = [];
+    if (isNestedAnswerShape(rawAnswer)) {
+        const inf = isPlainObject(rawAnswer.inferences) ? rawAnswer.inferences : {};
+        const dec = isPlainObject(rawAnswer.decisions) ? rawAnswer.decisions : {};
+        mergeBucketIntoFields(fields, unknowns, 'decisions', dec);
+        mergeBucketIntoFields(fields, unknowns, 'inferences', inf);
+        return { fields, unknowns };
+    }
+    for (const [key, field] of Object.entries(rawAnswer)) {
+        if (!looksLikeFieldEnvelope(field))
+            continue;
+        const f = field;
+        fields[key] = {
+            value: f.value,
+            fieldPath: typeof f.fieldPath === 'string' ? f.fieldPath : '',
+            ...(f.description != null ? { description: f.description } : {}),
+            ...(f.reasoning != null ? { reasoning: f.reasoning } : {}),
+            ...(f.linked != null ? { linked: f.linked } : {}),
+        };
+        if (f.value == null) {
+            unknowns.push(key);
+        }
+    }
+    return { fields, unknowns };
+}

package/dist/src/runtime/localSkills/scopedAnswerWriter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * scoped-answer-writer — local skill.
+ *
+ * Persists execution-memory payloads into Memorix **entity** collections, one
+ * **content type** per write (`inferences`, `decisions`, …) via `writeMemorixRecord`.
+ *
+ * Node config:
+ *   entityIdPath — required
+ *   payloadPath  — dot-path to `{ inferences?, decisions? }` or flat decisions map
+ *   memorixWriteDescriptors — optional map of contentType → Catalox write descriptor id
+ *     (default: descriptor id equals content type name)
+ */
+import { type MemorixScopedSkillConfig } from './memorixScopedConfig.js';
+import { type ResolveDotPathOpts } from './utils.js';
+export type ScopedAnswerWriterConfig = MemorixScopedSkillConfig & {
+    entityIdPath: string;
+    entityTypePath?: string;
+    staticEntityType?: string;
+    payloadPath?: string;
+    questionTitle?: string;
+    phase?: 'A' | 'B';
+    /** Content types to persist when present in payload (default: inferences, decisions). */
+    memorixContentTypes?: string[];
+};
+export type ScopedAnswerWriterOutput = {
+    write_status: 'ok' | 'error';
+    entity_id: string;
+    content_types_written: string[];
+    written_keys: string[];
+    error?: string;
+};
+export declare function runScopedAnswerWriter(cfg: ScopedAnswerWriterConfig, executionMemory: unknown, pathOpts?: ResolveDotPathOpts): Promise<ScopedAnswerWriterOutput>;