specfuse-loop 0.32.0__tar.gz → 0.33.0__tar.gz

{specfuse_loop-0.32.0/specfuse_loop.egg-info → specfuse_loop-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.32.0
+Version: 0.33.0
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.32.0"
+version = "0.33.0"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"

specfuse_loop-0.33.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.33.0

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/loop/data/docs/concepts/monitoring-runners.md

@@ -86,11 +86,14 @@ operator) it starts 24 hours back instead, and the run summary says so.
 The window applies to the checks that read event history: `error-logs` and
 `http-5xx` filter on `ingestion_time()`, so a row stamped just before the
 previous run but ingested after it is read by the next run rather than lost
-between the two. Three check types are deliberately not bounded by it:
+between the two. These check types are deliberately not bounded by it:
 
 - `heartbeat` needs the most recent heartbeat however old it is;
+- `backlog-stalled` reads each backlog's latest snapshot within a fixed
+  7-day lookback, since a stall is a state, not an event;
 - `http-status-regression` compares the windows around each deployment and
   carries its own fixed lookback;
+- `dependency-regression` does the same for the component's dependency calls;
 - `invariant` runs the operator's query as written. A query that reads event
   history should bound itself (for example `| where TimeGenerated > ago(1h)`);
   otherwise every matching row in retention is a finding, deduplicated only by
@@ -184,6 +187,7 @@ the issue was last updated (UTC), what was seen in this run (count, first, last,
 | `dlq` | Message (id, sequence number, subject, enqueued time, delivery count), Dead-letter reason, or the Exception message and top stack frames when the reason is blank, Body shape (the top-level keys, never the values), Peek it |
 | `heartbeat` | Schedule (cron, dialect, timezone, expected firing), Last run (the function's last execution and result), Host last seen, a Host silent line when the component sent no request telemetry across the expected firing, and Earliest heartbeat (the component's first heartbeat, which the grace rule measures from) |
 | `queue-stalled` | Queue (oldest active message age, depth, `stall_after`), Where |
+| `backlog-stalled` | Thresholds (`stall_after`, `silent_after`), Latest snapshot (time, oldest pending age, pending count), Investigate |
 
 A section with nothing to say is left out rather than printed empty. A
 `queue-stalled` finding cannot show when the subscription last completed a

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/loop/data/docs/concepts/monitoring-schema.md

@@ -85,16 +85,18 @@ confidence in the checks grows.
 
 ## Check types
 
-Every check has a required `type`, one of seven neutral values. This set is
+Every check has a required `type`, one of the neutral values in the table below. This set is
 provider-agnostic by construction: a check type names a concept
 (a dead-letter queue, a heartbeat), never a vendor.
 
 | Type | Extra required fields | Meaning |
 |---|---|---|
+| `backlog-stalled` | `targets` | Alerts when a work queue the component keeps in its **own data store** (a transactional outbox, a job table drained by a poller) stops draining. Its rows never reach a broker, so `dlq` and `queue-stalled` cannot see it, and `heartbeat` only proves the poller fired. The component reports each backlog itself as a `BacklogSnapshot` event (the emission contract is in `.specfuse/rules/design-for-diagnosis.md`); the monitor never reads the data store. One finding per (component, backlog `name`) while the latest snapshot's oldest pending item is older than `stall_after`, failure class `stalled-backlog`; with `silent_after` set, a separate `silent-backlog` finding when no snapshot for that backlog arrived within it (the reporter died). The backlog name is the signature, so a stall that lasts many runs stays one issue. `pendingCount` appears in the finding but is never compared against a threshold: this is not volume alerting. A component that has emitted no snapshot at all in the last 7 days yields nothing, since a never-deployed reporter and a dead one look the same. |
 | `dlq` | `harvest_mode` (`peek` or `quarantine`), `targets` | Alerts on messages landing in this component's dead-letter queue. `peek` reads without removing; `quarantine` removes after reading. `targets` is **required**: a dead-lettered message is attributed to a subscription, and a target-less `dlq` check on a multi-subscription host cannot say which one. |
 | `error-logs` | none | Scans structured application logs for error-level entries. |
 | `http-5xx` | none | Alerts when the rolling 5xx rate crosses a threshold. For HTTP-serving components. |
 | `http-status-regression` | `deploy_signal`, `window_after_deploy` | Alerts when a deployment raises the rate of server-fault 4xx responses compared with the window before it. For HTTP-serving components that stamp a version on every deployment. `deploy_signal` is a mapping with a required `kind`; the only accepted `kind` is `app-version`. `window_after_deploy` is a duration (`<integer><unit>`, e.g. `30m`). `codes` is optional: a non-empty list of unique integers in 400–499, defaulting to `[403, 405, 415]`. Other codes are opt-in: `401` because a 401 wave is as often expired client tokens as a broken deployment, and `410`, `412`, `428` because few services return them. A code fires when its **share of the component's requests** in the window after the deployment is at least 3× its share in the equal window before, and it occurs at least 10 times after; both thresholds are fixed constants, not fields, and comparing shares keeps a traffic ramp from reading as a regression. Each finding states both shares and counts, the deployment's first-seen time, the code's top five operations by after-window count, up to three sample operation ids, and a Log Analytics query covering both windows. |
+| `dependency-regression` | `deploy_signal`, `window_after_deploy` | Alerts when a deployment makes the component's calls to one of its dependencies — its own database first — start failing. For components that stamp a version on every deployment and call a data store or another dependency the telemetry records. `deploy_signal` and `window_after_deploy` are the same block `http-status-regression` takes, validated by the same rules. `dependency_types` is optional: a non-empty list of unique dependency type names as the telemetry records them (e.g. `[SQL]`, matched case-insensitively), defaulting to every type the component records. `min_failures` is optional: an integer of at least 1, defaulting to `5`, so one transient failure is not a regression. A (dependency type, target) pair fires when, in the window after the deployment, it has at least `min_failures` failed calls **and** its failure rate (failed calls ÷ all calls to that pair) is at least 3× its rate in the equal window before — the same fixed factor as `http-status-regression`. A pair with no calls or no failures before the deployment has a before-rate of 0, so a new query that fails, or a target that never failed before, fires on the floor alone; comparing rates keeps a traffic ramp from reading as a regression. One finding per (deployment, type, target); its signature is the version, type, target and the top failing result code. Each finding states both rates and counts, the deployment's first-seen time, the failing result codes, up to three sample operation ids, and a Log Analytics query covering both windows. **Failures only, by decision (#3577):** a failed call is discrete, while latency is a distribution comparison closer to metrics; a latency regression surfaces here once it becomes a timeout, which is a failed call. An opt-in `latency_ratio` remains a possible later decision, to be made explicitly rather than by precedent. |
 | `heartbeat` | none | Alerts when the component stops reporting in at all. |
 | `invariant` | `query`, `fingerprint_by` | Runs an operator-supplied query (opaque to this schema — not parsed or executed here) and alerts on unexpected rows. `fingerprint_by` names the field used to dedupe repeat findings into one issue. |
 | `queue-stalled` | `targets` | Alerts when a consumer stops consuming from a subscription — no message failed (so `dlq` sees nothing), the host is still alive (so `heartbeat` sees nothing), and the symptom is a broker coordinate (queue depth / age of oldest message), not a telemetry query, so `invariant` cannot express it either. `targets` is required from birth: a wedged consumer on a multi-subscription host raises the identical "which one" question `dlq`/`heartbeat` targets already answer. |
@@ -108,6 +110,43 @@ schema (`AppRequests`, `AppExceptions`, `AppEvents`, with `AppRoleName`,
 (`requests`, `exceptions`, `customEvents`, `cloud_RoleName`, `timestamp`,
 `customDimensions`), which a workspace does not resolve.
 
+## Scope: a component's data store is monitored through the component, never directly
+
+The monitor watches component misbehaviour, not metrics or infrastructure.
+A component's data store sits on that boundary; this is where the line falls
+(#3578, also stated in `.specfuse/rules/design-for-diagnosis.md`).
+
+**The monitor never connects to a component's data store.** There is no SQL,
+document-store or cache provider, and none will be added: the harvester holds
+telemetry and broker read access only. A data-store connection would mean
+holding credentials to production (often personal) data, coupling a check to a
+schema that a migration can silently break, and adding one provider per engine.
+
+**Data-store signals the component owns are in scope, and the component emits
+them as telemetry:**
+
+| Signal | Read by |
+|---|---|
+| Backlogs in data-store tables (rows waiting past their expected processing time) | the planned `backlog-stalled` check type (#3576) |
+| Dependency failures that start after a deployment, including data-store calls | the planned `dependency-regression` check type (#3577) |
+| Business-state invariants over persisted data: orphaned rows, records stuck in a state past their deadline, migration drift (the release expects migration N, the store reports M) | the existing `invariant` check |
+
+The component computes each invariant itself and emits the result; `invariant`
+queries that telemetry, never the store. This is `invariant`'s sanctioned
+business-state use, not the rate-shaped use FEAT-2026-0069 ruled out.
+
+**Data-store platform health is out of scope:** CPU and throughput-unit
+consumption, storage, connections, deadlock rate, replication lag, failover. The
+fix for these lives in infrastructure, not the component's repository, so a
+finding has nowhere to route and autofix cannot act on it. They belong to the
+platform's own infrastructure alerting, owned by whoever owns the
+infrastructure.
+
+**The test for any future request:** would the fix be a pull request on the
+component? If yes, it is in scope and the component emits the signal. If the
+fix is a capacity or infrastructure change, it is out of scope. `monitor-lint`
+needs no rule for this: a data-store provider does not exist to be configured.
+
 ## Check targets
 
 `component` and check `targets` are two different axes, and the schema keeps
@@ -146,11 +185,13 @@ triggers as `targets[]` is what keeps that property satisfiable.
 |---|---|---|---|
 | `dlq` | **required** | `subscription` (required), `function` (required) | `subscription` is what the harvester queries; `function` is what a human diagnoses by — a subscription name alone rarely tells an on-call engineer which handler failed. |
 | `queue-stalled` | **required** | `subscription` (required), `function` (required), `stall_after` (optional, `<integer><unit>` with unit `s`/`m`/`h`/`d`, e.g. `15m`) | Same `subscription`/`function` coordinates as `dlq` — same subscription, same on-call-facing handler name. `stall_after` (how long is too long since the last message) must match `<integer><unit>` with unit `s`, `m`, `h` or `d` (e.g. `15m`, `90s`, `2h`, `1d`); the linter rejects any other value — the harvester would refuse it on its first poll. A target with no `stall_after` is skipped and recorded at runtime. Only the grammar is checked, not a range. |
+| `backlog-stalled` | **required** | `name` (required), `stall_after` (required), `silent_after` (optional) | `name` is the `backlogName` the component emits. Both durations use the `<integer><unit>` grammar (unit `s`/`m`/`h`/`d`, e.g. `15m`); the linter rejects any other value. Only the grammar is checked, not a range. |
 | `heartbeat` | optional | `name` (required), `cron` (optional), `dialect` (required when `cron` present), `timezone` (optional) | One target per schedule, so a single silent timer among several stays individually visible. A single-schedule component may omit the list. |
 | `invariant` | **forbidden** | — | `fingerprint_by` is already this check type's enumeration key; permitting `targets` too would give it two competing enumeration keys. |
 | `error-logs` | **forbidden** | — | Role-name keyed and genuinely component-scoped; the validator rejects `targets` here. |
 | `http-5xx` | **forbidden** | — | Same reason as `error-logs`. |
 | `http-status-regression` | **forbidden** | — | Per-component, like `http-5xx`: the deployment it compares across is a component-wide event. |
+| `dependency-regression` | **forbidden** | — | Same reason as `http-status-regression`; the (dependency type, target) pair a finding names comes from the telemetry, not from configuration. |
 
 Where `targets` is present it must be a non-empty list of mappings, and every
 entry must carry that check type's required coordinates. An empty list is a

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/loop/data/docs/concepts/monitoring-to-fix.md

@@ -38,7 +38,8 @@ the shipped GitHub Actions template — see
 itself.
 
 **What it reads.** `.specfuse/monitoring.yml`: each component's checks
-(`error-logs`, `http-5xx`, `http-status-regression`, `dlq`, `queue-stalled`,
+(`error-logs`, `http-5xx`, `http-status-regression`, `dependency-regression`, `dlq`, `queue-stalled`,
+`backlog-stalled`,
 `heartbeat`, `invariant`), each environment's telemetry and broker bindings.
 Event-history checks read only what arrived since the previous run (the
 watermark in `.specfuse/monitor-watermarks/<env>.json`, or the last 24 hours on

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/loop/data/docs/flows.html

@@ -289,7 +289,7 @@ const FLOWS = [
     entry: "a failure in a deployed component", who: "specfuse monitor run, then specfuse-agent or you", ceremony: "one issue per fingerprint",
     summary: "Work that starts in production. The monitor files one issue per distinct failure; two per-component dials in monitoring.yml decide how far it goes without you. Findings skip triage and the bug lane on purpose: their route to a fix is diagnose, then autofix.",
     stages: [
-      { k: "auto", t: "Detect", c: "specfuse monitor run", d: "Runs each component's checks against its telemetry and broker: error-logs, http-5xx, http-status-regression, dlq, queue-stalled, heartbeat, invariant. Reads only what arrived since the last run (the watermark), or the last 24 hours on a first run. One failing check is reported and the rest still run.", rows: { Reads: ".specfuse/monitoring.yml, App Insights, Service Bus", Scheduled: "by you: cron, CI, or later the in-cluster runner" } },
+      { k: "auto", t: "Detect", c: "specfuse monitor run", d: "Runs each component's checks against its telemetry and broker: error-logs, http-5xx, http-status-regression, dependency-regression, dlq, queue-stalled, backlog-stalled, heartbeat, invariant. Reads only what arrived since the last run (the watermark), or the last 24 hours on a first run. One failing check is reported and the rest still run.", rows: { Reads: ".specfuse/monitoring.yml, App Insights, Service Bus", Scheduled: "by you: cron, CI, or later the in-cluster runner" } },
       { k: "auto", t: "File", c: "one issue per fingerprint", d: "The fingerprint is component + check + normalised failure. New fingerprint: a new monitoring-finding issue. Same fingerprint, open issue: the occurrence count goes up (at most every 6 hours). The monitor reopens a closed finding but never closes one; a finding unseen for 7 days gets a one-time close-candidate comment. A schedule is not called silent before its component's first heartbeat.", rows: { "Closed issue": "reopened with a comment when it closed within 90 days", "dlq issue": "closing it acknowledges the message; only a new message id reopens it" } },
       { k: "human", t: "Diagnose", c: "diagnose: manual | auto", d: "manual: you run /diagnose-issue N. auto: specfuse-agent diagnoses each open, undiagnosed finding in a headless session. Either way one comment is posted: root cause, evidence, candidate fix, confidence (0 to 1), fix_scope (small, large, external) and severity (critical, high, medium, low, judged from the evidence); the finding gets one severity label. One diagnosis per issue, except a fresh one after the monitor reopens it following a fix, or when someone adds the rediagnose label.", stops: ["diagnose: manual — every finding waits for you", "diagnose: auto only acts when specfuse-agent is scheduled too"] },
       { k: "auto", t: "Decide", c: "autofix: \"off\" | \"on\"", d: "Fixed rules, not configuration: autofix off → decline. fix_scope large or external → route to you. confidence below 0.8 → route to you. Already attempted for this fingerprint → decline. Daily cap reached → decline. Otherwise → fire. Severity changes none of these rules: it only orders the queue, most severe first.", stops: ["Routed to a human: an escalation comment says which rule fired"] },

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/loop/data/monitoring.yml.example

@@ -90,6 +90,19 @@ components:
         # codes defaults to [403, 405, 415]; this one also opts in to 401.
         codes: [401, 403, 405, 415]
 
+      # dependency-regression: alerts when a deployment makes calls to one of
+      # the component's dependencies (its database first) start failing — a
+      # migration that did not run, a renamed column, a broken connection
+      # string. Same deploy_signal block as http-status-regression. Failures
+      # only: a slow query is seen once it times out. A (type, target) pair
+      # fires at min_failures failed calls and 3x its pre-deploy failure rate.
+      - type: dependency-regression
+        deploy_signal:
+          kind: app-version
+        window_after_deploy: 1h
+        dependency_types: [SQL]   # default: every type the component records
+        min_failures: 5           # default 5
+
       # heartbeat: alerts when the component stops reporting in at all —
       # the check that catches "it didn't error, it just went silent."
       - type: heartbeat
@@ -123,6 +136,20 @@ components:
         query: "select count(*) from orders where fulfilled_at is null and created_at < now() - interval '1 day'"
         fingerprint_by: order_id
 
+      # backlog-stalled: catches a work queue this component keeps in its OWN
+      # data store (a transactional outbox, a job table) that has stopped
+      # draining. The rows never reach the broker, so `dlq`/`queue-stalled`
+      # see nothing. The component reports each backlog itself as a
+      # `BacklogSnapshot` event (see .specfuse/rules/design-for-diagnosis.md);
+      # `name` is that event's `backlogName`. `stall_after`: the oldest pending
+      # item older than this is a finding. `silent_after` (optional): no
+      # snapshot at all for this long is a finding — the reporter died.
+      - type: backlog-stalled
+        targets:
+          - name: acme-event-outbox
+            stall_after: 15m
+            silent_after: 30m
+
       - type: heartbeat
 
   # acme-functions-host: the motivating shape this feature exists for. One

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/loop/data/rules/design-for-diagnosis.md

@@ -7,7 +7,7 @@ Licensed under the Apache License, Version 2.0. See LICENSE.
 
 This rule governs the *target application's* code — not this loop's own
 execution. It states what a deployed component must do so the check types a
-`monitoring.yml` admits (`dlq`, `error-logs`, `http-5xx`,
+`monitoring.yml` admits (`backlog-stalled`, `dependency-regression`, `dlq`, `error-logs`, `http-5xx`,
 `http-status-regression`, `heartbeat`, `invariant`, `queue-stalled`) produce a diagnosable finding instead of a bare alert. A check that
 fires without one of these properties tells an operator only that something is
 wrong, not what or where.
@@ -20,6 +20,43 @@ implementations. How a project achieves a property (which library, which
 platform's native tracing, which log shipper) belongs in that project's
 `.specfuse/rules-local/`, never here.
 
+## A component's data store is monitored through the component, never directly
+
+The monitor watches component misbehaviour, not metrics or infrastructure.
+A component's data store sits on that boundary, so the line is drawn here once
+rather than differently in each project.
+
+**The monitor never connects to a component's data store.** There is no
+data-store provider for any engine; the harvester holds telemetry and broker
+read access only. Three reasons: credentials (a data store holds production
+data, often personal data), schema coupling (a migration silently breaks a check
+that reads tables directly), and provider sprawl (one adapter per engine).
+
+**Data-store signals the component owns are in scope, and the component emits
+them** as telemetry, the same way it emits everything else this rule covers:
+
+- backlogs in data-store tables — rows waiting past their expected processing
+  time — for the planned `backlog-stalled` check type (#3576);
+- dependency failures that start after a deployment, including calls to the
+  data store, for the planned `dependency-regression` check type (#3577);
+- business-state invariants over persisted data — orphaned rows, records stuck
+  in a state past their deadline, or migration drift (the running release
+  expects migration N while the store reports M). The component computes these
+  itself and emits the result; the existing `invariant` check reads that
+  telemetry. This is `invariant`'s sanctioned business-state use; a
+  rate-shaped signal is not an invariant and belongs to its own check type.
+
+**Data-store platform health is out of scope:** CPU and throughput-unit
+consumption, storage, connections, deadlock rate, replication lag, failover.
+The fix for these lives in infrastructure, not in the component's repository,
+so a finding has nowhere to route and an automated fix cannot act on it. They
+belong to the platform's own infrastructure alerting, owned by whoever owns the
+infrastructure.
+
+**The test for any future request:** would the fix be a pull request on the
+component? If yes, the signal is in scope and the component emits it. If the fix
+is a capacity or infrastructure change, it is out of scope.
+
 ## Correlation IDs propagate across component boundaries
 
 A single request or message carries one correlation ID from the moment it enters
@@ -94,6 +131,37 @@ indistinguishable from one whose schedule has stopped — the check reports ever
 target as silent from its first run, and the real silence, when it comes, is
 lost in that noise.
 
+## Data-store work queues report a backlog snapshot
+
+A component that keeps a work queue in its own data store — a transactional
+outbox table, a job table, a pending-work table drained by a poller loop —
+periodically reports the state of each such backlog, in exactly this shape: one
+custom event named `BacklogSnapshot` per backlog it owns, emitted under the
+component's role name, carrying:
+
+- `backlogName` — a stable identifier for the backlog (for example
+  `event-outbox`), the same string as the `name` of the matching
+  `backlog-stalled` target in `monitoring.yml`;
+- `oldestPendingAgeSeconds` — the age in seconds of the oldest unprocessed
+  item, `0` when the backlog is empty;
+- `pendingCount` — optional, the number of unprocessed items.
+
+Emit on a fixed interval from the component's own process, independently of
+whether the drainer succeeds, so the snapshot keeps arriving while the drainer
+is wedged.
+
+A broker-level check cannot see this queue: rows still in an outbox never reach
+the broker, so the broker looks quiet and healthy, and a schedule that fires on
+time proves nothing about whether the rows it should drain are moving. A
+`backlog-stalled` check reads the latest snapshot per backlog and reports when
+its oldest pending item is older than the target's `stall_after`, and, when the
+target sets `silent_after`, when no snapshot for that backlog arrived within it
+— the reporter itself has stopped. `pendingCount` only enriches the finding; it
+is never compared against a threshold, because this is a "work is waiting and
+not moving" signal, not volume alerting. The component reports its own backlog
+so the monitor never needs credentials to, or knowledge of the schema of, the
+data store itself.
+
 ## DLQ entries carry failure context, not just the payload
 
 A message that lands in a dead-letter queue carries, alongside its original
@@ -122,3 +190,15 @@ that stamps no version has no deployment signal at all; one that stamps the same
 value every release shows no new version to detect, so the check never opens its
 post-deployment window and a regression ships unseen. Either way the check
 cannot be evaluated, and discovery reports the gap rather than proposing it.
+
+A `dependency-regression` check reads the same version stamp from the
+component's outbound dependency calls — its database first — so the property
+applies to any component that calls a data store, HTTP-serving or not. Each
+call must be recorded with its dependency type, its target and a success flag
+(and the result code where the client has one); a component that catches a
+failed query and degrades still records that call as failed, which is exactly
+what the check looks for. The check is failures only, by decision (#3577): a
+failed call is discrete, while latency is a distribution comparison closer to
+metrics. A query that slows down after a deployment surfaces once it times out,
+because a timeout is a failed call. An opt-in latency ratio stays a possible
+later decision, to be made explicitly rather than by precedent.

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/loop/lint_monitoring.py

@@ -46,6 +46,8 @@ DIAGNOSE_VALUES = frozenset({"manual", "auto"})
 AUTOFIX_VALUES = frozenset({"off", "on"})
 CHECK_TYPES = frozenset(
     {
+        "backlog-stalled",
+        "dependency-regression",
         "dlq",
         "error-logs",
         "http-5xx",
@@ -262,6 +264,15 @@ def _check_checks(checks: object, component_label: str) -> list[str]:
                 )
         elif check_type == "http-status-regression":
             findings.extend(_check_http_status_regression(check, component_label, index))
+        elif check_type == "backlog-stalled":
+            if check.get("targets") is None:
+                findings.append(
+                    f"component '{component_label}': checks[{index}]: "
+                    f"'backlog-stalled' check requires 'targets' — each target "
+                    f"needs 'name' and 'stall_after'"
+                )
+        elif check_type == "dependency-regression":
+            findings.extend(_check_dependency_regression(check, component_label, index))
         elif check_type == "invariant":
             for field in ("query", "fingerprint_by"):
                 if not check.get(field):
@@ -282,6 +293,7 @@ def _check_checks(checks: object, component_label: str) -> list[str]:
 # they are role-name keyed and therefore genuinely component-scoped; see
 # `_TARGETLESS_CHECK_TYPES` below.
 _TARGET_REQUIRED_FIELDS = {
+    "backlog-stalled": ("name", "stall_after"),
     "dlq": ("subscription", "function"),
     "heartbeat": ("name",),
     "queue-stalled": ("subscription", "function"),
@@ -289,13 +301,10 @@ _TARGET_REQUIRED_FIELDS = {
 DEPLOY_SIGNAL_KINDS = frozenset({"app-version"})
 
 
-def _check_http_status_regression(
-    check: dict, component_label: str, check_index: int
-) -> list[str]:
-    """Field rules for one `http-status-regression` check (`targets` is
-    rejected by `_check_targets`)."""
-    where = f"component '{component_label}': checks[{check_index}]"
-    prefix = f"{where}: 'http-status-regression' check"
+def _check_deploy_window(check: dict, prefix: str) -> list[str]:
+    """The deploy-correlated block every deployment-windowed check type shares
+    (`http-status-regression`, `dependency-regression`): a `deploy_signal`
+    mapping with a known `kind`, and a `window_after_deploy` duration."""
     findings: list[str] = []
 
     signal = check.get("deploy_signal")
@@ -320,6 +329,17 @@ def _check_http_status_regression(
                 f"{prefix} 'window_after_deploy' value {window!r} is not a "
                 f"valid duration — expected {DURATION_GRAMMAR}"
             )
+    return findings
+
+
+def _check_http_status_regression(
+    check: dict, component_label: str, check_index: int
+) -> list[str]:
+    """Field rules for one `http-status-regression` check (`targets` is
+    rejected by `_check_targets`)."""
+    where = f"component '{component_label}': checks[{check_index}]"
+    prefix = f"{where}: 'http-status-regression' check"
+    findings = _check_deploy_window(check, prefix)
 
     codes = check.get("codes")
     if codes is not None:
@@ -339,9 +359,47 @@ def _check_http_status_regression(
     return findings
 
 
+def _check_dependency_regression(
+    check: dict, component_label: str, check_index: int
+) -> list[str]:
+    """Field rules for one `dependency-regression` check (#3577): the shared
+    deploy block, an optional `dependency_types` list (default: every type
+    the component records) and an optional `min_failures` floor (default 5).
+    `targets` is rejected by `_check_targets`."""
+    where = f"component '{component_label}': checks[{check_index}]"
+    prefix = f"{where}: 'dependency-regression' check"
+    findings = _check_deploy_window(check, prefix)
+
+    types = check.get("dependency_types")
+    if types is not None:
+        if (
+            not isinstance(types, list)
+            or not types
+            or not all(isinstance(t, str) and t.strip() for t in types)
+        ):
+            findings.append(
+                f"{prefix} 'dependency_types' must be a non-empty list of "
+                f"dependency type names (e.g. [SQL]) — omit it for every type"
+            )
+        elif len({t.lower() for t in types}) != len(types):
+            findings.append(f"{prefix} 'dependency_types' must not contain duplicates")
+
+    min_failures = check.get("min_failures")
+    if min_failures is not None and (
+        not isinstance(min_failures, int)
+        or isinstance(min_failures, bool)
+        or min_failures < 1
+    ):
+        findings.append(
+            f"{prefix} 'min_failures' must be an integer of at least 1, "
+            f"got {min_failures!r}"
+        )
+    return findings
+
+
 # Check types that must never carry `targets` at all.
 _TARGETLESS_CHECK_TYPES = frozenset(
-    {"error-logs", "http-5xx", "http-status-regression", "invariant"}
+    {"dependency-regression", "error-logs", "http-5xx", "http-status-regression", "invariant"}
 )
 
 
@@ -360,7 +418,8 @@ def _check_targets(
     check type is required to interpret. `cron`'s field *values* stay
     opaque; only the field *count* is checked. `timezone` and
     `invariant.query` are untouched by this and remain fully opaque.
-    `targets` itself is required for `dlq` and `queue-stalled` (enforced in
+    `targets` itself is required for `dlq`, `queue-stalled` and
+    `backlog-stalled` (enforced in
     `_check_checks`, since a missing key and an empty/malformed one are
     different findings). `error-logs`, `http-5xx`, and `invariant` must not
     carry `targets` at all; every other check type treats `targets` as
@@ -405,6 +464,28 @@ def _check_targets(
                     f"'stall_after' value {target['stall_after']!r} is not a "
                     f"valid duration — expected {DURATION_GRAMMAR}"
                 )
+        if check_type == "backlog-stalled":
+            findings.extend(_check_backlog_durations(target, where, t_index))
+    return findings
+
+
+def _check_backlog_durations(target: dict, where: str, t_index: int) -> list[str]:
+    """`stall_after` and the optional `silent_after` of one `backlog-stalled`
+    target must parse with the shared duration grammar (#3576). A missing
+    `stall_after` is already reported by the required-fields pass."""
+    findings: list[str] = []
+    for field in ("stall_after", "silent_after"):
+        value = target.get(field)
+        if value is None or (field == "stall_after" and not value):
+            continue
+        try:
+            parse_duration_seconds(str(value), field)
+        except ValueError:
+            findings.append(
+                f"{where}: targets[{t_index}]: 'backlog-stalled' target "
+                f"'{field}' value {value!r} is not a valid duration — "
+                f"expected {DURATION_GRAMMAR}"
+            )
     return findings
 
 

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/loop/loop.py

@@ -135,7 +135,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.32.0"
+DRIVER_VERSION = "0.33.0"
 # Oldest scaffold layout this driver can drive. init.sh stamps the scaffold's own
 # version into `.specfuse/VERSION`; check_scaffold_version() fails loud at startup if
 # the consumer's scaffold is older than this, pointing at `specfuse upgrade`. Bump

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/monitor/artifact.py

@@ -24,6 +24,7 @@ from typing import Mapping, Optional
 # requirements without importing from lint_monitoring.py — that module is
 # gate 2's, and this WU only reads its shape (see the WU's "do not touch").
 _TARGET_COORDINATE_FIELDS: Mapping[str, tuple[str, ...]] = {
+    "backlog-stalled": ("name",),
     "dlq": ("subscription", "function"),
     "heartbeat": ("name",),
     "queue-stalled": ("subscription", "function"),
@@ -32,7 +33,7 @@ _TARGET_COORDINATE_FIELDS: Mapping[str, tuple[str, ...]] = {
 # Check types that must never carry target coordinates — 0069 rejected
 # `targets` on these, so `fingerprint_by` stays their single enumeration key.
 _TARGETLESS_CHECK_TYPES = frozenset(
-    {"error-logs", "http-5xx", "http-status-regression", "invariant"}
+    {"dependency-regression", "error-logs", "http-5xx", "http-status-regression", "invariant"}
 )
 
 

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/monitor/autofix_state.py

@@ -57,7 +57,7 @@ import time
 from dataclasses import dataclass
 from typing import Callable, Optional
 
-from specfuse.monitor.issues import DEFAULT_LIST_LIMIT, FINDING_LABEL, find_finding_issue
+from specfuse.monitor.issues import DEFAULT_LIST_LIMIT, FINDING_LABEL, FINDING_LIST_LIMIT, find_finding_issue
 
 # Reserved for FEAT-2026-0042 gate 2: applied to a finding issue once a fired
 # autofix attempt is known to have failed. See module docstring.
@@ -94,7 +94,7 @@ def has_prior_attempt(runner: Callable, repo: str, fingerprint: str) -> bool:
     (the runner raises, the listing is truncated) fails closed: True.
     """
     try:
-        issue = find_finding_issue(runner, repo, fingerprint, limit=DEFAULT_LIST_LIMIT)
+        issue = find_finding_issue(runner, repo, fingerprint, limit=FINDING_LIST_LIMIT)
     except Exception:  # noqa: BLE001 - fail closed on any read failure
         return True
     if issue is None:
@@ -119,7 +119,7 @@ def record_attempt(
     under a different convention.
     """
     now = time.time() if now is None else now
-    issue = find_finding_issue(runner, repo, fingerprint, limit=DEFAULT_LIST_LIMIT)
+    issue = find_finding_issue(runner, repo, fingerprint, limit=FINDING_LIST_LIMIT)
     if issue is None:
         raise LookupError(f"no finding issue carries fingerprint {fingerprint!r}")
 

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/monitor/cli.py

@@ -265,6 +265,8 @@ def _build_adapter(
         deploy_signal=check.get("deploy_signal"),
         window_after_deploy=check.get("window_after_deploy"),
         codes=check.get("codes"),
+        dependency_types=check.get("dependency_types"),
+        min_failures=check.get("min_failures"),
         # The harvest window (#3480): adapters that read event history
         # accept it; those that need older history by design do not.
         since=since,
@@ -678,11 +680,24 @@ def run_cycle(
                         continue
                     filed_fingerprints.add(fingerprint)
                     recorder = _CallRecorder(gh_runner)
-                    record_finding(
-                        fingerprint, artifact, repo, runner=recorder, now=now.timestamp(),
-                        message_ids=tuple(message_ids.get(fingerprint, ())),
-                        seen=seen_by_fingerprint.get(fingerprint), ensure_label=ensure_label,
-                    )
+                    # #3579: a filing error (a truncated listing, a gh failure)
+                    # is isolated like a check error (#3478): reported, the
+                    # watermark held so the window is retried, other
+                    # components still filed.
+                    try:
+                        record_finding(
+                            fingerprint, artifact, repo, runner=recorder, now=now.timestamp(),
+                            message_ids=tuple(message_ids.get(fingerprint, ())),
+                            seen=seen_by_fingerprint.get(fingerprint), ensure_label=ensure_label,
+                        )
+                    except Exception as exc:  # noqa: BLE001 — isolation is the point
+                        env_errored = True
+                        errored_components.add(component_name)
+                        summary.append(
+                            f"{env_name}/{component_name}: filing errored — "
+                            f"{type(exc).__name__}: {exc}"
+                        )
+                        continue
                     outcome = _classify(recorder)
                     if outcome == "created":
                         created += 1
@@ -719,7 +734,7 @@ def run_cycle(
         if env_errored:
             any_errored = True
             summary.append(
-                f"environment {env_name}: watermark not advanced — a check errored; "
+                f"environment {env_name}: watermark not advanced — a check or filing errored; "
                 "its window is retried next cycle"
             )
         elif not dry_run:

{specfuse_loop-0.32.0 → specfuse_loop-0.33.0}/specfuse/monitor/issues.py

@@ -70,6 +70,12 @@ REOPENED_MARKER = "<!-- specfuse:finding-reopened -->"
 REDIAGNOSE_LABEL = "rediagnose"
 
 DEFAULT_LIST_LIMIT = 100
+# The finding lookups' own limit, apart from DEFAULT_LIST_LIMIT (which triage
+# borrows as a page size). `gh issue list` pages internally and stops when the
+# repo runs out, so a high limit costs nothing on a small repo. 100 was low
+# enough that a busy project crossed it and every new fingerprint raised
+# TruncatedListingError (#3579); a full page at this limit still raises.
+FINDING_LIST_LIMIT = 2000
 DEFAULT_THROTTLE_SECONDS = 6 * 60 * 60
 # A finding with no sighting for this long is annotated as a close candidate
 # (#3502). Elapsed time, not a run count: the meta records when a fingerprint
@@ -330,7 +336,7 @@ def find_finding_issue(
     repo: str,
     fingerprint: str,
     *,
-    limit: int = DEFAULT_LIST_LIMIT,
+    limit: int = FINDING_LIST_LIMIT,
     now: Optional[float] = None,
 ) -> Optional[dict]:
     """Return the listing row carrying `fingerprint`'s marker, or None.
@@ -376,7 +382,7 @@ def record_finding(
     *,
     runner: Optional[Callable] = None,
     now: Optional[float] = None,
-    limit: int = DEFAULT_LIST_LIMIT,
+    limit: int = FINDING_LIST_LIMIT,
     throttle_seconds: float = DEFAULT_THROTTLE_SECONDS,
     message_ids: Sequence[str] = (),
     seen: Optional[SeenThisRun] = None,
@@ -501,7 +507,7 @@ def finding_component(body: str) -> Optional[str]:
     return match.group(1) if match else None
 
 
-def list_finding_issues(runner: Callable, repo: str, *, now: float, limit: int = DEFAULT_LIST_LIMIT) -> list:
+def list_finding_issues(runner: Callable, repo: str, *, now: float, limit: int = FINDING_LIST_LIMIT) -> list:
     """Open finding issues plus those closed inside the lookup window, each
     carrying its `state` — the same single listing `find_finding_issue` reads."""
     return _list_findings(runner, repo, limit=limit, now=now)
@@ -523,7 +529,7 @@ def annotate_if_quiet(
     now: float,
     quiet_after_seconds: float = DEFAULT_QUIET_AFTER_SECONDS,
     runner: Optional[Callable] = None,
-    limit: int = DEFAULT_LIST_LIMIT,
+    limit: int = FINDING_LIST_LIMIT,
     existing: Optional[dict] = None,
 ) -> Optional[str]:
     """Annotate an open finding issue as a close candidate once its fingerprint