ms2k/remora
SHA256
Watch
0
Code Releases Activity

Tighten activation recovery and API contracts

Browse source
This commit is contained in:
ms2k 2026-07-14 19:04:00 +09:00
commit 3062bf3d75
1 changed files with 268 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/api/README.md
View file

@ -39,12 +39,21 @@ after durable authority changes. It never creates or restores a claim. Progress
and outcome operations require current fenced authority and return
`precondition_failed` for stale or non-authoritative tuples.
Activation returns the live lease expiry and a recommended renewal time. Renewal
returns the corresponding updated projection. These timestamps schedule worker
behavior; the coordination store remains authoritative for whether the lease is
live.
A successful claim returns the attempt authority and the attempt's
`ExecutionEnvelope`. The worker verifies that their job, attempt, fence, and
worker incarnation agree before source or target I/O. Opaque resolved-source
and checkpoint references identify durable streamable state; they are not
worker incarnation agree before source or target I/O. Resolved-source and
checkpoint descriptors identify durable streamable state; they are not
reconstructed from coordination data.
Resolved-source and checkpoint references carry their descriptor kind, schema
version, byte length, and SHA-256. The service accepts them only when their kind,
ownership, integrity, and fenced attempt authority match the mutation.
[`RemoraApiMutation`](../protocol/RemoraApiMutation.tla) models this durable
operation ledger around an abstract successful `JobProtocol` effect. It does
not redefine job phases or attempt-authority transitions. Its `Rejected`
@ -62,6 +71,11 @@ bound to the authenticated subject and filter.
credential values, bearer material, URL userinfo, raw upstream response bodies,
internal stack traces, or unredacted configured endpoints.
Credential creation uses a closed material shape selected by `kind`; rotation
must use the existing kind's shape. Custom HTTP headers use lowercase canonical
names and reject connection-nominated, routing, framing, cookie, proxy, and
authentication headers.
## Jobs, pages, and results
`Job.phase` uses the exact `JobProtocol` phase vocabulary; this contract does
@ -81,6 +95,10 @@ unauthorized, absent, and never-committed results are not exposed. The hard
delete endpoint returns the durable deletion resource established by the
architecture.
Before hard deletion, job reads return the complete `job` projection. Once only
the permanent minimal record remains, authorized reads and deleted-job pages use
the distinct `tombstone` projection rather than inventing discarded job fields.
A deletion whose exact remaining work cannot progress because target access or
configuration is unavailable enters `blocked` with a redacted problem. It
retains the deletion obligation and can return to active processing when the