Add df.status_by_label() and clarify df.status() requires instance_id

[Copilot]

df.status() accepts an instance_id, not a label — passing a label silently returns NULL, making it easy for callers who use df.start(..., 'my-label') to unknowingly query the wrong identifier.

New function: df.status_by_label(label TEXT)

Returns the status of the most recently started instance matching the given label. Respects RLS (queries via SPI). Returns NULL when no visible instance matches.

SELECT df.start('SELECT 1', 'my-workflow');

-- Before: callers would mistakenly do this (always returns NULL)
SELECT df.status('my-workflow');

-- Now: correct label-based lookup
SELECT df.status_by_label('my-workflow');  -- 'Running', 'Completed', etc.

Labels are not unique — if multiple instances share a label, the most recently created one wins. Save the instance_id from df.start() when you need to track a specific run.

Changes

• src/monitoring.rs — status_by_label implementation; documents NULL-on-error behaviour (consistent with df.status())
• sql/pg_durable--0.1.1.sql — C wrapper registration for fresh installs
• sql/pg_durable--0.2.1--0.2.2.sql — CREATE OR REPLACE FUNCTION for the upgrade path
• docs/api-reference.md — warning note on df.status() clarifying it needs an instance_id; full entry for df.status_by_label()
• USER_GUIDE.md — updated Quick Status Check section with label-based example and tip
• docs/upgrade-testing.md — added df.status_by_label() to the monitoring functions table
• tests/e2e/sql/05_monitoring_and_explain.sql — tests correct status for a known label and NULL for an unknown one

[crprashant]

PR #181 — Society of Thought Review (parallel) + Independent Opus 4.8 Self-Review

Target: microsoft/pg_durable PR #181 (Issue #167 — "Clarify that df.status() accepts instance_id, not label")
Adds: df.status_by_label(label TEXT) + docs/tests/SQL registration
Diff reviewed: rebased locally onto current main d8396ad — clean 8 files / +111 −4

Review Summary

• Mode: society-of-thought (parallel) + independent self-review (Opus 4.8)
• Specialists (9): architecture, assumptions, correctness, edge-cases, maintainability, performance, release-manager, security, testing
• Final tally: 2 must-fix · 4 should-fix · 2 consider ·
• Ruled out: B1 backward-compat, SQL injection, live RLS disclosure

Independent Self-Review Reconciliation (Opus 4.8)

An independent pass re-derived every claim from the raw diff, schema SQL, and sibling source — no specialist conclusion overturned.

Finding	Panel	Opus 4.8 verdict	Net
Upgrade/version placement (MF-1)	must-fix	Corroborated; two registrations mutually inconsistent	Confidence ↑
Status casing (MF-2)	must-fix	Corroborated + reframed: pre-existing repo-wide doc bug	Scope widened
Duplicate-label determinism (SF-1)	should-fix	Corroborated (now()=txn-start → ties)	—
NULL conflation (SF-2)	should-fix	Corroborated; Rustdoc good, user docs omit caveat	—
Missing label index (SF-3)	should-fix	Corroborated	—
MODULE_PATHNAME (SF-4)	should-fix	Corroborated; same PR self-contradicts	Evidence ↑
RLS coverage (C-1)	consider	Corroborated guardrail; no live disclosure	—
B1 backward-compat	open question	RULED OUT (label exists since 0.1.1.sql:50)	Phantom cleared
Wrong issue # in SQL comment	not raised	New (consider): cites #165, PR is #167	Added

---

🔴 Must-Fix

MF-1 — Install/upgrade paths don't register the function; PR edits obsolete history.
Cargo.toml=0.2.4, but status_by_label appears only in 0.1.1.sql (old fixture) and 0.2.1--0.2.2.sql (already-shipped). Absent from baseline 0.2.2.sql and the 0.2.2→0.2.3→0.2.4 forward chain → fresh 0.2.4 installs and upgraders past 0.2.2 never get the function. Editing a shipped upgrade script is itself a hazard.
Fix: add CREATE OR REPLACE FUNCTION df.status_by_label(text) to the correct forward script + regenerate fresh-install fixture; verify both CREATE EXTENSION and ALTER EXTENSION UPDATE with to_regprocedure(...); run ./scripts/test-upgrade.sh.

MF-2 — Status casing contract mismatch.
Implementation returns the raw lowercase status column (CHECK allows only pending/running/completed/failed/cancelled, 0.2.2.sql:95-96), but docs advertise title-case 'Running','Completed'. The new e2e test lower()s both sides, masking it. Opus reframe: this is pre-existing & repo-wide — df.status()'s own docs were already wrong; the fix must cover df.status() too.

🟡 Should-Fix

SF-1 — Duplicate-label nondeterminism. created_at DEFAULT now() = txn-start time → ties; ORDER BY created_at DESC LIMIT 1 returns an arbitrary tied row. Add a monotonic tie-breaker (e.g. id DESC) or document ties as unspecified.

SF-2 — NULL conflates no-match vs SPI error. .ok().flatten() (same as sibling df.status()). Rustdoc states this; user docs omit the caveat.

SF-3 — No index for label lookup. Only idx_instances_status exists; WHERE label=$1 ORDER BY created_at DESC is seq-scan+sort on a growing table vs df.status()'s PK lookup. Add (label, created_at DESC) (or RLS-covering variant).

SF-4 — Hardcoded 'pg_durable' vs MODULE_PATHNAME. Same PR contradicts itself: 0.1.1.sql:3727 uses MODULE_PATHNAME, 0.2.1--0.2.2.sql:58 hardcodes 'pg_durable'. Standardize on MODULE_PATHNAME.

🔵 Consider

• C-1 Add cross-user RLS regression test for label lookup (no live exploit found — SECURITY INVOKER + RLS confirmed; just a guardrail).
• C-2 Cover or reject the empty-string label boundary (STRICT only guards NULL).

Observations

• No exploitable disclosure (bound $1, no SECURITY DEFINER, RLS scopes by current_user).
• [Opus] B1 ruled out — label column present since the first shipped schema.
• [Opus] Issue-# nit — SQL comment cites #165, PR is #167.
• [Opus] Framing — the docs half fully satisfies Clarify that df.status() accepts instance_id, not label #167 and is a guaranteed win; maintainers could ship docs now and gate the function behind MF/SF fixes.

[crprashant]

see above review comments. @pinodeca let me know i can start a fresh PR to close this issue, as this PR 181 is behind the main by 74 commits.