Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/python-sdk.yml
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ jobs:
retention-days: 30
- run: python -m pip install --no-deps -e bindings/python-adapters/sqlite
- run: pytest -q bindings/python/tests
timeout-minutes: 3
- run: pytest -q bindings/python-adapters/sqlite/tests
- run: >-
ruff check bindings/python/python bindings/python/tests
Expand Down
62 changes: 62 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -309,8 +309,70 @@ intentional result of a dependency update. Do not regenerate them gratuitously.
- Comments should record non-obvious invariants and design decisions, not
narrate implementation steps.


### Explicit state ownership

No implicit state machines are allowed in new or changed workflows. If legal
next operations depend on history, identify one authoritative state owner and
enforce its named states, events, guards, required payloads, and transitions.
This includes asynchronous resource ownership, authorization, concurrency,
external effects, and durable recovery.

Do not distribute a lifecycle across unrelated flags, optional fields,
callback-local variables, filesystem markers, or duplicate status records.
Independent facts may remain booleans and actual absence may remain optional.
Compact two-state or consuming representations are valid when their named
transition contract is enforced in one place and hides no consequential
pending, closing, failed, or uncertain state. Replacing flags with an enum
without fixing transition ownership does not satisfy this rule.

Claim pending-operation ownership before external I/O or an await. Bind each
completion to that operation; recheck guards that may change while waiting.
Snapshot mutable decision inputs into owner-controlled memory before pending
admission; pass separate copies to external code and validate completions
against the retained snapshot. Readonly fields and shallow freezing do not
establish byte ownership. Specify exact bound fields and ownership transfers.

Define what each competing or reentrant caller receives: rejection, a shared
operation result, or a new operation. Distinguish cancellation/deadlines of an
individual waiter from cancellation/deadlines of the owned operation. Define
late-completion, cleanup failure/retry, and resource-publication behavior.
A terminal flag must not stand in for unfinished cleanup, and an error or
cancellation must not be treated as proof of non-effect.

Keep one semantic authority for each managed transition. Extend the existing
kernel, journal, or resource owner; do not add a parallel executor, recovery
ledger, or universal lifecycle framework. Persist necessary recovery facts
through the existing durable boundary and derive status from those facts.
Preserve provider/domain distinctions and the abstraction extraction gates.

Every change to such a workflow must document its states and ownership boundary
and add deterministic evidence for relevant competing events and failures.
Durable changes require applicable crash/restart and adapter evidence. Review
phase-specific payloads and invalid transitions, not just the happy path.
Before changing a recovery protocol, finish its command/transition tables,
competing-writer results, durable acknowledgement/synchronization ordering,
and interruption matrix. Naming those as future design tasks is insufficient.
Follow AP-SPEC-076 for the initial remediation inventory and acceptance gates.

## Testing and handoff

### Stateful change review

The PR description or linked spec must answer:

1. What history changes the legality of the next operation, and who owns it?
2. What orders competing/reentrant events, what identifies a completion, and
which result does each caller observe?
3. What data/capability is required by each phase, who can construct it, and
which mutable inputs are copied before crossing an asynchronous boundary?
4. How do waiter cancellation and operation cancellation differ? What happens
on timeout, stale completion, late resource creation, and partial cleanup/retry?
5. Where is durable success acknowledged, which synchronization/commit facts
support it, and what happens on repeated commands, competing writers, lost
acknowledgements, and restart immediately after acknowledged success?
6. Which exact tests exercise those schedules and preserve effect/receipt truth?

### Batch test and assurance hardening

Never use incremental write–run cycles when adding or hardening tests, checks,
Expand Down
95 changes: 13 additions & 82 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,8 @@ rustix = { version = "1.1.4", default-features = false, features = ["fs", "net",
seccompiler = "0.5.0"
zeroize = { version = "1.9.0", features = ["derive"] }
zip = { version = "8.2.0", default-features = false, features = ["deflate-flate2-zlib-rs"] }
rmcp = { version = "1.8.0", default-features = false, features = ["server"] }
# The MCP profile converts official model values; it does not run rmcp services.
rmcp = { version = "3.9.0", default-features = false }
serde_json_canonicalizer = "0.3.2"
tempfile = "3.27.0"
tar = { version = "0.4.44", default-features = false }
Expand Down
4 changes: 1 addition & 3 deletions architecture/dependency-graph.json
Original file line number Diff line number Diff line change
Expand Up @@ -8319,9 +8319,7 @@
"target_condition": null,
"optional": false,
"default_features": false,
"features": [
"server"
]
"features": []
},
{
"source": "auths-profile-mcp",
Expand Down
55 changes: 55 additions & 0 deletions bindings/fixtures/gateway/managed-cli-inventory.json
Original file line number Diff line number Diff line change
Expand Up @@ -1158,6 +1158,11 @@
"long": "recipe-family",
"required": false
},
{
"name": "resume",
"long": "resume",
"required": false
},
{
"name": "state_dir",
"long": "state-dir",
Expand Down Expand Up @@ -1450,6 +1455,21 @@
}
]
},
{
"command": "qualification-recover",
"arguments": [
{
"name": "help",
"long": "help",
"required": false
},
{
"name": "state_dir",
"long": "state-dir",
"required": true
}
]
},
{
"command": "qualification-status",
"arguments": [
Expand Down Expand Up @@ -1555,6 +1575,41 @@
}
]
},
{
"command": "recovery-status",
"arguments": [
{
"name": "action",
"long": "action",
"required": false
},
{
"name": "approval",
"long": "approval",
"required": false
},
{
"name": "candidate",
"long": "candidate",
"required": false
},
{
"name": "help",
"long": "help",
"required": false
},
{
"name": "proof",
"long": "proof",
"required": false
},
{
"name": "state_dir",
"long": "state-dir",
"required": true
}
]
},
{
"command": "review",
"arguments": [
Expand Down
8 changes: 8 additions & 0 deletions bindings/fixtures/gateway/managed-interface-unix.json
Original file line number Diff line number Diff line change
Expand Up @@ -527,6 +527,10 @@
"command": "qualification-import",
"help_accessible": true
},
{
"command": "qualification-recover",
"help_accessible": true
},
{
"command": "qualification-status",
"help_accessible": true
Expand All @@ -543,6 +547,10 @@
"command": "recovery-record",
"help_accessible": true
},
{
"command": "recovery-status",
"help_accessible": true
},
{
"command": "review",
"help_accessible": true
Expand Down
Loading
Loading