@descryy/mcp 0.9.0 → 0.11.0

package/dist/heartbeat.d.ts

@@ -0,0 +1,46 @@
+/**
+ * P6-B2 — a periodic progress beat for the duration of one long awaited step.
+ *
+ * `analyze` on a 7,700-file repository reliably exceeded the calling client's
+ * timeout even with the heap ceiling raised, and completed only when driven
+ * over stdio with no client-side timeout at all. It was not hung; it emitted
+ * one `notifications/progress` frame per *source*, so on a repo with a single
+ * language adapter the whole multi-minute read fell between two frames. MCP
+ * clients reset a request's timeout when a progress frame arrives for it, so a
+ * correct run and a wedged one were indistinguishable from the outside, and
+ * the timeout fired on the correct one.
+ *
+ * ## What this is not
+ *
+ * It does not make anything faster, and it is not a guarantee: resetting a
+ * timeout on progress is a client behaviour, not something the protocol
+ * obliges. That is why the elapsed time goes *in* the message rather than the
+ * beat being a bare ping — a caller reading the frames can see the step
+ * advancing rather than being asserted to. Honest degradation (rule 7) cuts
+ * both ways here: this discloses that work is ongoing, it does not claim
+ * progress it cannot measure. The adapter is opaque while it runs, so the
+ * count of files done is not available to report and none is invented.
+ */
+/** Interval between beats while a step is running. Well inside the 60s default most clients use. */
+export declare const HEARTBEAT_MS = 15000;
+export declare const HEARTBEAT_ENV_VAR = "DESCRY_PROGRESS_HEARTBEAT_MS";
+/**
+ * The interval in force, honouring `DESCRY_PROGRESS_HEARTBEAT_MS`.
+ *
+ * A zero, a negative or an unreadable value falls back to the default rather
+ * than being taken literally: zero is a busy loop and not a plausible way to
+ * ask for one, so reading it as "the operator meant to disable beats" would
+ * turn a typo into the exact silence this module removes.
+ */
+export declare function heartbeatMs(): number;
+/**
+ * Run `work`, beating `label` plus elapsed seconds every `intervalMs` until it
+ * settles.
+ *
+ * The timer is cleared in a `finally`, so a step that throws stops beating on
+ * the same tick it fails — a beat outliving its step would report a run that
+ * has already finished or died. `unref()` keeps a pending beat from holding
+ * the process open on its own.
+ */
+export declare function withHeartbeat<T>(label: string, beat: (message: string) => void, work: () => Promise<T>, intervalMs?: number): Promise<T>;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,oGAAoG;AACpG,eAAO,MAAM,YAAY,QAAS,CAAC;AAEnC,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,UAAU,GAAE,MAAsB,GACjC,OAAO,CAAC,CAAC,CAAC,CAWZ"}

package/dist/heartbeat.js

@@ -0,0 +1,66 @@
+/**
+ * P6-B2 — a periodic progress beat for the duration of one long awaited step.
+ *
+ * `analyze` on a 7,700-file repository reliably exceeded the calling client's
+ * timeout even with the heap ceiling raised, and completed only when driven
+ * over stdio with no client-side timeout at all. It was not hung; it emitted
+ * one `notifications/progress` frame per *source*, so on a repo with a single
+ * language adapter the whole multi-minute read fell between two frames. MCP
+ * clients reset a request's timeout when a progress frame arrives for it, so a
+ * correct run and a wedged one were indistinguishable from the outside, and
+ * the timeout fired on the correct one.
+ *
+ * ## What this is not
+ *
+ * It does not make anything faster, and it is not a guarantee: resetting a
+ * timeout on progress is a client behaviour, not something the protocol
+ * obliges. That is why the elapsed time goes *in* the message rather than the
+ * beat being a bare ping — a caller reading the frames can see the step
+ * advancing rather than being asserted to. Honest degradation (rule 7) cuts
+ * both ways here: this discloses that work is ongoing, it does not claim
+ * progress it cannot measure. The adapter is opaque while it runs, so the
+ * count of files done is not available to report and none is invented.
+ */
+/** Interval between beats while a step is running. Well inside the 60s default most clients use. */
+export const HEARTBEAT_MS = 15_000;
+export const HEARTBEAT_ENV_VAR = "DESCRY_PROGRESS_HEARTBEAT_MS";
+/**
+ * The interval in force, honouring `DESCRY_PROGRESS_HEARTBEAT_MS`.
+ *
+ * A zero, a negative or an unreadable value falls back to the default rather
+ * than being taken literally: zero is a busy loop and not a plausible way to
+ * ask for one, so reading it as "the operator meant to disable beats" would
+ * turn a typo into the exact silence this module removes.
+ */
+export function heartbeatMs() {
+    const raw = process.env[HEARTBEAT_ENV_VAR];
+    if (raw === undefined)
+        return HEARTBEAT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return HEARTBEAT_MS;
+    return parsed;
+}
+/**
+ * Run `work`, beating `label` plus elapsed seconds every `intervalMs` until it
+ * settles.
+ *
+ * The timer is cleared in a `finally`, so a step that throws stops beating on
+ * the same tick it fails — a beat outliving its step would report a run that
+ * has already finished or died. `unref()` keeps a pending beat from holding
+ * the process open on its own.
+ */
+export async function withHeartbeat(label, beat, work, intervalMs = heartbeatMs()) {
+    const started = Date.now();
+    const timer = setInterval(() => {
+        beat(`${label} — still running, ${Math.round((Date.now() - started) / 1000)}s elapsed`);
+    }, intervalMs);
+    timer.unref?.();
+    try {
+        return await work();
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,oGAAoG;AACpG,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAEnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,8BAA8B,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,YAAY,CAAC;IACjE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAa,EACb,IAA+B,EAC/B,IAAsB,EACtB,aAAqB,WAAW,EAAE;IAElC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,CAAC,GAAG,KAAK,qBAAqB,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAC1F,CAAC,EAAE,UAAU,CAAC,CAAC;IACf,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,aAAa,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -22,6 +22,6 @@ export type { RpcRequest, RpcNotification, RpcResponse, RpcMessage, RpcId } from
 /** The scenario format — storage, schema, refusals. Re-exported here so `descry check`
  *  doesn't reach past the package boundary — a second reader importing the relative path
  *  could drift from this one the day the schema changes. */
-export { SCENARIO_SCHEMA_VERSION, isUnverifying, parseScenario, serializeScenario, scenariosDirectory, scenarioPath, listScenarios, ScenarioListError, readScenario, writeScenario, } from "./scenarios/index.ts";
-export type { Scenario, ScenarioStep, ScenarioAssertion, ScenarioAssertionKind, ScenarioActionKind, ScenarioParseResult, TargetDescriptor, } from "./scenarios/index.ts";
+export { MIN_READABLE_SCHEMA_VERSION, SCENARIO_SCHEMA_VERSION, isSecretRef, isUnverifying, parseScenario, readSecretRef, referencedVariables, resolveSecretText, secretRefFor, serializeScenario, scenariosDirectory, scenarioPath, listScenarios, ScenarioListError, readScenario, writeScenario, projectScenarioToRunPlan, projectRunPlanToScenario, } from "./scenarios/index.ts";
+export type { Scenario, SecretEnvironment, SecretRef, SecretResolution, ScenarioStep, ScenarioAssertion, ScenarioAssertionKind, ScenarioActionKind, ScenarioParseResult, TargetDescriptor, ProjectedStep, ProjectedStepKind, ProjectedBrowserRunPlan, ProjectionRefusal, ScenarioProjection, PlanProjection, RawProjectedStep, ScenarioMeta, } from "./scenarios/index.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;yDAEyD;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1E,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEjG,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxF,YAAY,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,WAAW,EACX,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B;;6FAE6F;AAC7F,YAAY,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,2BAA2B,EAC3B,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,WAAW,EACX,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,EACpB,SAAS,EACT,eAAe,EACf,UAAU,EACV,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEjG;;4DAE4D;AAC5D,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;yDAEyD;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE9E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1E,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEjG,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxF,YAAY,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,WAAW,EACX,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B;;6FAE6F;AAC7F,YAAY,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,2BAA2B,EAC3B,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,WAAW,EACX,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,EACpB,SAAS,EACT,eAAe,EACf,UAAU,EACV,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEjG;;4DAE4D;AAC5D,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,QAAQ,EACR,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -11,5 +11,5 @@ export { PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, negotiateVersion, parseM
 /** The scenario format — storage, schema, refusals. Re-exported here so `descry check`
  *  doesn't reach past the package boundary — a second reader importing the relative path
  *  could drift from this one the day the schema changes. */
-export { SCENARIO_SCHEMA_VERSION, isUnverifying, parseScenario, serializeScenario, scenariosDirectory, scenarioPath, listScenarios, ScenarioListError, readScenario, writeScenario, } from "./scenarios/index.js";
+export { MIN_READABLE_SCHEMA_VERSION, SCENARIO_SCHEMA_VERSION, isSecretRef, isUnverifying, parseScenario, readSecretRef, referencedVariables, resolveSecretText, secretRefFor, serializeScenario, scenariosDirectory, scenarioPath, listScenarios, ScenarioListError, readScenario, writeScenario, projectScenarioToRunPlan, projectRunPlanToScenario, } from "./scenarios/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;yDAEyD;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG1E,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,UAAU,GACX,MAAM,aAAa,CAAC;AAWrB,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAoExF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG3E,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AAGvB;;4DAE4D;AAC5D,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;yDAEyD;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG1E,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,UAAU,GACX,MAAM,aAAa,CAAC;AAWrB,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAoExF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG3E,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AAGvB;;4DAE4D;AAC5D,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/planner/predict-then-propose.d.ts

@@ -0,0 +1,101 @@
+/**
+ * RG-10's second half, joined to its first: predict, then propose — never
+ * predict, then drive. `documents/plans/runtime-gap-closure.md`'s Lane C3.
+ *
+ * The predict half is `reachablePages` (`@descryy/core`): a one-sided
+ * forward walk from any node — typically a `DATABASE_COLUMN` a diff touches
+ * — over `PROPAGATES_TO`/`READS`/`ASSIGNS`/`RETURNS`, crossing `USES_API`
+ * backward at an `API_ENDPOINT`, to whatever `PAGE`/`COMPONENT` the data can
+ * reach. That traversal already existed (Gap 8 step 3) and is untouched
+ * here.
+ *
+ * The propose half reuses lane journey's planner (`./propose-journey.ts`)
+ * exactly as `propose_journey` itself does — same function, same "propose,
+ * never invent" discipline, same navigate-only limitation (the graph has no
+ * selector, so a `PAGE` reached through the walk becomes a navigate step
+ * only when its own qualified name looks like a route path; everything
+ * else is `reachedNotProposed`, not guessed into a click). This module
+ * builds no second planner and no second projection — it is the join, not
+ * a third implementation.
+ *
+ * **This module never drives anything and never writes to a `Finding`.**
+ * Proving or disproving what it predicts is: a human (or an agent acting on
+ * a human's behalf) reviews the proposal, drives the application for real
+ * (`browser_start_session`, the browser primitives, `browser_save_scenario`
+ * to commit what actually happened), and records the outcome against the
+ * finding that predicted it — a step this module does not take, because
+ * `packages/ir/src/finding.ts` and the finding funnel are outside this
+ * lane's owned files. See the `predict_reach` tool's own description for
+ * where that handoff is named to a caller.
+ *
+ * ## `proveOrDisprove` — the join, added by the pipeline-joins lane (RG-10, §5 Lane C3)
+ *
+ * Still never drives anything. It takes evidence a caller *already*
+ * collected by driving an accepted scenario for real — `browser_run_scenario`'s
+ * own `graph: BrowserGraphWrite` (or, in a live pipeline run, the same
+ * `graphNodeId`-correlated evidence `descry-desktop`'s runtime execution
+ * already produces) — and compares it against what {@link predictThenPropose}
+ * predicted. `ObservedReach` is declared structurally, not imported from
+ * `../browser/*`, so this module (and every caller of it, including
+ * `descry-desktop`'s pipeline) takes no dependency on the browser package;
+ * a real `BrowserGraphWrite`'s resolved node ids structurally satisfy it
+ * without a cast.
+ *
+ * **Both directions are real answers, not just the confirming one.** A
+ * predicted page absent from `observed.visitedNodeIds` after the declared
+ * journey ran to completion is a disproof — the propagation this module
+ * predicted did not show up where the graph said it would — and rule 6/7
+ * require that to be as visible as a proof, never silently dropped in favour
+ * of the cases that confirmed the prediction.
+ */
+import { type AdjacencyProvider } from "@descryy/core";
+import { type JourneyCandidateNode, type ProposedJourney } from "./propose-journey.ts";
+export interface PredictThenProposeOptions {
+    readonly targetUrl: string;
+    readonly name: string;
+    readonly savedAtCommit: string;
+}
+export interface PredictedReach {
+    /** Every PAGE/COMPONENT node the walk reached, in the order it found them. */
+    readonly reachedPages: readonly JourneyCandidateNode[];
+    /** Null iff `reachedPages` is empty — nothing to propose a journey toward. */
+    readonly proposal: ProposedJourney | null;
+    readonly notes: readonly string[];
+}
+/**
+ * Walks from `startNodeId` to whatever pages the data can reach, and — when
+ * it reaches at least one — proposes a navigate-only journey to them via
+ * the shared planner. Pure over `provider`: no browser, no write, no I/O.
+ */
+export declare function predictThenPropose(provider: AdjacencyProvider, startNodeId: string, options: PredictThenProposeOptions): PredictedReach;
+/**
+ * What a caller already observed by driving an accepted journey for real —
+ * never produced by this module. Structural: a real `BrowserGraphWrite`
+ * (`browser_run_scenario`'s own reply) or a live run's `graphNodeId`-
+ * correlated evidence both satisfy this without a cast; see this module's
+ * header.
+ */
+export interface ObservedReach {
+    /** Graph node ids the real, already-driven journey's evidence actually correlated to. */
+    readonly visitedNodeIds: readonly string[];
+}
+/** One predicted page, resolved against what really happened. */
+export interface ProvenReach {
+    /** Predicted pages the real drive's own evidence shows were actually reached. */
+    readonly proven: readonly JourneyCandidateNode[];
+    /**
+     * Predicted pages the declared journey ran to completion without ever
+     * reaching. A real disproof — not "not yet checked" (that's simply the
+     * absence of an `ObservedReach` at all) — see this module's header for why
+     * this is recorded with the same weight as `proven`.
+     */
+    readonly disproven: readonly JourneyCandidateNode[];
+}
+/**
+ * The join itself: never drives, only compares. `predicted.reachedPages`
+ * partitions cleanly into `proven`/`disproven` against `observed.visitedNodeIds`
+ * — every predicted page lands in exactly one, so a caller can never read a
+ * prediction as "not checked" once it has a real `ObservedReach` in hand.
+ */
+export declare function proveOrDisprove(predicted: PredictedReach, observed: ObservedReach): ProvenReach;
+//# sourceMappingURL=predict-then-propose.d.ts.map

package/dist/planner/predict-then-propose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predict-then-propose.d.ts","sourceRoot":"","sources":["../../src/planner/predict-then-propose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAkB,KAAK,oBAAoB,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvG,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvD,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,iBAAiB,EAC3B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,yBAAyB,GACjC,cAAc,CAgBhB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,GAAG,WAAW,CAQ/F"}

package/dist/planner/predict-then-propose.js

@@ -0,0 +1,88 @@
+/**
+ * RG-10's second half, joined to its first: predict, then propose — never
+ * predict, then drive. `documents/plans/runtime-gap-closure.md`'s Lane C3.
+ *
+ * The predict half is `reachablePages` (`@descryy/core`): a one-sided
+ * forward walk from any node — typically a `DATABASE_COLUMN` a diff touches
+ * — over `PROPAGATES_TO`/`READS`/`ASSIGNS`/`RETURNS`, crossing `USES_API`
+ * backward at an `API_ENDPOINT`, to whatever `PAGE`/`COMPONENT` the data can
+ * reach. That traversal already existed (Gap 8 step 3) and is untouched
+ * here.
+ *
+ * The propose half reuses lane journey's planner (`./propose-journey.ts`)
+ * exactly as `propose_journey` itself does — same function, same "propose,
+ * never invent" discipline, same navigate-only limitation (the graph has no
+ * selector, so a `PAGE` reached through the walk becomes a navigate step
+ * only when its own qualified name looks like a route path; everything
+ * else is `reachedNotProposed`, not guessed into a click). This module
+ * builds no second planner and no second projection — it is the join, not
+ * a third implementation.
+ *
+ * **This module never drives anything and never writes to a `Finding`.**
+ * Proving or disproving what it predicts is: a human (or an agent acting on
+ * a human's behalf) reviews the proposal, drives the application for real
+ * (`browser_start_session`, the browser primitives, `browser_save_scenario`
+ * to commit what actually happened), and records the outcome against the
+ * finding that predicted it — a step this module does not take, because
+ * `packages/ir/src/finding.ts` and the finding funnel are outside this
+ * lane's owned files. See the `predict_reach` tool's own description for
+ * where that handoff is named to a caller.
+ *
+ * ## `proveOrDisprove` — the join, added by the pipeline-joins lane (RG-10, §5 Lane C3)
+ *
+ * Still never drives anything. It takes evidence a caller *already*
+ * collected by driving an accepted scenario for real — `browser_run_scenario`'s
+ * own `graph: BrowserGraphWrite` (or, in a live pipeline run, the same
+ * `graphNodeId`-correlated evidence `descry-desktop`'s runtime execution
+ * already produces) — and compares it against what {@link predictThenPropose}
+ * predicted. `ObservedReach` is declared structurally, not imported from
+ * `../browser/*`, so this module (and every caller of it, including
+ * `descry-desktop`'s pipeline) takes no dependency on the browser package;
+ * a real `BrowserGraphWrite`'s resolved node ids structurally satisfy it
+ * without a cast.
+ *
+ * **Both directions are real answers, not just the confirming one.** A
+ * predicted page absent from `observed.visitedNodeIds` after the declared
+ * journey ran to completion is a disproof — the propagation this module
+ * predicted did not show up where the graph said it would — and rule 6/7
+ * require that to be as visible as a proof, never silently dropped in favour
+ * of the cases that confirmed the prediction.
+ */
+import { reachablePages } from "@descryy/core";
+import { proposeJourney } from "./propose-journey.js";
+/**
+ * Walks from `startNodeId` to whatever pages the data can reach, and — when
+ * it reaches at least one — proposes a navigate-only journey to them via
+ * the shared planner. Pure over `provider`: no browser, no write, no I/O.
+ */
+export function predictThenPropose(provider, startNodeId, options) {
+    const reach = reachablePages(provider, startNodeId);
+    // `reachablePages` already restricts itself to PAGE/COMPONENT nodes (see
+    // its own doc); no re-filtering needed here.
+    const reachedPages = reach.data.map((r) => ({
+        id: r.node.id,
+        type: r.node.type,
+        name: r.node.name,
+    }));
+    if (reachedPages.length === 0) {
+        return { reachedPages: [], proposal: null, notes: reach.notes };
+    }
+    const proposal = proposeJourney(reachedPages, options);
+    return { reachedPages, proposal, notes: [...reach.notes, ...proposal.notes] };
+}
+/**
+ * The join itself: never drives, only compares. `predicted.reachedPages`
+ * partitions cleanly into `proven`/`disproven` against `observed.visitedNodeIds`
+ * — every predicted page lands in exactly one, so a caller can never read a
+ * prediction as "not checked" once it has a real `ObservedReach` in hand.
+ */
+export function proveOrDisprove(predicted, observed) {
+    const visited = new Set(observed.visitedNodeIds);
+    const proven = [];
+    const disproven = [];
+    for (const page of predicted.reachedPages) {
+        (visited.has(page.id) ? proven : disproven).push(page);
+    }
+    return { proven, disproven };
+}
+//# sourceMappingURL=predict-then-propose.js.map

package/dist/planner/predict-then-propose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predict-then-propose.js","sourceRoot":"","sources":["../../src/planner/predict-then-propose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,cAAc,EAA0B,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAmD,MAAM,sBAAsB,CAAC;AAgBvG;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAA2B,EAC3B,WAAmB,EACnB,OAAkC;IAElC,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACpD,yEAAyE;IACzE,6CAA6C;IAC7C,MAAM,YAAY,GAA2B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE;QACb,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI;QACjB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI;KAClB,CAAC,CAAC,CAAC;IAEJ,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAClE,CAAC;IAED,MAAM,QAAQ,GAAG,cAAc,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACvD,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AAChF,CAAC;AA2BD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAyB,EAAE,QAAuB;IAChF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,SAAS,GAA2B,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC;QAC1C,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC"}

package/dist/planner/propose-journey.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The planner — proposes, never invents. Lane A1, item 5 of
+ * `documents/plans/runtime-gap-closure.md`, closing the rest of RG-1.
+ *
+ * ## What this is and is not
+ *
+ * Takes the `PAGE`/`COMPONENT` nodes a diff-scope traversal already found
+ * (the same `scopeChange` the `scope` tool calls — this module receives its
+ * output, it does not recompute it) and turns them into a **proposed**
+ * `Scenario` — a value returned to the caller, never written to disk. Rule 1
+ * ("never fabricate input") is the whole shape of this module: the code
+ * graph has no DOM. It can name a route a `PAGE` node's own qualified path
+ * spells out; it has no selector, no accessible name, no evidence a button
+ * exists at all. So the proposal is **navigate-only** — one step per
+ * page-shaped route the scope touched — and every `COMPONENT` node (and
+ * every `PAGE` node with no path-shaped name to navigate to) is listed as
+ * *reached but not exercised*, disclosed rather than guessed into a `click`
+ * step this module cannot back with a real selector.
+ *
+ * ## Why this can never execute anything
+ *
+ * The only way a `Scenario` becomes replayable is `writeScenario`
+ * (`scenarios/storage.ts`), and the only caller in this codebase that calls
+ * it is `browser_save_scenario` — which requires a **live, already-driven
+ * browser session** and independently verifies every step actually
+ * resolves before it writes anything (`collectUnresolvedTargets`). This
+ * module never imports `writeScenario` and never touches a browser session.
+ * A proposal from here is data in a tool reply; nothing runs until a human
+ * (or an agent acting on a human's behalf) drives the app for real and
+ * calls `browser_save_scenario` — the acceptance act — which is what
+ * produces the one artifact (`descry/scenarios/*.scenario.json`) that
+ * `browser_run_scenario` can replay. See `propose-journey.test.ts`'s
+ * "nothing executes without an acceptance record" case.
+ */
+import { type Scenario } from "../scenarios/index.ts";
+export interface JourneyCandidateNode {
+    readonly id: string;
+    readonly type: string;
+    readonly name: string;
+}
+export interface ProposedJourney {
+    /** A `Scenario`-shaped proposal. `assertions` is always empty: this module has no evidence to assert against, and inventing one would be a confident false claim about a page it never observed. */
+    readonly scenario: Scenario;
+    /** `PAGE` nodes in scope whose name did not look like a navigable path, and every `COMPONENT` node — real graph hits, listed rather than guessed into a step. */
+    readonly reachedNotProposed: readonly JourneyCandidateNode[];
+    readonly notes: readonly string[];
+}
+/**
+ * Builds a proposed journey from the `PAGE`/`COMPONENT` nodes a diff scope
+ * already found. `nodes` is typically `[...scoped.changed, ...scoped.affected]`
+ * mapped to their graph node — the caller (the MCP tool) owns fetching that;
+ * this function is pure over the result so it is exhaustively testable
+ * without a graph.
+ */
+export declare function proposeJourney(nodes: readonly JourneyCandidateNode[], options: {
+    readonly targetUrl: string;
+    readonly name: string;
+    readonly savedAtCommit: string;
+}): ProposedJourney;
+//# sourceMappingURL=propose-journey.d.ts.map

package/dist/planner/propose-journey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propose-journey.d.ts","sourceRoot":"","sources":["../../src/planner/propose-journey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,oMAAoM;IACpM,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,iKAAiK;IACjK,QAAQ,CAAC,kBAAkB,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAOD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,oBAAoB,EAAE,EACtC,OAAO,EAAE;IACP,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GACA,eAAe,CAwDjB"}

package/dist/planner/propose-journey.js

@@ -0,0 +1,96 @@
+/**
+ * The planner — proposes, never invents. Lane A1, item 5 of
+ * `documents/plans/runtime-gap-closure.md`, closing the rest of RG-1.
+ *
+ * ## What this is and is not
+ *
+ * Takes the `PAGE`/`COMPONENT` nodes a diff-scope traversal already found
+ * (the same `scopeChange` the `scope` tool calls — this module receives its
+ * output, it does not recompute it) and turns them into a **proposed**
+ * `Scenario` — a value returned to the caller, never written to disk. Rule 1
+ * ("never fabricate input") is the whole shape of this module: the code
+ * graph has no DOM. It can name a route a `PAGE` node's own qualified path
+ * spells out; it has no selector, no accessible name, no evidence a button
+ * exists at all. So the proposal is **navigate-only** — one step per
+ * page-shaped route the scope touched — and every `COMPONENT` node (and
+ * every `PAGE` node with no path-shaped name to navigate to) is listed as
+ * *reached but not exercised*, disclosed rather than guessed into a `click`
+ * step this module cannot back with a real selector.
+ *
+ * ## Why this can never execute anything
+ *
+ * The only way a `Scenario` becomes replayable is `writeScenario`
+ * (`scenarios/storage.ts`), and the only caller in this codebase that calls
+ * it is `browser_save_scenario` — which requires a **live, already-driven
+ * browser session** and independently verifies every step actually
+ * resolves before it writes anything (`collectUnresolvedTargets`). This
+ * module never imports `writeScenario` and never touches a browser session.
+ * A proposal from here is data in a tool reply; nothing runs until a human
+ * (or an agent acting on a human's behalf) drives the app for real and
+ * calls `browser_save_scenario` — the acceptance act — which is what
+ * produces the one artifact (`descry/scenarios/*.scenario.json`) that
+ * `browser_run_scenario` can replay. See `propose-journey.test.ts`'s
+ * "nothing executes without an acceptance record" case.
+ */
+import { SCENARIO_SCHEMA_VERSION } from "../scenarios/index.js";
+/** A qualified symbol name that looks like a route path: starts with `/`, single line, no whitespace. Deliberately conservative — false negatives (a real route this misses) fall through to `reachedNotProposed`, which is the safe direction (rule 2: when in doubt, omit). */
+function looksLikeRoutePath(name) {
+    return name.startsWith("/") && !/\s/.test(name) && !name.includes("\n");
+}
+/**
+ * Builds a proposed journey from the `PAGE`/`COMPONENT` nodes a diff scope
+ * already found. `nodes` is typically `[...scoped.changed, ...scoped.affected]`
+ * mapped to their graph node — the caller (the MCP tool) owns fetching that;
+ * this function is pure over the result so it is exhaustively testable
+ * without a graph.
+ */
+export function proposeJourney(nodes, options) {
+    const pages = nodes.filter((n) => n.type === "PAGE");
+    const components = nodes.filter((n) => n.type === "COMPONENT");
+    const routable = [];
+    const unroutable = [];
+    for (const page of pages)
+        (looksLikeRoutePath(page.name) ? routable : unroutable).push(page);
+    const base = options.targetUrl.endsWith("/") ? options.targetUrl.slice(0, -1) : options.targetUrl;
+    // Deduplicated and ordered — two PAGE nodes for the same route (a layout
+    // and a leaf, say) must not become two identical navigate steps.
+    const seenPaths = new Set();
+    const steps = [];
+    for (const page of routable) {
+        if (seenPaths.has(page.name))
+            continue;
+        seenPaths.add(page.name);
+        steps.push({ action: "navigate", url: `${base}${page.name}`, target: null, text: null });
+    }
+    const notes = [];
+    if (steps.length === 0) {
+        notes.push("No node in scope named a path-shaped route, so this proposal has no steps to offer. This is not a " +
+            "claim that nothing changed — it is a claim that nothing in scope looked like a navigable page from " +
+            "the graph alone. A human exploring the application directly (browser_start_session, then " +
+            "browser_save_scenario) is how a real journey gets declared from here.");
+    }
+    notes.push("Every step here is navigate-only: the code graph has no selector, no accessible name and no evidence " +
+        "an element exists, so this proposal never invents a click, a type or a submit. A human who accepts " +
+        "this proposal drives the rest of the journey for real and saves it with browser_save_scenario — that " +
+        "save is what turns a proposal into something replayable, and this module never calls it itself.");
+    if (unroutable.length + components.length > 0) {
+        notes.push(`${unroutable.length + components.length} node(s) in scope (${unroutable.length} page(s) with no ` +
+            `path-shaped name, ${components.length} component(s)) are reached but not proposed as a step — listed ` +
+            "in reachedNotProposed rather than guessed into one.");
+    }
+    return {
+        scenario: {
+            schemaVersion: SCENARIO_SCHEMA_VERSION,
+            name: options.name,
+            description: "Proposed by the planner from a diff scope's PAGE nodes — not accepted, not saved, not runnable until a human reviews it.",
+            targetUrl: steps[0]?.url ?? options.targetUrl,
+            savedAt: new Date().toISOString(),
+            savedAtCommit: options.savedAtCommit,
+            steps,
+            assertions: [],
+        },
+        reachedNotProposed: [...unroutable, ...components],
+        notes,
+    };
+}
+//# sourceMappingURL=propose-journey.js.map

package/dist/planner/propose-journey.js.map

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

package/dist/registry.d.ts

@@ -3,7 +3,7 @@
  *  in config and loaded at runtime via a `create*Adapter` convention (an ambiguous match
  *  errors, never guesses). A failed load is disclosed as `SourceLoadFailure`, never silently
  *  skipped (§20.2). Specifiers resolve from the repo root first (npx isolates adapters there), then this package's own closure. */
-import type { IRSource, LanguageAdapter, RepoRoot } from "@descryy/ir";
+import type { IRSource, LanguageAdapter, RepoRoot, StructuredSkipEntry } from "@descryy/ir";
 /** One entry in the configured source list. A bare string is `{ module }`. */
 export interface SourceSpec {
     readonly module: string;
@@ -81,6 +81,14 @@ export declare function loadSources(entries: readonly (string | SourceSpec)[], r
  * routinely disable to get their work done is not a security control."
  */
 export declare function withSafeAlternative(reason: string, specifier: string, repoPath: string | undefined): Promise<string>;
+/** One adapter's `detect()`-time evidence, kept alongside `applicable`/`skipped` rather than
+ *  folded into either — `DetectionResult.evidence` is populated on a match as much as on a
+ *  skip (a matched adapter can still report "skipped 3: a separate checkout with its own
+ *  .git"), so it is collected independently of which bucket the source landed in. */
+export interface DetectionEvidence {
+    readonly source: string;
+    readonly entries: readonly (string | StructuredSkipEntry)[];
+}
 /** Asks each loaded adapter whether it claims this repository. A non-`LanguageAdapter`
  *  source (the git reader) always runs. A throwing `detect` counts as "did not detect",
  *  with the reason recorded — it can't fail the whole run, and can't hide either. */
@@ -90,5 +98,6 @@ export declare function detectSources(sources: readonly LoadedSource[], root: Re
         source: LoadedSource;
         reason: string;
     }[];
+    readonly evidence: readonly DetectionEvidence[];
 }>;
 //# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;mIAImI;AAOnI,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvE,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;yEAEqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC/C;AAID,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAEpE;AAoBD;sGACsG;AACtG,wBAAsB,WAAW,CAC/B,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,EACzC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAmBzB;AAuCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAAC,MAAM,CAAC,CAejB;AAyLD;;qFAEqF;AACrF,wBAAsB,aAAa,CACjC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC;IACT,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACvE,CAAC,CAuBD"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;mIAImI;AAOnI,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAI5F,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;yEAEqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC/C;AAID,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAEpE;AAoBD;sGACsG;AACtG,wBAAsB,WAAW,CAC/B,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,EACzC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAmBzB;AAuCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAAC,MAAM,CAAC,CAejB;AAyLD;;;qFAGqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,mBAAmB,CAAC,EAAE,CAAC;CAC7D;AAED;;qFAEqF;AACrF,wBAAsB,aAAa,CACjC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC;IACT,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtE,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD,CAAC,CA2BD"}

package/dist/registry.js

@@ -291,6 +291,7 @@ async function importSource(specifier, repoPath) {
 export async function detectSources(sources, root) {
     const applicable = [];
     const skipped = [];
+    const evidence = [];
     for (const entry of sources) {
         if (entry.adapter === null) {
             applicable.push(entry);
@@ -298,6 +299,9 @@ export async function detectSources(sources, root) {
         }
         try {
             const detection = await entry.adapter.detect(root);
+            if (detection.evidence.length > 0) {
+                evidence.push({ source: entry.source.id, entries: detection.evidence });
+            }
             if (detection.detected)
                 applicable.push(entry);
             else
@@ -310,6 +314,6 @@ export async function detectSources(sources, root) {
             skipped.push({ source: entry, reason: `detection failed — ${describe(error)}` });
         }
     }
-    return { applicable, skipped };
+    return { applicable, skipped, evidence };
 }
 //# sourceMappingURL=registry.js.map