instar 0.28.83 → 0.28.85

package/dist/commands/memoryBackfillEvidence.js

@@ -0,0 +1,220 @@
+/**
+ * `instar memory backfill-evidence` — one-shot migration that walks every
+ * existing MemoryEntity, pattern-matches the legacy `source: string` field,
+ * and synthesizes a `MemoryEvidence` row when (and only when) the source
+ * matches a known shape that the `manual` producer is allowed to write.
+ *
+ * Per WikiClaim spec § Migration of Existing MemoryEntity Records (line 202)
+ * and § Risks line 357 ("Backfill is idempotent and uses only the patterns
+ * enumerated above. Anything that doesn't match a known pattern stays
+ * `evidence: []`. No LLM in the migration path.") and line 360 ("Backfill
+ * defaults `privacyTier: undefined` (inherit from entity). No automatic
+ * upgrade to private or sensitive.").
+ *
+ * **Phase 1 narrowed `manual` producer to `external-url` only** (see
+ * `PRODUCER_KIND_ALLOWLIST` in SemanticMemory.ts and the Phase 1 side-effects
+ * artifact). Because of that, the only legacy `source` shape backfill can
+ * cover is an `https?://` URL. Other patterns the spec lists (`session:ABC`,
+ * `user:Justin`, `observation`) would need their own dedicated producer
+ * bridges (e.g., `DecisionJournal` for `session`); attempting them here is
+ * out-of-scope for Phase 5 — we DELIBERATELY do not widen the allowlist to
+ * make migration easier.
+ *
+ * Idempotency: before writing, the command queries the entity's existing
+ * evidence rows; if an `external-url` row with the same path already exists,
+ * the entity is skipped. Two consecutive `--apply` runs produce identical
+ * end state.
+ */
+import path from 'node:path';
+import pc from 'picocolors';
+import { loadConfig } from '../core/Config.js';
+import { SemanticMemory } from '../memory/SemanticMemory.js';
+/**
+ * URL pattern: a complete `http://` or `https://` URL as the ENTIRE source
+ * string (anchored). We deliberately do NOT extract URLs embedded inside
+ * other text — extracting partial URLs creates ambiguity about what the
+ * "real" source was and re-runs could backfill different URLs from the same
+ * source string as the matcher evolves. Anchoring keeps the migration
+ * deterministic.
+ *
+ * Allowed: `https://example.com/path`, `http://localhost:8080/x?y=z`
+ * Rejected: `session:ABC`, `user:Justin`, `observation`, `see https://...`
+ */
+const URL_SOURCE_PATTERN = /^https?:\/\/\S+$/;
+/**
+ * Public entry: runs the backfill against the SemanticMemory in the given
+ * state directory. Returns a structured summary for tests / callers that
+ * want to assert on outcomes; the CLI wrapper prints the same data.
+ */
+export async function runBackfillEvidence(opts) {
+    const config = loadConfig(opts.dir);
+    const memory = new SemanticMemory({
+        dbPath: path.join(config.stateDir, 'semantic.db'),
+        decayHalfLifeDays: 30,
+        lessonDecayHalfLifeDays: 90,
+        staleThreshold: 0.2,
+    });
+    await memory.open();
+    try {
+        return backfillAgainstMemory(memory, opts);
+    }
+    finally {
+        memory.close();
+    }
+}
+/**
+ * Test-friendly seam: takes an open SemanticMemory instance directly. The
+ * CLI wrapper threads loadConfig + open + close around it; tests skip the
+ * config dance and pass a memory created against a tmp dir.
+ */
+export function backfillAgainstMemory(memory, opts) {
+    const viewerScope = opts.viewerScope ?? 'private';
+    const dryRun = !!opts.dryRun;
+    const { entities } = memory.export();
+    const summary = {
+        scanned: 0,
+        backfilled: 0,
+        skipped: 0,
+        errors: 0,
+        details: [],
+    };
+    for (const entity of entities) {
+        summary.scanned++;
+        const source = entity.source ?? '';
+        // Pattern-match URL only. Everything else is a deliberate skip per
+        // spec § Risks line 357 (no LLM, only known patterns).
+        if (!URL_SOURCE_PATTERN.test(source)) {
+            summary.skipped++;
+            summary.details.push({
+                entityId: entity.id,
+                source,
+                outcome: 'no-pattern-match',
+            });
+            continue;
+        }
+        // Idempotency: if an existing external-url evidence row already cites
+        // this URL, skip. We read at the WIDEST viewer scope (default 'private',
+        // configurable for tests) so the dup-check sees every existing row —
+        // a narrow read could miss a row tagged `private` on a `shared-project`
+        // entity and cause a duplicate write.
+        let existing;
+        try {
+            existing = memory.getEvidence(entity.id, viewerScope);
+        }
+        catch (err) {
+            summary.errors++;
+            summary.details.push({
+                entityId: entity.id,
+                source,
+                outcome: 'error',
+                note: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
+        const alreadyHas = existing.some((ev) => ev.kind === 'external-url' &&
+            (ev.path === source || ev.sourceId === source));
+        if (alreadyHas) {
+            summary.skipped++;
+            summary.details.push({
+                entityId: entity.id,
+                source,
+                outcome: 'already-has-url-evidence',
+            });
+            continue;
+        }
+        // Synthesize the evidence row. Per spec § Risks line 360, leave
+        // `privacyTier` undefined so it inherits from the entity's scope —
+        // never auto-upgrade to `private` / `sensitive`.
+        const synthesized = {
+            kind: 'external-url',
+            // For URLs, sourceId == path == the URL itself. Spec § Producers
+            // line 229 keys 'manual external-url' on the URL value as both
+            // dedupe identity and display path.
+            sourceId: source,
+            path: source,
+            // updatedAt uses entity's createdAt — preserves temporal ordering
+            // and means a second run on the same row produces identical content.
+            updatedAt: entity.createdAt,
+            // Caller-set confidence/weight per spec § Open Questions; coarse
+            // legacy provenance gets a low-confidence float matching the spec's
+            // suggested 0.5 for migrated rows.
+            confidence: 0.5,
+            note: 'Backfilled from legacy MemoryEntity.source (Phase 5 migration)',
+        };
+        if (dryRun) {
+            summary.backfilled++;
+            summary.details.push({
+                entityId: entity.id,
+                source,
+                outcome: 'backfilled',
+                note: 'dry-run (not written)',
+            });
+            continue;
+        }
+        try {
+            memory.addEvidence(entity.id, synthesized, 'manual');
+            summary.backfilled++;
+            summary.details.push({
+                entityId: entity.id,
+                source,
+                outcome: 'backfilled',
+            });
+        }
+        catch (err) {
+            summary.errors++;
+            summary.details.push({
+                entityId: entity.id,
+                source,
+                outcome: 'error',
+                note: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return summary;
+}
+/**
+ * Commander entry-point. Prints a human-readable report; structured callers
+ * use `runBackfillEvidence` directly.
+ */
+export async function memoryBackfillEvidence(opts) {
+    try {
+        const summary = await runBackfillEvidence(opts);
+        console.log(pc.bold('\n  Memory backfill-evidence\n'));
+        if (opts.dryRun) {
+            console.log(pc.yellow('  Dry-run: no writes performed.\n'));
+        }
+        console.log(`  Scanned:    ${summary.scanned}`);
+        console.log(`  Backfilled: ${pc.green(String(summary.backfilled))}`);
+        console.log(`  Skipped:    ${summary.skipped}`);
+        if (summary.errors > 0) {
+            console.log(`  Errors:     ${pc.red(String(summary.errors))}`);
+        }
+        else {
+            console.log(`  Errors:     ${summary.errors}`);
+        }
+        // Show details only when there's something interesting to look at.
+        const interesting = summary.details.filter((d) => d.outcome === 'backfilled' || d.outcome === 'error');
+        if (interesting.length > 0) {
+            console.log();
+            for (const d of interesting) {
+                const tag = d.outcome === 'backfilled'
+                    ? pc.green('  +')
+                    : pc.red('  !');
+                const noteStr = d.note ? pc.dim(` — ${d.note}`) : '';
+                console.log(`${tag} ${d.entityId}  ${pc.dim(d.source)}${noteStr}`);
+            }
+        }
+        console.log();
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes('better-sqlite3')) {
+            console.log(pc.yellow('Backfill requires better-sqlite3.'));
+            console.log(pc.dim('Install it with: npm install better-sqlite3'));
+        }
+        else {
+            console.log(pc.red(`Backfill failed: ${err instanceof Error ? err.message : err}`));
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=memoryBackfillEvidence.js.map

package/dist/commands/memoryBackfillEvidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryBackfillEvidence.js","sourceRoot":"","sources":["../../src/commands/memoryBackfillEvidence.ts"],"names":[],"mappings":"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"}

package/dist/commands/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiQH,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAg4CD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4yJtE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD5E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiQH,UAAU,YAAY;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;2DACuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAg4CD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAu4JtE;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD5E"}

package/dist/commands/server.js

@@ -5718,8 +5718,93 @@ export async function startServer(options) {
         }
         const { InitiativeTracker } = await import('../core/InitiativeTracker.js');
         const initiativeTracker = new InitiativeTracker(config.stateDir);
-        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, feedbackAnomalyDetector, dispatches, updateChecker, autoUpdater, autoDispatcher, quotaTracker, quotaManager, publisher, viewer, tunnel, evolution, watchdog, topicMemory, triageNurse, projectMapper, coherenceGate: scopeVerifier, contextHierarchy, canonicalState, operationGate, sentinel, adaptiveTrust, memoryMonitor, orphanReaper, coherenceMonitor, commitmentTracker, semanticMemory, activitySentinel, messageRouter, summarySentinel, spawnManager, systemReviewer, capabilityMapper, selfKnowledgeTree, coverageAuditor, topicResumeMap: _topicResumeMap ?? undefined, autonomyManager, trustElevationTracker, autonomousEvolution, coordinator: coordinator.enabled ? coordinator : undefined, localSigningKeyPem, whatsapp: whatsappAdapter, slack: slackAdapter, imessage: imessageAdapter, whatsappBusinessBackend, messageBridge, hookEventReceiver, worktreeMonitor, subagentTracker, instructionsVerifier, handshakeManager: threadlineHandshake, threadlineRouter, threadlineRelayClient, threadlineReplyWaiters, listenerManager: listenerManager ?? undefined, responseReviewGate, messagingToneGate, outboundDedupGate, telemetryHeartbeat, pasteManager, featureRegistry, discoveryEvaluator, unifiedTrust, liveConfig, sharedStateLedger, ledgerSessionRegistry, worktreeManager, oidcEnrolledRepos: parallelDevConfig?.oidcEnrolledRepos, initiativeTracker, proxyCoordinator, telegramBridgeConfig, telegramBridge: telegramBridge ?? undefined, threadlineObservability, workingMemory });
+        // TaskFlow registry — opt-in via config.taskFlow.enabled (default: off in v1).
+        // Owns its own SQLite file under .instar/task-flows.db. The maintenance
+        // sweeper and due-waker start with the registry; both .unref() their timers
+        // so they never keep the process alive on shutdown.
+        let taskFlowRegistry;
+        let taskFlowSweeper;
+        let taskFlowDueWaker;
+        let threadlineFlowBridge;
+        let divergenceChecker;
+        if (config.taskFlow?.enabled) {
+            try {
+                const { TaskFlowStore } = await import('../tasks/task-flow-registry.store.sqlite.js');
+                const { TaskFlowRegistry } = await import('../tasks/TaskFlowRegistry.js');
+                const { TaskFlowMaintenanceSweeper } = await import('../tasks/TaskFlowMaintenanceSweeper.js');
+                const { TaskFlowDueWaker } = await import('../tasks/TaskFlowDueWaker.js');
+                const path = await import('node:path');
+                const dbPath = path.default.join(config.stateDir, 'task-flows.db');
+                const store = new TaskFlowStore({ dbPath });
+                await store.open();
+                taskFlowRegistry = new TaskFlowRegistry({
+                    store,
+                    ledger: sharedStateLedger ?? undefined,
+                    thresholds: config.taskFlow?.thresholds,
+                    // Phase 5: rate limits + cache cap. Each field has a documented
+                    // default in DEFAULT_RATE_LIMITS / DEFAULT_CACHE_CONFIG.
+                    rateLimits: config.taskFlow?.rateLimits,
+                    cache: config.taskFlow?.cache,
+                });
+                taskFlowSweeper = new TaskFlowMaintenanceSweeper({
+                    registry: taskFlowRegistry,
+                    store,
+                    ledger: sharedStateLedger ?? undefined,
+                });
+                taskFlowDueWaker = new TaskFlowDueWaker({ registry: taskFlowRegistry });
+                taskFlowSweeper.start();
+                taskFlowDueWaker.start();
+                const { ThreadlineFlowBridge } = await import('../tasks/ThreadlineFlowBridge.js');
+                threadlineFlowBridge = new ThreadlineFlowBridge({ registry: taskFlowRegistry });
+                // Phase 3a — wire EvolutionManager dual-write + divergence checker.
+                const crypto = await import('node:crypto');
+                const controllerInstanceId = crypto.randomUUID();
+                evolution.setTaskFlowRegistry(taskFlowRegistry, controllerInstanceId);
+                // Backfill in-flight clusters into TaskFlow. Idempotent via
+                // `evolution-cluster-create-<id>` idempotency key.
+                try {
+                    const migrationReport = await evolution.migrateExistingToTaskFlow();
+                    console.log(pc.green(`  TaskFlow: backfilled evolution clusters created=${migrationReport.created} ` +
+                        `existed=${migrationReport.alreadyExisted} advanced=${migrationReport.advanced} ` +
+                        `skipped=${migrationReport.skipped}`));
+                }
+                catch (err) {
+                    console.warn('[instar] taskflow evolution backfill failed (non-fatal):', err);
+                }
+                const { DivergenceChecker } = await import('../tasks/DivergenceChecker.js');
+                divergenceChecker = new DivergenceChecker({
+                    registry: taskFlowRegistry,
+                    evolutionManager: evolution,
+                    ledger: sharedStateLedger ?? undefined,
+                });
+                divergenceChecker.start();
+                // Phase 4 — wire InitiativeTracker to TaskFlow as the single source of
+                // truth. Backfill any initiatives present in the legacy
+                // `initiatives.json` file. Idempotent via `findIdempotent` on
+                // `(controllerId="InitiativeTracker", ownerKey, idempotencyKey)`.
+                initiativeTracker.setTaskFlowRegistry(taskFlowRegistry, controllerInstanceId);
+                try {
+                    const initiativeReport = await initiativeTracker.migrateExistingToTaskFlow();
+                    console.log(pc.green(`  TaskFlow: backfilled initiatives created=${initiativeReport.created} ` +
+                        `existed=${initiativeReport.alreadyExisted} advanced=${initiativeReport.advanced} ` +
+                        `skipped=${initiativeReport.skipped}`));
+                }
+                catch (err) {
+                    console.warn('[instar] taskflow initiative backfill failed (non-fatal):', err);
+                }
+            }
+            catch (err) {
+                console.warn('[instar] task-flow init failed (non-fatal):', err);
+                taskFlowRegistry = undefined;
+                threadlineFlowBridge = undefined;
+                divergenceChecker = undefined;
+            }
+        }
+        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, feedbackAnomalyDetector, dispatches, updateChecker, autoUpdater, autoDispatcher, quotaTracker, quotaManager, publisher, viewer, tunnel, evolution, watchdog, topicMemory, triageNurse, projectMapper, coherenceGate: scopeVerifier, contextHierarchy, canonicalState, operationGate, sentinel, adaptiveTrust, memoryMonitor, orphanReaper, coherenceMonitor, commitmentTracker, semanticMemory, activitySentinel, messageRouter, summarySentinel, spawnManager, systemReviewer, capabilityMapper, selfKnowledgeTree, coverageAuditor, topicResumeMap: _topicResumeMap ?? undefined, autonomyManager, trustElevationTracker, autonomousEvolution, coordinator: coordinator.enabled ? coordinator : undefined, localSigningKeyPem, whatsapp: whatsappAdapter, slack: slackAdapter, imessage: imessageAdapter, whatsappBusinessBackend, messageBridge, hookEventReceiver, worktreeMonitor, subagentTracker, instructionsVerifier, handshakeManager: threadlineHandshake, threadlineRouter, threadlineRelayClient, threadlineReplyWaiters, listenerManager: listenerManager ?? undefined, responseReviewGate, messagingToneGate, outboundDedupGate, telemetryHeartbeat, pasteManager, featureRegistry, discoveryEvaluator, unifiedTrust, liveConfig, sharedStateLedger, ledgerSessionRegistry, worktreeManager, oidcEnrolledRepos: parallelDevConfig?.oidcEnrolledRepos, initiativeTracker, proxyCoordinator, telegramBridgeConfig, telegramBridge: telegramBridge ?? undefined, threadlineObservability, workingMemory, taskFlowRegistry, threadlineFlowBridge });
         await server.start();
+        void taskFlowSweeper;
+        void taskFlowDueWaker;
+        void divergenceChecker;
         // Connect DegradationReporter downstream systems now that everything is initialized.
         // Any degradation events queued during startup will drain to feedback + telegram.
         {