loopgraph 0.1.0 → 0.2.1

package/dist/adapters/agenthub/extract.d.ts

@@ -22,19 +22,8 @@
  * didn't change still needs re-extraction if the extractor did).
  */
 export declare const ADAPTER_VERSION = "agenthub-facts-1";
-export type SignalKind = "pg_boss_queue" | "setinterval_poller";
-export interface ImplementationFact {
-    signal: SignalKind;
-    /** The queue name, or the poller's enclosing function/file marker. */
-    name: string;
-    filePath: string;
-    /** 1-based line for a human reading the report — not a stable anchor. */
-    line: number;
-    /** Extra context: e.g. "env-suffixed" for a QUEUE_SUFFIX template, or the interval. */
-    detail?: string;
-    /** true when the fact's key part (queue name / interval) couldn't be read statically. */
-    unanalyzable?: boolean;
-}
+export type { ImplementationFact, SignalKind } from "../types.js";
+import type { ImplementationFact } from "../types.js";
 /**
  * pg-boss queue names. In this target stack the authoritative names live in
  * `const *_QUEUE = <string | template>` declarations (e.g.

package/dist/adapters/agenthub/facts.d.ts

@@ -1,5 +1,5 @@
 import type { Adapter } from "../types.js";
-import type { ImplementationFact } from "./extract.js";
+import type { ImplementationFact } from "../types.js";
 export interface FactsOptions {
     /**
      * Machine-level content cache dir (B3). Defaults to `~/.cache/loopgraph`;

package/dist/adapters/registry.js

@@ -1,12 +1,15 @@
 import { agenthubAdapter } from "./agenthub/index.js";
+import { rushAdapter } from "./rush/index.js";
 /**
  * The adapter registry (E1): the single place the engine resolves an adapter by
  * name. A new target stack registers here and everything else — the fact
- * runner, the cache key, the INV-1 default config — flows through the Adapter
- * interface without further engine changes.
+ * runner, the cache key — flows through the Adapter interface without further
+ * engine changes. `rush` (GATE-3) is the proof: registering it here is the ONLY
+ * engine-side change a second target required.
  */
 const ADAPTERS = {
     [agenthubAdapter.name]: agenthubAdapter,
+    [rushAdapter.name]: rushAdapter,
 };
 export function getAdapter(name) {
     return ADAPTERS[name];

package/dist/adapters/rush/extract.d.ts

@@ -0,0 +1,36 @@
+import type { ImplementationFact } from "../types.js";
+/**
+ * rush adapter — implementation-fact extraction (Proposal 006 E2 / GATE-3, the
+ * second target stack). PURE functions of `(filePath, content)`, an in-memory
+ * `ts.createSourceFile` parse, no I/O — same cacheable posture as the agenthub
+ * adapter.
+ *
+ * rush's background-signal profile differs from agenthub's: it has no pg-boss
+ * queue backend; async fan-out goes through Redis pub/sub channels, plus the
+ * usual setInterval pollers. So this adapter extracts (1) Redis channels and
+ * (2) setInterval pollers. It is fully independent of the agenthub adapter — no
+ * shared extractor logic (they're structurally similar but semantically distinct
+ * per-target extension points; extract a common core only once a 3rd adapter
+ * exists and the real invariants are known, not from n=2).
+ */
+/** Bumped when THIS adapter's extractor logic changes — part of the B3 cache key. */
+export declare const RUSH_ADAPTER_VERSION = "rush-facts-1";
+/**
+ * Redis pub/sub channels. rush's convention is `const *channel* = <string |
+ * template>` referenced by identifier at `.publish(channel, ...)` /
+ * `.subscribe(channel)` call sites; a direct string literal AT the call site is
+ * also captured. The `*channel*` const-name convention is rush-adapter
+ * knowledge — exactly what an adapter is allowed to encode. Deduped by name.
+ */
+export declare function extractRedisChannels(filePath: string, content: string): ImplementationFact[];
+/**
+ * setInterval poller registrations — bare (`setInterval(...)`) or off an object
+ * (`globalThis.setInterval(...)`). Numeric-literal interval → detail; a
+ * variable/expression interval → unanalyzable. (setInterval is a Node global,
+ * not rush-specific — but kept local to this adapter rather than shared with
+ * agenthub until a 3rd adapter justifies extraction.)
+ */
+export declare function extractPollers(filePath: string, content: string): ImplementationFact[];
+/** Runs every rush extractor over one file. */
+export declare function extractFacts(filePath: string, content: string): ImplementationFact[];
+//# sourceMappingURL=extract.d.ts.map

package/dist/adapters/rush/extract.js

@@ -0,0 +1,125 @@
+import ts from "typescript";
+/**
+ * rush adapter — implementation-fact extraction (Proposal 006 E2 / GATE-3, the
+ * second target stack). PURE functions of `(filePath, content)`, an in-memory
+ * `ts.createSourceFile` parse, no I/O — same cacheable posture as the agenthub
+ * adapter.
+ *
+ * rush's background-signal profile differs from agenthub's: it has no pg-boss
+ * queue backend; async fan-out goes through Redis pub/sub channels, plus the
+ * usual setInterval pollers. So this adapter extracts (1) Redis channels and
+ * (2) setInterval pollers. It is fully independent of the agenthub adapter — no
+ * shared extractor logic (they're structurally similar but semantically distinct
+ * per-target extension points; extract a common core only once a 3rd adapter
+ * exists and the real invariants are known, not from n=2).
+ */
+/** Bumped when THIS adapter's extractor logic changes — part of the B3 cache key. */
+export const RUSH_ADAPTER_VERSION = "rush-facts-1";
+function lineOf(src, node) {
+    return src.getLineAndCharacterOfPosition(node.getStart(src)).line + 1;
+}
+/**
+ * The static name of a string/template expression, or null if not statically
+ * known. Template statics are joined with "…" across the dynamic `${}` gaps —
+ * e.g. `` `events:${id}` `` → "events:"; a fully dynamic template → "<dynamic>".
+ */
+function channelNameOf(expr) {
+    if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr))
+        return { name: expr.text };
+    if (ts.isTemplateExpression(expr)) {
+        const staticParts = [expr.head.text, ...expr.templateSpans.map((s) => s.literal.text)].filter(Boolean);
+        if (staticParts.length === 0)
+            return { name: "<dynamic>", detail: "interpolated" };
+        return { name: staticParts.join("…"), detail: "interpolated" };
+    }
+    return null;
+}
+/**
+ * Redis pub/sub channels. rush's convention is `const *channel* = <string |
+ * template>` referenced by identifier at `.publish(channel, ...)` /
+ * `.subscribe(channel)` call sites; a direct string literal AT the call site is
+ * also captured. The `*channel*` const-name convention is rush-adapter
+ * knowledge — exactly what an adapter is allowed to encode. Deduped by name.
+ */
+export function extractRedisChannels(filePath, content) {
+    const src = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const facts = [];
+    const seen = new Set();
+    const PUBSUB_METHODS = new Set(["publish", "subscribe"]);
+    const push = (name, node, detail) => {
+        if (seen.has(name))
+            return;
+        seen.add(name);
+        facts.push({
+            signal: "redis_channel",
+            name,
+            filePath,
+            line: lineOf(src, node),
+            ...(detail ? { detail } : {}),
+        });
+    };
+    function visit(node) {
+        // `const *channel* = <string | template>` — the authoritative channel-name decl.
+        // Case-INSENSITIVE "channel" (rush uses lowercase `channel` locals and
+        // SCREAMING_SNAKE `*_CHANNEL` consts alike).
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.name.text.toLowerCase().includes("channel") &&
+            node.initializer) {
+            const c = channelNameOf(node.initializer);
+            if (c)
+                push(c.name, node, c.detail);
+        }
+        // Direct string-literal `.publish/.subscribe("channel", ...)` call sites.
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            PUBSUB_METHODS.has(node.expression.name.text)) {
+            const arg0 = node.arguments[0];
+            const c = arg0 ? channelNameOf(arg0) : null;
+            if (c)
+                push(c.name, node, c.detail);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(src);
+    return facts;
+}
+/**
+ * setInterval poller registrations — bare (`setInterval(...)`) or off an object
+ * (`globalThis.setInterval(...)`). Numeric-literal interval → detail; a
+ * variable/expression interval → unanalyzable. (setInterval is a Node global,
+ * not rush-specific — but kept local to this adapter rather than shared with
+ * agenthub until a 3rd adapter justifies extraction.)
+ */
+export function extractPollers(filePath, content) {
+    const src = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const facts = [];
+    const isSetInterval = (expr) => (ts.isIdentifier(expr) && expr.text === "setInterval") ||
+        (ts.isPropertyAccessExpression(expr) && expr.name.text === "setInterval") ||
+        (ts.isElementAccessExpression(expr) &&
+            ts.isStringLiteral(expr.argumentExpression) &&
+            expr.argumentExpression.text === "setInterval");
+    function visit(node) {
+        if (ts.isCallExpression(node) && isSetInterval(node.expression)) {
+            const intervalArg = node.arguments[1];
+            const literalMs = intervalArg && ts.isNumericLiteral(intervalArg) ? intervalArg.text : undefined;
+            facts.push({
+                signal: "setinterval_poller",
+                name: `setInterval@${filePath}:${lineOf(src, node)}`,
+                filePath,
+                line: lineOf(src, node),
+                ...(literalMs
+                    ? { detail: `${literalMs}ms` }
+                    : { detail: "dynamic interval", unanalyzable: true }),
+            });
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(src);
+    return facts;
+}
+/** Runs every rush extractor over one file. */
+export function extractFacts(filePath, content) {
+    return [...extractRedisChannels(filePath, content), ...extractPollers(filePath, content)];
+}
+//# sourceMappingURL=extract.js.map

package/dist/adapters/rush/index.d.ts

@@ -0,0 +1,10 @@
+import type { Adapter } from "../types.js";
+/**
+ * The rush (rush-app) adapter behind the engine's Adapter interface (E2 /
+ * GATE-3). Proves the engine↔adapter seam generalizes to a second, differently
+ * shaped stack (Redis pub/sub + setInterval, no pg-boss) without touching the
+ * engine or the agenthub adapter. Ships no defaultInv1Config — a target's
+ * guarded-writer config lives in its own loopgraph.config.json.
+ */
+export declare const rushAdapter: Adapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/rush/index.js

@@ -0,0 +1,15 @@
+import { RUSH_ADAPTER_VERSION, extractFacts } from "./extract.js";
+/**
+ * The rush (rush-app) adapter behind the engine's Adapter interface (E2 /
+ * GATE-3). Proves the engine↔adapter seam generalizes to a second, differently
+ * shaped stack (Redis pub/sub + setInterval, no pg-boss) without touching the
+ * engine or the agenthub adapter. Ships no defaultInv1Config — a target's
+ * guarded-writer config lives in its own loopgraph.config.json.
+ */
+export const rushAdapter = {
+    name: "rush",
+    version: RUSH_ADAPTER_VERSION,
+    candidatePattern: "setInterval\\(|\\.(publish|subscribe)\\(",
+    extractFacts,
+};
+//# sourceMappingURL=index.js.map

package/dist/adapters/types.d.ts

@@ -1,5 +1,30 @@
 import type { Inv1Config } from "../validate/inv1/config.js";
-import type { ImplementationFact } from "./agenthub/extract.js";
+/**
+ * The kind of implementation signal a fact represents. An OPEN string, not a
+ * closed union: each adapter names its own signal kinds (agenthub:
+ * `pg_boss_queue` / `setinterval_poller`; rush: `redis_channel` / …). The
+ * engine treats it opaquely — it never enumerates every adapter's kinds — so a
+ * new adapter adds signals without the engine changing.
+ */
+export type SignalKind = string;
+/**
+ * One extracted implementation signal (a "registerable" background unit the
+ * behavioral model is supposed to account for). Lives here on the engine↔adapter
+ * boundary — NOT inside any one adapter — so every adapter and the engine share
+ * one contract instead of importing it from a sibling adapter.
+ */
+export interface ImplementationFact {
+    signal: SignalKind;
+    /** The queue/channel/… name, or the poller's enclosing function/file marker. */
+    name: string;
+    filePath: string;
+    /** 1-based line for a human reading the report — not a stable anchor. */
+    line: number;
+    /** Extra context: e.g. "env-suffixed" for a templated name, or the interval. */
+    detail?: string;
+    /** true when the fact's key part (name / interval) couldn't be read statically. */
+    unanalyzable?: boolean;
+}
 /**
  * The engine↔adapter boundary (Proposal 006 E1 / 001 §2 三分离, Phase 5
  * generalization). The ENGINE (loader, T0, INV-1 scan primitive, query, cache,

package/dist/cli/commands/snapshot.d.ts

@@ -1,4 +1,4 @@
-import type { ImplementationFact, SignalKind } from "../../adapters/agenthub/extract.js";
+import type { Adapter, ImplementationFact, SignalKind } from "../../adapters/types.js";
 import { type Inv1CheckResult } from "../../validate/inv1/check.js";
 import type { T0Result } from "../../validate/types.js";
 export declare const SNAPSHOT_SCHEMA_VERSION: 1;
@@ -98,6 +98,8 @@ export interface SnapshotOptions {
     repoRoot?: string | undefined;
     /** Machine cache dir for facts (B3); null disables. Default: the shared cache. */
     cacheDir?: string | null | undefined;
+    /** The adapter supplying the facts (default: agenthub). Threaded to runFacts. */
+    adapter?: Adapter | undefined;
     /** Injected for reproducibility; defaults to now. */
     generatedAt?: string | undefined;
     /** Injected for tests; defaults to `git rev-parse HEAD` of repoRoot. */

package/dist/cli/run.js

@@ -1,4 +1,5 @@
 import { runFacts } from "../adapters/agenthub/facts.js";
+import { adapterNames, getAdapter } from "../adapters/registry.js";
 import { loadModel } from "../loader/load-model.js";
 import { startMcpServer } from "../mcp/server.js";
 import { runQuery } from "../query/run-query.js";
@@ -28,7 +29,7 @@ const USAGE = "usage: loopgraph <init|import|check> [dir] [--adapter name] [--re
     "       loopgraph inspect <node-id> [dir] [--depth n]\n" +
     "       loopgraph <impact|plan|scenario|evidence|matrix> <id> [dir]\n" +
     "       loopgraph mcp [dir]   # start the stdio MCP server\n" +
-    "       loopgraph facts [repo]   # extract implementation facts (pg-boss queues, pollers)\n" +
+    "       loopgraph facts [repo] [--adapter name]   # extract implementation facts (default adapter: agenthub)\n" +
     "       loopgraph snapshot [dir] --repo-root path [--out file] [--drift prior.json]   # T2 nightly scan artifact";
 /**
  * Reads a `--flag value` string option. Returns `{ error }` when the flag
@@ -47,6 +48,27 @@ function readStringFlag(flags, name) {
         return { value: raw };
     return { value: undefined, error: `--${name} requires a value` };
 }
+/**
+ * Resolve `--adapter <name>` for the fact-extracting commands (facts /
+ * reconcile / snapshot). Returns `{}` (no `adapter` key) when the flag is absent
+ * — the caller then falls back to the default adapter — or `{ error: true }`
+ * after reporting a malformed flag / unknown adapter name.
+ */
+function resolveAdapterFlag(flags, io) {
+    const f = readStringFlag(flags, "adapter");
+    if (f.error) {
+        io.error(`${f.error}. ${USAGE}`);
+        return { error: true };
+    }
+    if (f.value === undefined)
+        return {}; // no --adapter → caller uses the default
+    const adapter = getAdapter(f.value);
+    if (!adapter) {
+        io.error(`unknown adapter "${f.value}" (available: ${adapterNames().join(", ")})`);
+        return { error: true };
+    }
+    return { adapter };
+}
 /**
  * Core dispatch, factored out of the process entry point so tests can
  * drive it in-process (real filesystem via temp dirs, no subprocess
@@ -214,8 +236,15 @@ export async function run(argv, io) {
         case "facts": {
             // Extract implementation facts from a target repo (positionals[0] = repo
             // root, defaulting to cwd). `--no-cache` disables the B3 content cache.
+            // `--adapter <name>` selects the target stack's adapter (default agenthub).
             const repo = positionals[0] ?? process.cwd();
-            const result = await runFacts(repo, flags["no-cache"] === true ? { cacheDir: null } : {});
+            const factsAdapter = resolveAdapterFlag(flags, io);
+            if ("error" in factsAdapter)
+                return 1;
+            const result = await runFacts(repo, {
+                ...(flags["no-cache"] === true ? { cacheDir: null } : {}),
+                ...(factsAdapter.adapter ? { adapter: factsAdapter.adapter } : {}),
+            });
             if (!result.ran) {
                 io.log(`⚠ facts extraction skipped: ${result.skippedReason}`);
                 return 0;
@@ -246,8 +275,14 @@ export async function run(argv, io) {
                 io.error(`reconcile needs --repo-root <repo>. ${USAGE}`);
                 return 1;
             }
+            const reconcileAdapter = resolveAdapterFlag(flags, io);
+            if ("error" in reconcileAdapter)
+                return 1;
             const model = await loadModel(`${targetDir}/model`);
-            const factsResult = await runFacts(repoRootFlag.value, flags["no-cache"] === true ? { cacheDir: null } : {});
+            const factsResult = await runFacts(repoRootFlag.value, {
+                ...(flags["no-cache"] === true ? { cacheDir: null } : {}),
+                ...(reconcileAdapter.adapter ? { adapter: reconcileAdapter.adapter } : {}),
+            });
             if (!factsResult.ran) {
                 io.log(`⚠ reconcile skipped: ${factsResult.skippedReason}`);
                 return 0;
@@ -279,9 +314,13 @@ export async function run(argv, io) {
                     return 1;
                 }
             }
+            const snapshotAdapter = resolveAdapterFlag(flags, io);
+            if ("error" in snapshotAdapter)
+                return 1;
             const snapshot = await runSnapshot(targetDir, {
                 repoRoot: repoRootFlag.value,
                 ...(flags["no-cache"] === true ? { cacheDir: null } : {}),
+                ...(snapshotAdapter.adapter ? { adapter: snapshotAdapter.adapter } : {}),
             });
             io.log(renderSnapshotSummary(snapshot));
             if (driftFlag.value) {

package/dist/validate/unregistered.d.ts

@@ -1,4 +1,4 @@
-import type { ImplementationFact } from "../adapters/agenthub/extract.js";
+import type { ImplementationFact } from "../adapters/types.js";
 import type { ModelGraph } from "../loader/model-graph.js";
 /**
  * C2 T1 reconciliation (Proposal 006 Phase 3): which extracted implementation

package/dist/validate/unregistered.js

@@ -81,9 +81,15 @@ export function reconcileFacts(facts, graph) {
     const unregistered = [];
     // Three DISJOINT buckets (active wins over dormant wins over nothing), so
     // `registered`, `dormantSuppressed`, and `unregistered` partition the facts.
-    // A queue fact is active-registered by EITHER its file being anchored OR its
-    // name being declared in some active loop's consumes_queues (producer/consumer
-    // split: the definition file may carry no anchor while the loop is modeled).
+    // EVERY fact — any adapter, any signal kind — reconciles by FILE (the base
+    // mechanism): file anchored → registered. The extra `consumes_queues`
+    // name-match is an OPT-IN, currently only for `pg_boss_queue` (agenthub's
+    // producer/consumer split: a queue defined in an un-anchored registry file
+    // whose loop is modeled elsewhere). Other signals (e.g. rush's
+    // `redis_channel`) are NOT ignored — they just reconcile by file only. If a
+    // second adapter needs the same name-match, generalize this to an
+    // adapter-declared "name-matchable signal kinds" set rather than hardcoding
+    // more kinds here (GATE-3 doesn't need it; file-level reconcile suffices).
     const isActive = (f) => active.has(f.filePath) || (f.signal === "pg_boss_queue" && consumedQueues.has(f.name));
     for (const f of facts) {
         if (isActive(f)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopgraph",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Model-driven engineering control system: behavioral model as spec source of truth, code/tests/observability as projections and evidence.",
   "type": "module",
   "license": "MIT",