@remnic/core 9.3.676 → 9.3.678

package/src/capabilities.test.ts

@@ -95,3 +95,176 @@ test("resolveCapabilities returns a frozen object", () => {
   const caps = resolveCapabilities(parseConfig({}));
   assert.equal(Object.isFrozen(caps), true, "CapabilitySet must be frozen");
 });
+
+// ---------------------------------------------------------------------------
+// GraphConstructionCapabilitySet — gate-parity tests (issue #1566 Cluster A).
+//
+// Same invariant as the recall CapabilitySet tests above: every caps field
+// must project from its `<field>Enabled` config flag, so a future edit to
+// `resolveGraphConstructionCapabilities` that maps a field to the wrong flag
+// (or drops the `!== false` default for the optional session-adjacency flag)
+// fails loudly here.
+//
+// Parity contract: a caps-resolved run and a config-derived run MUST produce
+// identical boolean values for every gate — on AND off. These tests are the
+// executable proof of that contract.
+// ---------------------------------------------------------------------------
+
+import {
+  resolveGraphConstructionCapabilities,
+  type GraphConstructionCapabilitySet,
+} from "./capabilities.js";
+
+const GRAPH_FIELD_TO_FLAG: Record<keyof GraphConstructionCapabilitySet, string> = {
+  entityGraph: "entityGraphEnabled",
+  timeGraph: "timeGraphEnabled",
+  causalGraph: "causalGraphEnabled",
+  multiGraphMemory: "multiGraphMemoryEnabled",
+  graphWriteSessionAdjacency: "graphWriteSessionAdjacencyEnabled",
+};
+
+const GRAPH_FIELDS = Object.keys(GRAPH_FIELD_TO_FLAG) as Array<
+  keyof GraphConstructionCapabilitySet
+>;
+
+test("resolveGraphConstructionCapabilities projects every field from its flag (true variant)", () => {
+  const overrides: Record<string, boolean> = {};
+  for (const flag of Object.values(GRAPH_FIELD_TO_FLAG)) overrides[flag] = true;
+  const config = parseConfig(overrides);
+  const graphCaps = resolveGraphConstructionCapabilities(config);
+
+  for (const field of GRAPH_FIELDS) {
+    const flag = GRAPH_FIELD_TO_FLAG[field];
+    assert.equal(
+      graphCaps[field],
+      (config as unknown as Record<string, boolean>)[flag],
+      `graphCaps.${field} must equal config.${flag} (true variant)`,
+    );
+    assert.equal(graphCaps[field], true, `graphCaps.${field} should be true here`);
+  }
+});
+
+test("resolveGraphConstructionCapabilities projects every field from its flag (false variant)", () => {
+  const overrides: Record<string, boolean> = {};
+  for (const flag of Object.values(GRAPH_FIELD_TO_FLAG)) overrides[flag] = false;
+  const config = parseConfig(overrides);
+  const graphCaps = resolveGraphConstructionCapabilities(config);
+
+  for (const field of GRAPH_FIELDS) {
+    const flag = GRAPH_FIELD_TO_FLAG[field];
+    assert.equal(
+      graphCaps[field],
+      (config as unknown as Record<string, boolean>)[flag],
+      `graphCaps.${field} must equal config.${flag} (false variant)`,
+    );
+    assert.equal(graphCaps[field], false, `graphCaps.${field} should be false here`);
+  }
+});
+
+test("resolveGraphConstructionCapabilities preserves graphWriteSessionAdjacency default-on when undefined", () => {
+  // graphWriteSessionAdjacencyEnabled is optional — `!== false` means
+  // default-ON. This is the exact semantics the migrated call site used
+  // (orchestrator.ts buildGraphEdge), and the parity test below verifies
+  // the caps resolver does not drift from it.
+  const config = parseConfig({});
+  const graphCaps = resolveGraphConstructionCapabilities(config);
+
+  assert.equal(
+    graphCaps.graphWriteSessionAdjacency,
+    config.graphWriteSessionAdjacencyEnabled !== false,
+    "graphWriteSessionAdjacency must be default-on unless explicitly false",
+  );
+  assert.equal(
+    graphCaps.graphWriteSessionAdjacency,
+    true,
+    "with no explicit override, graphWriteSessionAdjacency should be true",
+  );
+
+  // Explicit-false must propagate (not get swallowed by the default).
+  const disabled = parseConfig({ graphWriteSessionAdjacencyEnabled: false });
+  assert.equal(
+    resolveGraphConstructionCapabilities(disabled).graphWriteSessionAdjacency,
+    false,
+    "explicit false must disable graphWriteSessionAdjacency",
+  );
+});
+
+test("resolveGraphConstructionCapabilities returns a frozen object", () => {
+  const graphCaps = resolveGraphConstructionCapabilities(parseConfig({}));
+  assert.equal(Object.isFrozen(graphCaps), true, "GraphConstructionCapabilitySet must be frozen");
+});
+
+test("resolveGraphConstructionCapabilities matches pre-migration config reads (parity contract)", () => {
+  // This is the core parity test: for EVERY combination of the 5 cluster-A
+  // flags, the caps-resolved values MUST be identical to what the old
+  // scattered `this.config.<flag>Enabled` reads would have produced.
+  //
+  // We exercise representative combinations rather than the full 2^5 space
+  // (32 cases) to keep the test cheap, but we cover:
+  //   - all-off (the "no graphs" baseline)
+  //   - all-on (the "full graph" mode)
+  //   - only entity graph
+  //   - multiGraph off but others on (the recall-without-write split)
+  //   - session-adjacency undefined vs explicit-false
+  const cases: Record<string, Record<string, boolean | undefined>> = {
+    "all-off": {
+      entityGraphEnabled: false,
+      timeGraphEnabled: false,
+      causalGraphEnabled: false,
+      multiGraphMemoryEnabled: false,
+      graphWriteSessionAdjacencyEnabled: false,
+    },
+    "all-on": {
+      entityGraphEnabled: true,
+      timeGraphEnabled: true,
+      causalGraphEnabled: true,
+      multiGraphMemoryEnabled: true,
+      graphWriteSessionAdjacencyEnabled: true,
+    },
+    "entity-only": {
+      entityGraphEnabled: true,
+      timeGraphEnabled: false,
+      causalGraphEnabled: false,
+      multiGraphMemoryEnabled: true,
+      graphWriteSessionAdjacencyEnabled: true,
+    },
+    "multigraph-off": {
+      entityGraphEnabled: true,
+      timeGraphEnabled: true,
+      causalGraphEnabled: true,
+      multiGraphMemoryEnabled: false,
+      graphWriteSessionAdjacencyEnabled: true,
+    },
+    "session-adj-undefined": {
+      entityGraphEnabled: true,
+      timeGraphEnabled: true,
+      causalGraphEnabled: true,
+      multiGraphMemoryEnabled: true,
+      // graphWriteSessionAdjacencyEnabled deliberately omitted
+    },
+  };
+
+  for (const [label, overrides] of Object.entries(cases)) {
+    const config = parseConfig(overrides);
+    const graphCaps = resolveGraphConstructionCapabilities(config);
+
+    // Parity: each caps field must equal the pre-migration config read.
+    // entityGraph/timeGraph/causalGraph/multiGraphMemory used bare reads:
+    //   config.entityGraphEnabled  → graphCaps.entityGraph
+    // graphWriteSessionAdjacency used `!== false`:
+    //   config.graphWriteSessionAdjacencyEnabled !== false  → graphCaps.graphWriteSessionAdjacency
+    assert.equal(graphCaps.entityGraph, config.entityGraphEnabled, `[${label}] entityGraph parity`);
+    assert.equal(graphCaps.timeGraph, config.timeGraphEnabled, `[${label}] timeGraph parity`);
+    assert.equal(graphCaps.causalGraph, config.causalGraphEnabled, `[${label}] causalGraph parity`);
+    assert.equal(
+      graphCaps.multiGraphMemory,
+      config.multiGraphMemoryEnabled,
+      `[${label}] multiGraphMemory parity`,
+    );
+    assert.equal(
+      graphCaps.graphWriteSessionAdjacency,
+      config.graphWriteSessionAdjacencyEnabled !== false,
+      `[${label}] graphWriteSessionAdjacency parity (must match !== false)`,
+    );
+  }
+});

package/src/capabilities.ts

@@ -84,3 +84,64 @@ export function resolveCapabilities(config: PluginConfig): CapabilitySet {
     graphExpandedIntent: config.graphExpandedIntentEnabled === true,
   });
 }
+
+// ---------------------------------------------------------------------------
+// Graph-construction capability set (issue #1566 Cluster A).
+//
+// The recall CapabilitySet above covers flags whose EVERY read site lives on
+// the recall call chain. The five flags below are read on graph-construction,
+// write/extraction, AND recall paths — so they cannot join the recall set
+// without leaving some sites on `caps.` and others on `config.` (the exact
+// divergence #1523 forbade). They get their own projection, resolved at graph
+// build/write entry (and alongside `caps` when recall reads them).
+// ---------------------------------------------------------------------------
+
+/**
+ * Frozen projection of graph-construction feature gates.
+ *
+ * Every field is `readonly boolean`. Composition (including default-when-
+ * undefined semantics for the optional `graphWriteSessionAdjacencyEnabled`)
+ * lives ONLY in {@link resolveGraphConstructionCapabilities}.
+ */
+export interface GraphConstructionCapabilitySet {
+  /** `entityGraphEnabled` — maintain entity co-reference graph edges. */
+  readonly entityGraph: boolean;
+  /** `timeGraphEnabled` — maintain thread-adjacency graph edges. */
+  readonly timeGraph: boolean;
+  /** `causalGraphEnabled` — maintain causal-language graph edges. */
+  readonly causalGraph: boolean;
+  /** `multiGraphMemoryEnabled` — master switch for multi-graph writes/traversal. */
+  readonly multiGraphMemory: boolean;
+  /** `graphWriteSessionAdjacencyEnabled` — session-adjacency fallback for time edges (default-on). */
+  readonly graphWriteSessionAdjacency: boolean;
+}
+
+/**
+ * Resolve the {@link GraphConstructionCapabilitySet} from parsed config.
+ *
+ * Call this ONCE at graph build/write entry (extraction, recall graph
+ * expansion, graph-health/repair) and thread the result down — exactly the
+ * pattern {@link resolveCapabilities} established for recall.
+ */
+export type GraphConstructionConfigProjection = Pick<
+  PluginConfig,
+  | "entityGraphEnabled"
+  | "timeGraphEnabled"
+  | "causalGraphEnabled"
+  | "multiGraphMemoryEnabled"
+  | "graphWriteSessionAdjacencyEnabled"
+>;
+
+export function resolveGraphConstructionCapabilities(
+  config: GraphConstructionConfigProjection,
+): GraphConstructionCapabilitySet {
+  return Object.freeze({
+    entityGraph: config.entityGraphEnabled,
+    timeGraph: config.timeGraphEnabled,
+    causalGraph: config.causalGraphEnabled,
+    multiGraphMemory: config.multiGraphMemoryEnabled,
+    // Optional flag: preserve the exact default-when-undefined semantics the
+    // migrated call site used (`!== false` = default-on).
+    graphWriteSessionAdjacency: config.graphWriteSessionAdjacencyEnabled !== false,
+  });
+}

package/src/graph.ts

@@ -424,13 +424,29 @@ export class GraphIndex {
     recentInThread?: string[];
     entitySiblings?: string[];
     causalPredecessor?: string;
+    /**
+     * Optional frozen gate overrides (from GraphConstructionCapabilitySet).
+     * When provided, these take precedence over `this.cfg` so the caller's
+     * operation-scoped snapshot is the single source of truth (#1566).
+     */
+    graphCapsOverride?: {
+      entityGraph: boolean;
+      timeGraph: boolean;
+      causalGraph: boolean;
+      multiGraphMemory: boolean;
+    };
   }): Promise<void> {
-    if (!this.cfg.multiGraphMemoryEnabled) return;
+    const g = opts.graphCapsOverride;
+    const multiGraphOn = g ? g.multiGraphMemory : this.cfg.multiGraphMemoryEnabled;
+    if (!multiGraphOn) return;
+    const entityOn = g ? g.entityGraph : this.cfg.entityGraphEnabled;
+    const timeOn = g ? g.timeGraph : this.cfg.timeGraphEnabled;
+    const causalOn = g ? g.causalGraph : this.cfg.causalGraphEnabled;
     const ts = new Date().toISOString();
 
     try {
       // Entity graph
-      if (this.cfg.entityGraphEnabled && opts.entityRef && opts.entitySiblings?.length) {
+      if (entityOn && opts.entityRef && opts.entitySiblings?.length) {
         const siblings = opts.entitySiblings.slice(0, this.cfg.maxEntityGraphEdgesPerMemory);
         for (const sibling of siblings) {
           await appendEdge(this.memoryDir, {
@@ -445,7 +461,7 @@ export class GraphIndex {
       }
 
       // Time graph — link to most recent memory in same thread
-      if (this.cfg.timeGraphEnabled && opts.threadId && opts.recentInThread?.length) {
+      if (timeOn && opts.threadId && opts.recentInThread?.length) {
         const predecessor = opts.recentInThread[opts.recentInThread.length - 1];
         if (predecessor && predecessor !== opts.memoryPath) {
           await appendEdge(this.memoryDir, {
@@ -460,7 +476,7 @@ export class GraphIndex {
       }
 
       // Causal graph
-      if (this.cfg.causalGraphEnabled && opts.causalPredecessor) {
+      if (causalOn && opts.causalPredecessor) {
         const phrase = detectCausalPhrase(opts.content);
         if (phrase) {
           await appendEdge(this.memoryDir, {