Skip to content

docs(adr): propose ADR-0037 worker compatibility and capability admission (WC-01) - #184

Open
avalla wants to merge 20 commits into
mainfrom
docs/wc-01-capability-admission-contract
Open

avalla wants to merge 20 commits into
mainfrom
docs/wc-01-capability-admission-contract

Conversation

@avalla

@avalla avalla commented Oct 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

WC-01 of M24 (Worker Compatibility & Capability Admission): the gap analysis and the contract that will replace the static Codex/Claude version and model allowlists with exactly-bound, evidence-backed, owner-certified admission. Documentation only. Proposes ADR-0037; nothing is implemented and no allowlist, worker, routing or local configuration changes.

Task

  • Task: 99b23a02-59a3-4a5a-b82e-bc21874299f3 — WC-01 Capability Admission Contract (milestone M24, requirements WC-R01–WC-R14)
  • Acceptance criteria:
    • ADR-0037 Proposed (ADR-0036 belongs to M23); ADR-0037 verified free on every local and remote ref
    • exact subject: worker, version, model, effective configuration, protocol (plus platform and mode); certifying one subject certifies no other
    • capabilities with evidence proportional to risk; provider/client declarations have weight zero
    • evidence bundle separated from certification decision; a digest is not trust
    • host-local, content-addressed, immutable, owner-approved, revocable, atomically updated registry
    • drift relevant to a required guarantee refuses new runs (typed); informational drift advisory; expiry opt-in and never overrides security checks
    • probes propose but cannot approve; live tests only with explicit per-execution authorization (model, version, USD); no paid CI call
    • bounded versus governed delegation distinguished; native delegation unsupported
    • release monitoring and a recertification procedure
    • Claude legacy policy unchanged and never represented as certified; WC-07 to evaluate and propose a transition
    • plan, roadmap and docs index updated; Runtime requirement, task and link records aligned
    • no production code, no live test, no worker/routing/configuration change

Scope

  • In scope: docs/adr/ADR-0037-… (Proposed), docs/development/worker-compatibility-admission.md, an M24 section in docs/development/roadmap.md, an entry in docs/README.md. Runtime records (14 requirement descriptions and titles, 6 task descriptions, 7 task-requirement links) were aligned outside Git.
  • Non-goals: any code, allowlist or admission-rule change; WC-02 or later; live or paid tests; renumbering historical ADRs; M12/M18/M21 deliverables.

Dependencies

  • Task depends on: none.
  • Branch based on: origin/main (c3fdb25), not stacked.
  • Note: in the Runtime WC-02 depends on WC-01 completing. WC-02 must additionally wait for ADR-0037 to be Accepted; its description says so.

Design notes

Normative contract is the ADR; the plan does not restate it. Key choices, all following the owner's decisions of 2026-10-16 (D1–D7, recorded in the ADR):

  • subject tuple with a configuration digest computed from the adapter's effective configuration, so a flag change in source changes the subject;
  • four guarantee states, four risk tiers, a deterministic sufficiency table; evidence bundles, certification decisions and revocations are distinct immutable records; trust is recomputed (sufficiency, approval class, harness provenance), not read from a hash;
  • manifest generations published by atomic rename with a previous-manifest digest chain (tamper-evident, not tamper-proof); the same-user limit is stated and left to M10;
  • baselines (baseline_import for the current Codex combination, legacy_policy for the Claude floor) reproduce today's behavior without being presented as certification, introduced in shadow mode with a differential test.

Open decisions O1–O5 for the owner are listed in the ADR (unobservable metadata dependencies, reading of the legacy exception, sufficiency table, local_operator approval class until M10, catalogue freeze).

Verification

Check Command Result Commit
Baseline bun run check exit 0, 3470 tests passed c3fdb25
Formatting bunx prettier --check on the four files pass c0c2192
Diff git diff --check origin/main..HEAD clean c0c2192
Head bun run check see the hardening update below d9c7f4d

Review

  • Independent reviews: see the hardening update below.
  • External review (Codex): required, not satisfied; see below.

Limitations and follow-ups

  • No enforcement exists until WC-02/WC-05; the ADR is Proposed.
  • No pipeline run was started in the Runtime: the project's delivery pipeline is enforced, and starting a run would bind the task to stage performers I cannot be assigned to; the task-delivery gates were followed instead. Owner to decide if a run is wanted.
  • The M21 plan is not yet in the repository, so M21 is referenced through its Runtime records only.

Merge

Do not merge without explicit authorization. READY FOR MERGE is not DONE:
post-merge verification is still required.

🤖 Generated with Claude Code

https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t

Hardening update (2026-10-19) - HEAD d9c7f4d

Documentation only; ADR-0037 stays Proposed; O1-O6 stay open for the owner; nothing is implemented.

  • The plan's ASCII dependency graph implied WC-02 -> WC-06, contradicting the task table (WC-06 depends on WC-03 only): replaced by an adjacency list identical to the table.
  • ADR-0037 decision 5 listed the six *_mismatch values as reasons and also used them as dimensions of no_matching_audit: it now states that the public code follows the primary reason (a known model with an unaudited version stays WORKER_UNAVAILABLE, as today).
  • The open-decisions table, misaligned by the O6 row, is reformatted.

Evidence: bun run check exit 0 on d9c7f4d (3470 passed, 242 skipped); GitHub CI 13/13 green. Independent read-only review of the delta and the whole PR: no confirmed findings; constants checked against the code (auditedCodexVersions, Claude floor, run.ts gate, global.sqlite docs) and links resolved.

The global.sqlite review thread stays open on purpose: it is open decision O6, owned by the owner (see the non-normative comparison).

External review (Codex): not satisfied on the final head. The Codex CLI and the GitHub connector are unavailable (usage limit); no other review stands in for it. The independent review below is by a subagent of the same model family, not Codex.

…sion

WC-01 of M24: gap analysis of the static Codex/Claude version and model
allowlists, the admission-subject, guarantee, evidence/decision and registry
contract, drift and expiry rules, bounded versus governed modes, baseline and
legacy policy handling, recertification procedure, plan, roadmap section and
docs index entry. Documentation only; no allowlist, worker, routing or
configuration change.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-16T06:52:51.649788Z c0c2192 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c0c21925e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/adr/ADR-0037-worker-compatibility-and-capability-admission.md Outdated
Comment thread docs/adr/ADR-0037-worker-compatibility-and-capability-admission.md Outdated
Comment thread docs/adr/ADR-0037-worker-compatibility-and-capability-admission.md Outdated
Comment on lines +188 to +190
A host-local registry, because the facts describe the clients installed on one
host and the Runtime has no host-level database; PostgreSQL authority is
unaffected.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Re-evaluate the registry against the existing host database

The premise that the Runtime has no host-level database is false: docs/architecture/overview.md:618 documents <runtime-home>/global.sqlite, runtime-paths.ts resolves it, and the daemon opens it at startup. Since this premise is used to reject database persistence and introduce a separate object/manifest store with its own locking, integrity, backup, and audit semantics, the ADR should either explain why the existing database's ownership contract disqualifies it or compare a dedicated/extended SQLite store against the proposed filesystem registry.

AGENTS.md reference: AGENTS.md:L24-L28

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Partially confirmed. The 'no host database' premise was already corrected, but the rationale only rejected reusing global.sqlite and never compared a dedicated SQLite store against AGENTS.md (authoritative state in SQLite behind the Runtime). bd832fc rewrites the Alternatives and records the choice as a new open owner decision O6 that blocks acceptance and WC-02. Left open on purpose: not settled by this PR.

avalla and others added 18 commits October 16, 2026 09:00
Narrow the self-certification claim to what the Runtime provides and state the
same-account limit; specify legacy_policy as a closed source-shipped predicate
with its own admission rule; exempt baseline records from the sufficiency table
and forbid registry decisions with baseline or legacy bases; define the full
admission step order, closed reason set and reason-to-public-code table; keep
the per-dispatch adapter checks; make supersession single-active; retain every
manifest and record the last accepted generation; reword harness provenance as
a recorded claim; fix facts, naming and the dependency graph.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
…cedence

Add a model-admissibility step ahead of per-dispatch observations so the public
error codes and the current model-before-inspect order are preserved, with an
exact reason-to-code table; give exact decisions (active or revoked) precedence
over the legacy predicate and never fall back after a revocation; treat an
absent registry as empty only before any generation was accepted; correct the
pre-release clause of the Claude predicate; keep the execution-time Codex login
re-admission; refuse certified decisions with unobservable dependencies until
O1 is decided.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
Extend the model-admissibility step to the run's persisted parameters so that
today's supportsModel refusals (output-token cap, unsupported reasoning effort)
remain refusals; add the parameter clause to the claude-legacy-floor@1
predicate and parameters to the differential matrix; name one reason for the
explicit-requirement case; specify the state reset as planned, approved and
audited, and add it to the WC-02 command shapes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
After a record matches in step 4, require the run's parameters to lie within
that record's own parameter scope so one subject's scope cannot admit another's
runs; state the parameter scope of the Codex baseline import.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
…external review

Refuse the snapshot when a committed manifest or revocation is missing or
invalid, honor only revocations listed by committed manifests, make manifests
cumulative for revocations, check the legacy predicate record for revocation,
select the single active exact decision so a superseded predecessor cannot
block its successor, enforce notBefore with a typed reason, and make the
implicit bounded requirement set one named set that includes the routed-model
guarantee.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
…sion

An invalid decision listed by a committed manifest now blocks its subject
instead of letting the legacy predicate admit it; a decision named by a
committed revocation is revoked even if still listed as active.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
Limit rollback and tampering detection to inconsistencies while the recorded
state is intact and name the independently protected anchor as M10 scope; scope
the "new version stays refused" statement to subjects needing an exact
certification and describe the Claude legacy exception; make blocked subjects
explicit in model admissibility; record the WC-02 gate on the blocked-subject
scope.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
… parity

Bind claude-legacy-floor@1 to the source-shipped configuration profile, output
protocol and supported platforms; pass explicit requirements to admit
separately and derive the mode-implied set inside it so the legacy exception
tests for empty explicit requirements; list drift, validity-window and
registry-integrity refusals as expected differences of the shadow comparison;
scope the blocked-subject rule to the current manifest's active set and forbid
dropping an active decision without a revocation.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
…ock, order model first

Take the subject used for blocking, matching and revocation from the manifest
binding so a corrupted decision cannot move its subject to the legacy
predicate; make registration, revocation and reset share one publication
exclusion with the planned generation rechecked under it; run model and
run-parameter admissibility before platform and mode so unsupported models keep
WORKER_MODEL_UNSUPPORTED on every platform; clarify bundle-citing decisions and
that re-pinning the legacy predicate needs owner approval.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
…nd storage rationale gaps

- A reload that meets a committed manifest or revocation it cannot verify
  fails closed; the previously loaded snapshot stays in force only when no
  newer committed object was read, so a revoked decision cannot be readmitted.
- admit takes an explicit dispatchContext (persisted run parameters,
  per-dispatch observation outcomes, evaluation timestamp) so steps 1, 3 and 5
  have no hidden state.
- Correct the rationale: a host-level global.sqlite exists, but it is the
  reusable-memory store and is deliberately not reused for admission facts.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZEHMaJc8oY8hS3FUSQw1t
…y baseline checks

Re-evaluate ADR-0037 against the Codex review threads on PR #184. Compare the
file registry with the existing global.sqlite and a dedicated host-level SQLite
store against AGENTS.md, and leave the choice to the owner as O6. State that
the deterministic sufficiency checks govern registered decisions while
source-shipped baselines follow decisions 9 and 10, and that a baseline
declares its metadata dependencies as unobservable.

Claude-Session: https://claude.ai/code/session_01Q21NUKiVwrCvpZ5YgzjM5W
…O6 options

A failed reload no longer keeps the previously loaded snapshot in force: a
state file that records no newer generation cannot prove that no newer
revocation was published (a writer can publish the pointer and stop before the
state is updated). Any reload that does not end in a fully verified snapshot
refuses every subject with registry_unreadable until a later reload verifies.
A pointer ahead of the recorded state is accepted only after the whole chain
verifies; an older pointer is a rollback. Persistence stays open decision O6;
a non-normative comparison of the file and dedicated-SQLite options is added.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
… advanced

A pointer ahead of the recorded state is accepted only after chain
verification; if the state then cannot be durably advanced, a later pointer
rollback would match the stale state and drop a revocation. The reload now
fails closed with registry_unreadable. AGENTS.md citations in the ADR and the
O6 comparison say "project state" as the rule is worded.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
… mode_unsupported reachable

Review hardening. Ancestry of the recorded manifest validates against rollback
only; admission uses the snapshot built from the generation the pointer names.
Step 1 no longer matches a mode without a governed contract, so a model lookup
cannot mask mode_unsupported. The O6 comparison states the anchor update order
and the verified-successor recovery instead of claiming the crash window
disappears.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
…rsisted model

Review hardening. admitModel runs before any observation so an unsupported
model still launches no process, probe or login read; admit repeats the step.
Unrouted and historical runs have no exact subject and are admitted only
through the legacy predicate on the resolved model, with provenance basis
legacy_policy, and join the WC-05 differential matrix.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
@avalla

avalla commented Oct 19, 2026

Copy link
Copy Markdown
Owner Author

Update for head 8ac0ae9 (docs only, ADR-0037 stays Proposed): ChatGPT P1 confirmed and fixed. A failed reload never keeps the previous snapshot; admission uses only the snapshot of the pointed-to generation; a pointer ahead of the state is accepted only after chain verification and a durable state advance, otherwise registry_unreadable. Also: staged admitModel preflight, unrouted/historical runs via their resolved model, non-normative O6 comparison (docs/development/wc-01-o6-registry-persistence-comparison.md). O6 is NOT decided and the ADR is NOT accepted; WC-02 does not start. Evidence: bun run check exit 0, CI green (13/13), independent architect review, Codex static review of the diff text (several P2 rounds fixed; final pass: no findings).

@avalla avalla left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent ChatGPT ADR review — HEAD 8ac0ae9 (static source review, not Codex CLI)

Technical verdict: no additional confirmed P1/P2 defect found in the reviewed revised contract. Revisited the registry loading/revocation invariants, admission preflight and ordering, baseline imports, and bounded legacy Claude exception. The prior fail-closed contradiction is addressed: a failed reload refuses all new admissions, and a prior snapshot cannot silently remain authoritative. The model preflight is explicitly staged ahead of launching a worker.

Outstanding design gate: O6 (content-addressed files vs dedicated SQLite registry) remains undecided and the corresponding review thread intentionally open. The comparison is non-normative. Do not mark ADR-0037 Accepted or start WC-02 until the owner selects the persistence model and the normative ADR is reconciled. O1–O5 should also be recorded as explicit owner decisions rather than inferred from recommendations.

Evidence: GitHub workflows on this HEAD are green; no Bun tests were executed by this reviewer. The PR description's consolidation note names an earlier HEAD and should be refreshed.

Gate: This is a static ChatGPT review, not a successful codex review --base origin/main. It does not replace the configured external-review gate.

… rule

- The plan's ASCII graph attached WC-06 to the bus that WC-02 also feeds, which
  contradicted the dependency table (WC-06 depends on WC-03 only). Replace it
  with an adjacency list identical to the table.
- ADR-0037 listed the six *_mismatch values as reasons and also used them as
  dimensions of no_matching_audit, without saying which one selects the public
  code. State that the code follows the primary reason, so a known model with
  an unaudited version stays WORKER_UNAVAILABLE as today.
- Realign the open-decisions table, which the O6 row had left misformatted.

ADR-0037 stays Proposed; O1-O6 stay open for the owner.

Claude-Session: https://claude.ai/code/session_01FKM37BV4LS8Rc8ny5GCwXy
@avalla

avalla commented Oct 19, 2026

Copy link
Copy Markdown
Owner Author

Hardening cycle closed on d9c7f4d: dependency graph aligned with the task table; decision 5 now says the public code follows the primary reason; table reformatted. Independent review of the whole PR found no further defect. ADR-0037 stays Proposed. The global.sqlite thread remains open on purpose (open decision O6, the owner's call). bun run check exit 0 (3470 passed), CI 13/13. Codex gate: not satisfied.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant