Skip to content

Q-Deck A0: candidate-state continuity #91

Closed

Description

@PhysShell

Actual resolution (2026-08-04) — ACCEPTED / CLOSED / FROZEN

This issue's plan was executed exactly as specified below, contract-first. Only the tracking status ("PLANNED / UNSTARTED") went stale while execution proceeded in PR #92; reconciled by PR #100.

execution:
  a0_0_contract:
    status: completed
    commit: 71800fce8d6c0c7a7dc513950271dcd116149a63
    ordering: preceded_implementation    # the FIRST commit of PR #92,
                                         # "Freezes the design before any
                                         # implementation" — a single
                                         # contract-only document
    normative_source: docs/q-deck/a0-candidate-state.md

  a0_implementation:
    status: completed
    corrective_rounds: 8                 # forward-only; no amend/rebase/
                                         # squash/force-push between heads
    accepted_head: 52627c33f0c3b58e9ce68e0573fc67f0566d5c87
    pr: 92
    merge_commit: f1ac458731e23da2c48ca3ef84f44992727f76fe

  residuals:
    status: tracked_separately           # "Post-A0 hardening before A2"
    reopens_a0: false

The original body below is preserved unchanged as the historical planned contract. It is not rewritten to pretend it always knew the future.


Status

PLANNED / UNSTARTED. This is the first post-R1 Alpha slice.

Frozen predecessor

  • R1 accepted implementation head: e2e046af10e13aa961aa54974912dd50787b196c
  • R1 merge commit / current main starting point: eead3b775cf0d5d1ea567b6eb496a555637c1f95
  • e2e046a..eead3b7 contains only the merge commit and no file delta.

A0 work must start in a fresh branch and fresh child worktree from exact merge commit eead3b775cf0d5d1ea567b6eb496a555637c1f95. Never reuse an R1 implementation or review worktree.

Goal

Prove minimal candidate-state continuity across one accepted Command:

sealed parent run A
+ exact canonical candidate state produced by A
+ accepted command B
-> fresh child worktree materialized from A's verified candidate state
-> child run B sees that state and may extend it

R1 proved provider-session continuity only. A0 must add candidate-state continuity without reopening a sealed run, trusting a mutable live worktree, or making the ledger an alternate canonical authority.

A0.0: freeze the contract before implementation

The first commit must define the representation and authority model. At minimum it must answer:

  1. What exact object is the candidate state: canonical patch, bundle/archive, tree object, or another deterministic representation?
  2. Which canonical event references it, and which digest covers its bytes and identity metadata?
  3. What base committed revision does it apply to?
  4. How is repository identity bound?
  5. How is cumulative ancestry represented for A -> B -> C without replaying unrelated mutable state?
  6. What is the fail-closed behavior for missing, tampered, conflicting, or non-applicable candidate state?
  7. What remains deliberately outside A0?

No implementation should precede this contract commit.

Required invariants

Canonical authority

  • Candidate state must be digest-bound by the parent's canonical record.
  • Ledger rows, worktree records, paths, branch names, and mutable repository state are projections/conveniences, never candidate-state authority.
  • Exact parent RunId, conversation, repository identity, base revision, and candidate-state digest must be bound together.
  • A sealed parent's candidate receipt is immutable.

Fresh materialization

  • Every child gets a newly created, independently attested worktree.
  • Never reopen or mutate the parent's worktree for the child.
  • Materialize the committed base, then apply only the verified candidate state.
  • The source repository and its checked-out branch remain untouched.
  • Existing o7-worktree ownership/attestation rules remain in force; a serialized record or path alone never authorizes use or deletion.

Command lineage

  • The child canonical record must bind the exact parent candidate-state digest it consumed.
  • A child may consume candidate state only from its exact accepted parent lineage.
  • Same-conversation but wrong-parent, wrong-repo, stale-tail, copied receipt, altered base revision, or altered patch/archive must fail closed before provider invocation.

Determinism and safety

  • Re-materializing the same verified parent candidate state must produce the same initial child tree.
  • Candidate application failure must not invoke the provider.
  • Crash/retry behavior must preserve R1's dispatch-boundary and at-most-once guarantees.
  • Cleanup/recovery must never delete a worktree unless existing ownership and filesystem identity checks independently prove it is ours.

Minimal end-to-end acceptance case

  1. Start from a committed fixture repository.
  2. Parent run A changes an existing file and creates a new file.
  3. A seals with a canonical candidate-state receipt.
  4. Submit command B against A.
  5. B is executed in a fresh child worktree.
  6. Before provider execution, prove B's initial tree contains A's exact two changes.
  7. B adds a third change and seals.
  8. The original repository checkout remains byte-identical to its starting state.
  9. A's worktree and B's worktree have distinct paths and filesystem identities.
  10. Canonical replay proves which candidate digest B consumed.

Required negative/adversarial cases

  • missing candidate receipt;
  • receipt referenced by event but artifact missing;
  • altered candidate bytes;
  • copied candidate from another run;
  • rewritten receipt metadata with wrong parent/run/conversation;
  • wrong repository identity;
  • wrong base revision;
  • patch/archive that does not apply cleanly;
  • path traversal, symlink, submodule, mode-bit, binary-file, rename, and deletion cases according to the frozen representation contract;
  • mutable parent worktree changed after sealing;
  • source repository changed after parent sealing;
  • concurrent same-key retries;
  • crash after child worktree creation but before durable dispatch boundary;
  • crash after durable dispatch boundary.

Every invalid/non-applicable case must fail before provider invocation and must not mutate the source repository, parent record, or command binding beyond the documented recoverable state.

Explicit non-goals

  • No command queue or multi-agent orchestration.
  • No merge/commit/push of candidate state into the user's branch.
  • No automatic conflict resolution.
  • No distributed or multi-host lease protocol.
  • No UI beyond the minimum needed to expose truthful state.
  • No force-redrive or operator resolution for R1 ambiguous outcomes.
  • No general workflow DSL.

Work protocol

Stop condition

A0 stops after one accepted Command demonstrably consumes and extends its exact parent's verified candidate state in a fresh worktree. Broader local-alpha UX and multi-command productization are subsequent slices, not reasons to inflate A0.

Activity

  1. PhysShell commented on Aug 2, 2026

    @PhysShell
    OwnerAuthor

    A0.0 contract inputs from A1 drafting (#95) and the OTP-lens review

    Design input only — nothing here expands A0 scope. All three items are answers-in-progress to questions A0.0 already owns (§A0.0 items 1, 2, 6), surfaced while drafting the A1 contracts (#95).

    1. Candidate sealing boundary (normative here, consumed by A1)

    The sealing boundary is part of the definition of canonical candidate state, so it must be normative in A0.0 — not in A1, which would otherwise define when the very capability it claims to consume becomes valid.

    Quiescence is defined by revoked write authority, not by process death:

    1. the producer invocation can no longer receive authorized work;
    2. its write capability / lease epoch is durably revoked or advanced;
    3. no previously issued writer capability remains valid under that
       revoked or advanced epoch;
    4. filesystem ownership and identity still match the attestation;
    5. the candidate snapshot is taken after the revocation boundary;
    6. descriptor and artifact bytes are durably accepted before sealing.
    
    No candidate state exists canonically before this sequence completes.
    

    The epoch formulation is deliberate: the invariant holds because old authority is no longer valid under the advanced epoch — not because an implementation enumerated every capability ever issued and hunted down live holders. Process termination and descendant absence are proof mechanisms or additional guards, never the definition: a detached descendant can keep writing after every known process has exited, and a live process can be provably incapable of writing. PIDs and process trees are observations, not authority — the same rule already applied to serialized worktree paths.

    Not "nobody is alive anymore" — "nobody alive retains the right to write."

    A1 (#95 §3) consumes this as a capability:

    seal_candidate(worktree_attestation, producer_run) -> CandidateRef
    

    2. Result identity vs transport representation

    Whatever physical form A0.0 chooses (patch, archive, bundle, tree object), it is transport. Two distinct identities must exist and must never share a field:

    candidate content identity
      = resulting tree/state digest
    
    candidate receipt identity
      = digest(
          protocol_version,
          repository_identity,
          conversation_id,
          producer_run_id,
          base_revision,
          resulting_tree_digest,
          transport_digest,
          transport_media_type,
          canonical metadata
        )
    

    The mandatory bindings are enumerated deliberately — #91 already requires exact parent RunId, conversation, repository identity, base revision, and candidate digest to be bound together, and they must be listed, not hidden behind a word like "binding". (If A0.0 chooses a different exact name for the conversation binding, use that name.) accepted_command_id is deliberately absent: the parent's candidate exists before any child command does; command-to-receipt binding belongs to the consumption protocol.

    The state is identified by its result; the receipt is identified by the result together with its context and provenance; the format remains transport.

    Materialization verifies both levels, fail-closed at every step:

    stored transport bytes
    -> transport digest matches
    -> transport applies under frozen rules
    -> resulting tree digest matches
    -> descriptor bindings match repository / conversation / producer / base
    -> candidate accepted
    

    A transport that applies cleanly but does not reproduce the recorded tree digest is an integrity failure, not a near-miss. This makes the patch-vs-archive-vs-bundle decision a transport question rather than a truth question, and closes the tool-version / rename-heuristic / line-ending class from the adversarial matrix by construction: identity proves the value, not the instruction.

    3. A0-local identity distinction (deliberately narrow)

    A0.0 defines only the identities its own protocol needs:

    stable protocol identities:
      accepted command
      parent run
      candidate receipt
    
    execution incarnations:
      child run attempt
      materialization attempt
      worktree lease / attestation
    

    Principle:

    Retry or rematerialization may create a new execution incarnation without changing the accepted command or the parent candidate identity.

    The full logical-lineage taxonomy (root_goal / task / campaign / round vs run / attempt / provider invocation) is deliberately not frozen here — it belongs to A1 (#95) and the A2 reducer freeze. A0 must only avoid conflating state identity with materialization attempt.


    Generated by Claude Code

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions