@kontourai/flow-agents 0.3.0 → 1.0.0

package/kits/knowledge/adapters/flow-runner/index.js

@@ -13,6 +13,7 @@
  *   - compile(rawIds[], options)        — compile flow: select → compile → link with provenance
  *   - synthesize(conceptId | topicSelector, options) — synthesize flow:
  *       detect-cluster → propose → evidence-gate → apply-or-reject
+ *   - retire(recordId, options)          — retire flow: identify → propose → evidence-gate → apply-or-reject
  *   - defaultSimilarityDetector         — pluggable similarity interface default (R3)
  *
  * Telemetry:
@@ -34,6 +35,12 @@
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { KnowledgeTelemetry } from "./telemetry.js";
+import {
+  defaultEntityExtractor,
+  normalizeName,
+  isExactMatch,
+  isPossibleDuplicate,
+} from "./entity-extractor.js";
 
 // ---------------------------------------------------------------------------
 // Error helpers
@@ -112,6 +119,9 @@ export async function defaultSimilarityDetector(concept, candidates, store) {
   const similar = [];
 
   for (const candidate of candidates) {
+    // Exclude retired records from the working set (Addendum B — R3)
+    if ((candidate.status || "active") === "retired") continue;
+
     // Check 1: category overlap (prefix match in either direction)
     const catMatch =
       candidate.category === concept.category ||
@@ -1107,12 +1117,597 @@ export class KnowledgeFlowRunner {
     };
   }
 
+  // -------------------------------------------------------------------------
+  // knowledge.retire flow  (Addendum B — S7)
+  //   Steps: identify → propose-retirement → evidence-gate → apply-or-reject → done
+  //   Gate: evidence-gate — proposal carries rationale/ref; no direct mutation (AC1).
+  //         apply-gate    — apply or reject via store retire op.
+  //                         rejection leaves record status byte-identical (AC2).
+  //
+  // Machinery reuse: retire shares the same propose→evidence-gate→apply-or-reject
+  // pattern as synthesize/consolidate. The store's retire op enforces the transition
+  // table; rejection leaves the record unchanged.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Execute the retire flow: identify the target record, create a retirement
+   * proposal (never a direct mutation), gate the evidence, then apply or reject.
+   *
+   * On apply:
+   *   The store retire op updates the record status to targetStatus and appends
+   *   a mutation log entry with the full evidence. The record is excluded from
+   *   default working-set queries (listByType, listByCategory, similarity
+   *   detection) unless includeRetired is true.
+   *
+   * On reject:
+   *   The record status is byte-identical to its pre-proposal state.
+   *
+   * @param {string} recordId
+   *   ID of the record to retire.
+   * @param {object} [options]
+   *   - targetStatus: "implemented"|"retired"  — target status (required)
+   *   - rationale: string                      — why retiring (required)
+   *   - implementedByRef: string               — ref when targetStatus="implemented" (required)
+   *   - supersededByRef: string                — optional ref to superseding artifact
+   *   - decision: "apply"|"reject"             — gate decision (default "apply")
+   *   - rejectReason: string                   — reason for rejection (required when decision="reject")
+   *   - agent: string                          — override agent name
+   *   - session_id: string                     — session id
+   *   - note: string                           — provenance note
+   * @returns {Promise<{
+   *   recordId: string,
+   *   targetStatus: string,
+   *   decision: "apply"|"reject",
+   *   previousStatus: string,
+   *   proposerId: string,
+   *   telemetryEvents: object[]
+   * }>}
+   */
+  async retire(recordId, options = {}) {
+    const events = [];
+    const agent = options.agent || this._agent;
+
+    // ── Step: identify ─────────────────────────────────────────────────────
+    if (!recordId || typeof recordId !== "string") {
+      throw missingEvidenceError("retire: recordId must be a non-empty string");
+    }
+
+    const targetStatus = options.targetStatus;
+    if (targetStatus !== "implemented" && targetStatus !== "retired") {
+      throw missingEvidenceError(
+        'retire: options.targetStatus must be "implemented" or "retired"'
+      );
+    }
+
+    if (!options.rationale || !options.rationale.trim()) {
+      throw missingEvidenceError("retire: options.rationale is required");
+    }
+
+    if (targetStatus === "implemented" && (!options.implementedByRef || !options.implementedByRef.trim())) {
+      throw missingEvidenceError(
+        'retire: options.implementedByRef is required when targetStatus is "implemented"'
+      );
+    }
+
+    const record = await this._store.get(recordId);
+    if (!record) {
+      throw missingEvidenceError(`retire: record not found: ${recordId}`);
+    }
+
+    const previousStatus = record.status || "active";
+
+    // Validate transition early (surface errors at identify-gate, not at apply-gate)
+    const VALID_TRANSITIONS = {
+      active:      new Set(["implemented", "retired"]),
+      implemented: new Set(["retired"]),
+      retired:     new Set(),
+    };
+    const allowed = VALID_TRANSITIONS[previousStatus] || new Set();
+    if (!allowed.has(targetStatus)) {
+      throw missingEvidenceError(
+        `retire: invalid transition from "${previousStatus}" to "${targetStatus}"`
+      );
+    }
+
+    // Emit identify gate entry
+    const identifyGateIn = this._telemetry.emitGate("knowledge.retire", "identify-gate", {
+      flow: "knowledge.retire",
+      gate: "identify-gate",
+      record_id: recordId,
+      record_type: record.type,
+      current_status: previousStatus,
+      target_status: targetStatus,
+    });
+    events.push(identifyGateIn);
+
+    const identifyGateOut = this._telemetry.emitGateResult("knowledge.retire", "identify-gate", {
+      record_id: recordId,
+      record_type: record.type,
+      current_status: previousStatus,
+      target_status: targetStatus,
+      transition_valid: true,
+    });
+    events.push(identifyGateOut);
+
+    // ── Step: propose-retirement ───────────────────────────────────────────
+    // We reuse the store's propose op against the record itself.
+    // The record acts as the "concept" target; a transient proposer raw record
+    // carries the retirement proposal and proposes link.
+
+    const proposeGateIn = this._telemetry.emitGate(
+      "knowledge.retire",
+      "propose-retirement-gate",
+      {
+        flow: "knowledge.retire",
+        gate: "propose-retirement-gate",
+        record_id: recordId,
+        target_status: targetStatus,
+        rationale: options.rationale,
+      }
+    );
+    events.push(proposeGateIn);
+
+    // Create a transient proposer record to hold the retirement proposal
+    const proposerBody =
+      `Retirement proposal for record ${recordId}.
+` +
+      `Target status: ${targetStatus}
+` +
+      `Rationale: ${options.rationale}
+` +
+      (options.implementedByRef ? `Implemented-by: ${options.implementedByRef}
+` : "") +
+      (options.supersededByRef ? `Superseded-by: ${options.supersededByRef}
+` : "");
+
+    const proposerId = await this._store.create({
+      type: "raw",
+      title: `Retirement proposal: ${record.title}`,
+      body: proposerBody,
+      category: record.category,
+      provenance: {
+        agent,
+        note: `Retirement proposal for ${recordId}`,
+        ...(options.session_id ? { session_id: options.session_id } : {}),
+      },
+    });
+
+    // Attach the proposal via the store's propose op (not direct mutation — AC1)
+    await this._store.propose(recordId, proposerId, {
+      agent,
+      proposal: options.rationale,
+      ...(options.note ? { note: options.note } : {}),
+    });
+
+    const proposeGateOut = this._telemetry.emitGateResult(
+      "knowledge.retire",
+      "propose-retirement-gate",
+      {
+        record_id: recordId,
+        proposer_id: proposerId,
+        target_status: targetStatus,
+        proposal_recorded: true,
+      }
+    );
+    events.push(proposeGateOut);
+
+    // ── Step: evidence-gate ────────────────────────────────────────────────
+    // Verify the proposal carries required evidence and the transition is valid.
+
+    const evidenceGateIn = this._telemetry.emitGate("knowledge.retire", "evidence-gate", {
+      flow: "knowledge.retire",
+      gate: "evidence-gate",
+      record_id: recordId,
+      proposer_id: proposerId,
+      target_status: targetStatus,
+    });
+    events.push(evidenceGateIn);
+
+    // Enforce: proposer must have a "proposes" link to the record
+    const { forward } = await this._store.getLinks(proposerId);
+    const hasProposesLink = forward.some(
+      (l) => l.target_id === recordId && l.kind === "proposes"
+    );
+    if (!hasProposesLink) {
+      throw missingEvidenceError(
+        `evidence-gate: proposer ${proposerId} must have a "proposes" link to record ${recordId}`
+      );
+    }
+
+    // Enforce: target record still exists
+    const targetRecord = await this._store.get(recordId);
+    if (!targetRecord) {
+      throw missingEvidenceError(
+        `evidence-gate: target record ${recordId} does not exist`
+      );
+    }
+
+    const evidenceGateOut = this._telemetry.emitGateResult("knowledge.retire", "evidence-gate", {
+      record_id: recordId,
+      proposer_id: proposerId,
+      target_status: targetStatus,
+      proposes_link_verified: true,
+      target_record_verified: true,
+    });
+    events.push(evidenceGateOut);
+
+    // ── Step: apply-or-reject ──────────────────────────────────────────────
+    const decision = options.decision || "apply";
+
+    const applyGateIn = this._telemetry.emitGate("knowledge.retire", "apply-gate", {
+      flow: "knowledge.retire",
+      gate: "apply-gate",
+      record_id: recordId,
+      proposer_id: proposerId,
+      target_status: targetStatus,
+      decision,
+    });
+    events.push(applyGateIn);
+
+    if (decision === "apply") {
+      // Apply via store retire op — transitions status, appends mutation log (AC1)
+      await this._store.retire(recordId, targetStatus, {
+        agent,
+        rationale: options.rationale,
+        ...(options.implementedByRef ? { implementedByRef: options.implementedByRef } : {}),
+        ...(options.supersededByRef ? { supersededByRef: options.supersededByRef } : {}),
+        ...(options.note ? { note: options.note } : {}),
+      });
+    } else if (decision === "reject") {
+      if (!options.rejectReason || !options.rejectReason.trim()) {
+        throw missingEvidenceError(
+          "apply-gate: options.rejectReason is required when decision=reject"
+        );
+      }
+      // Reject via store reject op — record status remains untouched (AC2)
+      await this._store.reject(recordId, proposerId, {
+        agent,
+        reason: options.rejectReason,
+      });
+    } else {
+      throw missingEvidenceError(
+        `apply-gate: decision must be "apply" or "reject"; got: ${decision}`
+      );
+    }
+
+    const applyGateOut = this._telemetry.emitGateResult("knowledge.retire", "apply-gate", {
+      record_id: recordId,
+      proposer_id: proposerId,
+      target_status: targetStatus,
+      decision,
+      previous_status: previousStatus,
+    });
+    events.push(applyGateOut);
+
+    return {
+      recordId,
+      targetStatus,
+      decision,
+      previousStatus,
+      proposerId,
+      telemetryEvents: events,
+    };
+  }
+
+
+  // -------------------------------------------------------------------------
+  // knowledge.compile — entity extraction step (R2)
+  //
+  // Called after compile() to extract person mentions from the compiled record,
+  // resolve/create person cards, and write bidirectional links:
+  //   - Person card → raw + compiled (kind: appears-in)
+  //   - Compiled record → person cards (kind: person)
+  //
+  // EntityExtractor interface (same pattern as SimilarityDetector — R3):
+  //   async (record: Record) => PersonMention[]
+  //   PersonMention: { name: string, role?: string, org?: string }
+  // -------------------------------------------------------------------------
+
+  /**
+   * Extract person entities from a compiled record and its source raws, then
+   * create or update person cards with bidirectional links.
+   *
+   * @param {string} compiledId   - ID of the compiled record to process
+   * @param {object} [options]
+   *   - entityExtractor: fn   — pluggable extractor (default: defaultEntityExtractor)
+   *   - agent: string         — override agent name
+   * @returns {Promise<{
+   *   compiledId: string,
+   *   personCards: Array<{ cardId, name, created, duplicate }>,
+   *   linkCount: number
+   * }>}
+   */
+  async extractEntities(compiledId, options = {}) {
+    const agent = options.agent || this._agent;
+    const extractor = options.entityExtractor || defaultEntityExtractor;
+
+    const compiled = await this._store.get(compiledId);
+    if (!compiled) throw new Error(`extractEntities: compiled record not found: ${compiledId}`);
+
+    // Gather mentions from the compiled record
+    const mentions = await extractor(compiled);
+
+    // Also gather mentions from all source raw records
+    const sourceLinks = (compiled.links || []).filter((l) => l.kind === "source");
+    const seenNames = new Set(mentions.map((m) => normalizeName(m.name)));
+    for (const link of sourceLinks) {
+      const raw = await this._store.get(link.target_id);
+      if (!raw) continue;
+      const rawMentions = await extractor(raw);
+      for (const m of rawMentions) {
+        const norm = normalizeName(m.name);
+        if (!seenNames.has(norm)) {
+          seenNames.add(norm);
+          mentions.push(m);
+        }
+      }
+    }
+
+    const personCardResults = [];
+    const category = compiled.category || "people";
+
+    for (const mention of mentions) {
+      // Resolve or create the person card
+      const result = await resolvePersonCard(this._store, mention, category, agent);
+      const { cardId, created, duplicate } = result;
+
+      // Build link sets for both sides
+      const cardRecord = await this._store.get(cardId);
+      const compiledRecord = await this._store.get(compiledId);
+
+      // Person card → compiled (appears-in) — skip if already linked
+      const cardLinks = cardRecord.links || [];
+      const hasCompiledLink = cardLinks.some(
+        (l) => l.target_id === compiledId && l.kind === "appears-in"
+      );
+      if (!hasCompiledLink) {
+        await this._store.link(
+          cardId,
+          [{ target_id: compiledId, kind: "appears-in" }],
+          { agent, note: `Person appears in compiled record` }
+        );
+      }
+
+      // Person card → each source raw (appears-in) — skip if already linked
+      for (const link of sourceLinks) {
+        const updatedCard = await this._store.get(cardId);
+        const hasRawLink = (updatedCard.links || []).some(
+          (l) => l.target_id === link.target_id && l.kind === "appears-in"
+        );
+        if (!hasRawLink) {
+          await this._store.link(
+            cardId,
+            [{ target_id: link.target_id, kind: "appears-in" }],
+            { agent, note: `Person appears in raw source` }
+          );
+        }
+      }
+
+      // Compiled record → person card (person link) — skip if already linked
+      const compLinks = compiledRecord.links || [];
+      const hasPersonLink = compLinks.some(
+        (l) => l.target_id === cardId && l.kind === "person"
+      );
+      if (!hasPersonLink) {
+        await this._store.link(
+          compiledId,
+          [{ target_id: cardId, kind: "person" }],
+          { agent, note: `Compiled record references person card` }
+        );
+      }
+
+      personCardResults.push({ cardId, name: mention.name, created, duplicate });
+    }
+
+    return {
+      compiledId,
+      personCards: personCardResults,
+      linkCount: personCardResults.length,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // knowledge.merge-person flow (R3 / AC3)
+  //   Merge two person cards via the existing propose→apply/reject gate.
+  //   On apply: union aliases + links → supersede the duplicate (archive).
+  //   On reject: both cards remain byte-identical.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Merge a duplicate person card into a primary card via gated propose/apply.
+   *
+   * On apply:
+   *   1. Primary card body updated with unioned role text.
+   *   2. Aliases from the duplicate appended to primary's tags as "alias:Name".
+   *   3. All appears-in links from the duplicate are added to the primary.
+   *   4. The duplicate is superseded (archived) via store.supersede().
+   *
+   * On reject:
+   *   Both cards remain byte-identical (AC3).
+   *
+   * @param {string} primaryId    - ID of the primary person card to keep
+   * @param {string} duplicateId  - ID of the card being merged in
+   * @param {object} [options]
+   *   - decision: "apply"|"reject"  (default "apply")
+   *   - rationale: string           (required for apply)
+   *   - rejectReason: string        (required for reject)
+   *   - agent: string
+   * @returns {Promise<{ primaryId, duplicateId, decision }>}
+   */
+  async mergePerson(primaryId, duplicateId, options = {}) {
+    const agent = options.agent || this._agent;
+    const decision = options.decision || "apply";
+
+    const primary = await this._store.get(primaryId);
+    if (!primary) throw new Error(`mergePerson: primary card not found: ${primaryId}`);
+    if (primary.type !== "person") throw new Error(`mergePerson: primaryId must be a person record`);
+
+    const duplicate = await this._store.get(duplicateId);
+    if (!duplicate) throw new Error(`mergePerson: duplicate card not found: ${duplicateId}`);
+    if (duplicate.type !== "person") throw new Error(`mergePerson: duplicateId must be a person record`);
+
+    // propose: duplicate proposes a change to primary
+    await this._store.propose(primaryId, duplicateId, {
+      agent,
+      proposal: `Merge duplicate person card "${duplicate.title}" into "${primary.title}"`,
+    });
+
+    if (decision === "apply") {
+      if (!options.rationale || !options.rationale.trim()) {
+        throw new Error("mergePerson: options.rationale is required when decision=apply");
+      }
+
+      // Compute merged body: union role text
+      const mergedBodyLines = [];
+      if (primary.body && primary.body.trim()) mergedBodyLines.push(primary.body.trim());
+      if (duplicate.body && duplicate.body.trim() && duplicate.body.trim() !== primary.body.trim()) {
+        mergedBodyLines.push(duplicate.body.trim());
+      }
+      const mergedBody = mergedBodyLines.join("\n") || primary.title;
+
+      // Apply: update primary body
+      await this._store.apply(primaryId, duplicateId, {
+        agent,
+        new_body: mergedBody,
+        rationale: options.rationale,
+      });
+
+      // Add duplicate title as alias on primary
+      const primaryAfterApply = await this._store.get(primaryId);
+      const existingTags = primaryAfterApply.tags || [];
+      const aliasTag = `alias:${duplicate.title}`;
+      if (!existingTags.includes(aliasTag)) {
+        await this._store.update(primaryId, { tags: [...existingTags, aliasTag] }, {
+          agent,
+          note: `Added alias from merged duplicate: ${duplicate.title}`,
+        });
+      }
+
+      // Union appears-in links from duplicate to primary
+      const dupLinks = (duplicate.links || []).filter((l) => l.kind === "appears-in");
+      const primaryLinks = await this._store.getLinks(primaryId);
+      for (const link of dupLinks) {
+        const hasLink = primaryLinks.forward.some(
+          (l) => l.target_id === link.target_id && l.kind === "appears-in"
+        );
+        if (!hasLink) {
+          await this._store.link(primaryId, [{ target_id: link.target_id, kind: "appears-in" }], {
+            agent,
+            note: `Unioned from merged duplicate ${duplicateId}`,
+          });
+        }
+      }
+
+      // Supersede the duplicate (archives it — supersede-not-delete invariant)
+      await this._store.supersede(primaryId, [duplicateId], {
+        agent,
+        rationale: options.rationale,
+        note: `Merged duplicate person card into ${primaryId}`,
+      });
+    } else if (decision === "reject") {
+      if (!options.rejectReason || !options.rejectReason.trim()) {
+        throw new Error("mergePerson: options.rejectReason is required when decision=reject");
+      }
+      // Reject: both cards remain byte-identical
+      await this._store.reject(primaryId, duplicateId, {
+        agent,
+        reason: options.rejectReason,
+      });
+    } else {
+      throw new Error(`mergePerson: decision must be "apply" or "reject"; got: ${decision}`);
+    }
+
+    return { primaryId, duplicateId, decision };
+  }
+
 }
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve or create a person card for a given mention.
+ *
+ * Resolution rules (R3):
+ *  1. Exact normalised-name match (or alias match) → update existing card.
+ *  2. Possible duplicate (same surname + initial) → create new card + related
+ *     link of kind "related" with a possible-duplicate tag.
+ *  3. No match → create new card.
+ *
+ * @param {object} store       - KnowledgeStoreAdapter
+ * @param {object} mention     - { name, role? }
+ * @param {string} category    - category for new card
+ * @param {string} agent       - agent name
+ * @returns {Promise<{ cardId: string, created: boolean, duplicate: boolean }>}
+ */
+async function resolvePersonCard(store, mention, category, agent) {
+  const existing = await store.listByType("person");
+
+  // 1. Exact match (name or alias)
+  for (const card of existing) {
+    if (isExactMatch(card.title, mention.name)) {
+      return { cardId: card.id, created: false, duplicate: false };
+    }
+    // Check aliases tag: "alias:Some Name"
+    const aliases = (card.tags || [])
+      .filter((t) => t.startsWith("alias:"))
+      .map((t) => t.slice("alias:".length));
+    for (const alias of aliases) {
+      if (isExactMatch(alias, mention.name)) {
+        return { cardId: card.id, created: false, duplicate: false };
+      }
+    }
+  }
+
+  // 2. Possible duplicate check
+  let possibleDupId = null;
+  for (const card of existing) {
+    if (isPossibleDuplicate(mention.name, card.title)) {
+      possibleDupId = card.id;
+      break;
+    }
+    const aliases = (card.tags || [])
+      .filter((t) => t.startsWith("alias:"))
+      .map((t) => t.slice("alias:".length));
+    for (const alias of aliases) {
+      if (isPossibleDuplicate(mention.name, alias)) {
+        possibleDupId = card.id;
+        break;
+      }
+    }
+    if (possibleDupId) break;
+  }
+
+  // Build body: role/org as structured prose
+  const bodyLines = [];
+  if (mention.role) {
+    bodyLines.push(`**Role/Org:** ${mention.role}`);
+  }
+  const body = bodyLines.length > 0 ? bodyLines.join("\n") : mention.name;
+
+  // Create new person card
+  const cardId = await store.create({
+    type: "person",
+    title: mention.name,
+    body,
+    category,
+    tags: [],
+    provenance: { agent, note: `Auto-created from entity extraction` },
+  });
+
+  // If possible duplicate: add related link from new card to existing card
+  if (possibleDupId) {
+    await store.link(
+      cardId,
+      [{ target_id: possibleDupId, kind: "related", label: "possible-duplicate" }],
+      { agent, note: "Possible duplicate — same surname+initial; verify manually" }
+    );
+  }
+
+  return { cardId, created: true, duplicate: possibleDupId !== null };
+}
+
 function mostCommonCategory(records) {
   const counts = {};
   for (const r of records) {
@@ -1176,4 +1771,48 @@ export async function consolidate(
   return runner.consolidate(snapshotIdOrTopic, consolidateOpts);
 }
 
+/**
+ * Module-level retire: creates an ephemeral runner using the provided store.
+ *
+ * @param {string} recordId
+ * @param {object} options  (merged into retire options + runner options)
+ */
+export async function retire(
+  recordId,
+  { store, workspace, agent, sessionId, ...retireOpts } = {}
+) {
+  const runner = new KnowledgeFlowRunner({ store, workspace, agent, sessionId });
+  return runner.retire(recordId, retireOpts);
+}
+
 export default KnowledgeFlowRunner;
+
+/**
+ * Module-level extractEntities: creates an ephemeral runner using the provided store.
+ *
+ * @param {string} compiledId
+ * @param {object} options  (merged into extractEntities options + runner options)
+ */
+export async function extractEntities(
+  compiledId,
+  { store, workspace, agent, sessionId, ...extractOpts } = {}
+) {
+  const runner = new KnowledgeFlowRunner({ store, workspace, agent, sessionId });
+  return runner.extractEntities(compiledId, extractOpts);
+}
+
+/**
+ * Module-level mergePerson: creates an ephemeral runner using the provided store.
+ *
+ * @param {string} primaryId
+ * @param {string} duplicateId
+ * @param {object} options
+ */
+export async function mergePerson(
+  primaryId,
+  duplicateId,
+  { store, workspace, agent, sessionId, ...mergeOpts } = {}
+) {
+  const runner = new KnowledgeFlowRunner({ store, workspace, agent, sessionId });
+  return runner.mergePerson(primaryId, duplicateId, mergeOpts);
+}