Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
3ab703f
Describe each durable runner step as a typed transition
n0rpan Nov 16, 2026
ba060e6
Persist bounded lead facts with replay and stall incidents
n0rpan Nov 16, 2026
f765d3b
Commit a prepared fact without replaying the journal twice
n0rpan Nov 16, 2026
f0da0e0
test(work): reproduce facts byte retention and parent durability fail…
n0rpan Nov 16, 2026
65f463c
fix(work): retain active facts within byte bounds and sync root parent
n0rpan Nov 16, 2026
d325ab2
test(work): reproduce acknowledging an unsynced pending journal line
n0rpan Nov 16, 2026
667f15a
fix(work): sync visible pending journal data before recovery acknowle…
n0rpan Nov 16, 2026
7ca16a6
Merge remote-tracking branch 'origin/main' into agent/629-lead-facts
n0rpan Nov 16, 2026
f8753be
test(gateway): reserve fixture directories independently of wall-cloc…
n0rpan Nov 16, 2026
9e92adb
WIP: implement protected standing core and revision-bound asks
n0rpan Nov 16, 2026
0e9289c
test(work): reproduce unsynced prepared policy recovery
n0rpan Nov 16, 2026
551bb00
Complete typed standing policy, bound proposals and checked release c…
n0rpan Nov 16, 2026
ecacd23
Return revision-consistent standing and facts views for cards
n0rpan Nov 16, 2026
fd1272c
Merge remote-tracking branch 'origin/main' into agent/629-lead-facts
n0rpan Nov 16, 2026
3843f64
Merge commit 'fd1272c8bf8060c4ec24bb622ad3ae51a31fcedc' into agent/62…
n0rpan Nov 16, 2026
ab952f4
test(proto): supply explicit running steps in shared evening fixtures
n0rpan Nov 16, 2026
ccd4344
Merge commit 'ab952f4ac622a0932c12a2f6588d25a2cd2f9d9b' into agent/62…
n0rpan Nov 16, 2026
4511f9f
Merge current main while preserving standing fact validation
n0rpan Nov 16, 2026
92e8fe9
test(work): reproduce stranded standing recovery after failed fact re…
n0rpan Nov 16, 2026
b084de5
fix(work): reserve standing projection capacity before preparing policy
n0rpan Nov 16, 2026
c255237
test(work): reproduce oversized event pages that cannot advance
n0rpan Nov 16, 2026
01ea760
fix(work): bound event pages by wire size and preserve cursor progress
n0rpan Nov 16, 2026
1372010
test(work): reproduce answered-ask trimming blocking owner closure
n0rpan Nov 16, 2026
7eda27f
fix(work): preserve ask-close evidence across bounded history trimming
n0rpan Nov 16, 2026
0e9cdca
merge: retain approved standing layer after facts lands
n0rpan Nov 17, 2026
727c282
fix(work): refuse to verify released or retired standing rules
Nov 17, 2026
f797291
test(work): keep the new standing test within the formatter width
Nov 17, 2026
ca7eb1c
test(work): assert released and retired rules stay stored
n0rpan Nov 17, 2026
dbce064
test(work): expose standing privacy and cross-source boundary failures
n0rpan Nov 17, 2026
39e0a6f
Merge remote agent/629-standing preserving both histories
n0rpan Nov 17, 2026
93ffb22
fix(work): protect standing privacy and reserved fact identities
n0rpan Nov 17, 2026
a312ba7
test(work): recover standing revisions through protected append
n0rpan Nov 17, 2026
651f732
test(work): reproduce standing reservation sync retry failure
n0rpan Nov 17, 2026
df5997e
fix(work): sync visible standing reservations on retry
n0rpan Nov 17, 2026
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
5 changes: 5 additions & 0 deletions oxa/docs/lead-facts-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ it retains no unbounded per-task tombstones. Retrying the latest source/revision
fact returns its original event and timestamp, even after journal rotation. Different facts
under that identity and stale revisions are errors. Sequence exhaustion is an error.

Standing initialization reserves one of those 16 slots before its first mutation;
ordinary producers cannot consume that reservation. The `standing` checkpoint
source, `StandingChanged` observations and `standing:` ask-ID namespace belong
to the standing store's protected prepared-append path, not public `Facts::append`.

Each append validates the projected situation before reserving the event. It then saves a
pending observation in `facts.json`, appends and syncs the journal line, commits the source
cursor and atomically replaces `situation.json`. Atomic replacements sync the file and directory.
Expand Down
139 changes: 139 additions & 0 deletions oxa/docs/standing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# Standing rules and owner decisions

`oxa_work::standing` stores the owner's rules, holds and questions for one repository. It
never opens runner task state, starts a model, writes a task receipt or creates a background
thread. The runner owns command/action wiring; the lead owns cards and tool registration.

## Protected root and revisions

The trusted frontend supplies a fixed per-repository root in owner configuration, outside
workspace and writable Git binds, and the repository's `Facts` instance. Neither path comes
from tool JSON. `Standing::initialize(root, Authority::Owner, facts)` is explicit. `open`
never turns missing, partial, corrupt, unsafe or inconsistent enforcement data into empty rules.
The existing private directory/file/no-follow primitives are reused.

`read()` returns the current revision, entries, asks and explicit history-truncation flag.
`read_facts()` returns that view paired with a shared situation checked at the same standing
revision. Cards use this pair rather than joining independently read versions.
`live_rules()` excludes superseded/retired rules and released constraints; `open_asks()`
excludes answered questions. Active rules and unanswered asks share a 128-item limit. Up to
16 terminal records are retained; they may shrink to fit the 256 KiB read view. Pending
metadata is capped at 1 MiB. Active data is never dropped to make room.

An owner can close a question even when its answer would exceed the view's byte budget.
The close observation is captured before answered history is trimmed. If that new answer
is immediately trimmed, pending metadata retains that one exact answered question until
the fact commits. Recovery validates its original question and answer revision; absent or
changed evidence cannot turn a missing unanswered question into a silent close.

Every mutation supplies the document revision it read. A stale revision refuses without
changing the store. A live collision of kind/scope requires its exact `supersedes` ID.
IDs are derived from the checked revision, not from model text or time. Released and retired
records are not live: only a live entry can be verified as applied, answered or reminded.

## Authority, values and checked application

`Authority` is supplied separately by the trusted interface. It is absent from `Rule`,
`Question` and `AnswerRequest`. A model cannot claim owner authority by adding a JSON field
or quoting a message. The frontend checks the source reference and binds owner operations to
actual owner input. `said` preserves those words; `said_by` attributes them separately from
inherited hold protection. Sources name a command or saved session entry.

Kinds are goal, priority, freeze, hold, budget, model, placement, gate, eligible, decided,
reserve and note. Text policy values remain explicit data. Budgets use integer USD micros
per day; the frontend presents/parses ordinary USD amounts. Gates contain an ordered T1/T2/T3
tier and a closed set of additional evidence requirements. They supplement existing policy
floors. Reserve values use the closed public/paid/credentials/destructive/desktop classes.

Only the owner raises a budget, establishes an initial positive budget/gate, weakens a gate,
changes reserves, or releases an owner constraint. Lead reductions and conjunctive gate
strengthening are allowed. An owner hold keeps its protection through a lead replacement;
replacing it cannot turn it into a releasable lead hold or change its release condition.

Storing a rule gives it `Stored` state. Gateway caps, model profiles, placement, eligibility,
priority and merge-policy application belong to their existing runner/runtime adapters.
They consume the locked read view; this store does not invent another policy engine.
`verify` accepts only a frontend-owned checker reporting the exact current revision, scope,
actual value and evidence reference. Mismatches leave the rule Stored. An accepted proposal
also starts Stored; it does not claim a runtime was reconfigured.

Reminders require owner context and a checked source. Counts, the latest source/time and
incident observations persist. After two reminders a live note reports that a conversion
should be offered. It is never converted automatically. An explicit owner decision may
supersede that note with an enforced kind.

## One action guard

`with_guard(action, subject, callback)` reloads and establishes the current policy's durability
under its stable lock. Subject identity is resolved by the trusted frontend; a missing PR
means checked absence, and a known PR must always be supplied. Admission can precede a PR.
Approve/enqueue/update require a positive PR identity. There is no head-dependent hold key.

A live hold refuses admit, push, approve, enqueue and update. Freeze refuses approve/enqueue.
Both apply immediately while Stored. `is_held(pr)` is a read for presentation; a preceding
read never authorizes an effect. Callback receives `&Read` with the exact guarded revision,
including the other policy values for their owning adapters, and runs only after guard success.
It must not recursively read/write this Standing instance.

The lock covers one effect and its result, never an entire worker, loop or batch. The caller
owns bounded execution/cancellation, side-effect idempotency and its receipt containing the
guarded revision. It must invoke another guard before the next effect. The store's guard
does not override existing tool, sandbox, gateway or publishing policy.

## Questions and proposals

The existing ask tool's payload is reused: question, 2–4 unique label/detail options and an
exact-label recommendation. Stored asks add ID, question revision, scope, time/source,
optional meanwhile plan and an optional owner answer. Unknown meanwhile remains `None`.
The existing UI/journal adapter is not replaced by a second tool in this module.

`ask` records the question. A recommendation never answers it or grants permission.
`answer` requires owner context, the current document revision and the exact question
revision. Option labels are checked; free text is stored as free text. Answers preserve the
owner's actual words/source. A generic answer labelled "Release" cannot release a hold.

`propose` binds an exact typed Rule to an ask and an accept label. Cards **must render that
rule's actual kind, scope and value**, not only model-written labels/details. Scope must match
the question. Only selecting that label through the owner interface applies the bound rule;
it cannot substitute a new value. A changed/superseded target refuses without closing the ask.
Free text has no implicit accept meaning. Other answers close only the question. This changes
standing data, never performs a GitHub/paid/tool side effect.

A named `PrMerged(N)` condition can release a hold/freeze without asking for a second decision
already authorized by the owner. `release_when` uses a frontend-owned checker and requires the
exact matching `PrMerged` Event retained in this same Facts store. The runner records that
verified merge first. Wrong PRs, invented events and unavailable observations refuse; prose,
a successful worker and a changed head are insufficient. The resulting release retains its
source words and records checked merge evidence. Only the separate merge fact is landed work.

## Durable fact handoff

One fixed `standing` emitter uses the document revision. `StandingChanged` projects revision,
goal, one ask transition and an optional incident. Full rule/option/answer data stays in this
protected file. It does not emit two different facts under one source/revision.

Event pages honor both the requested count (at most 64) and the serialized byte limit.
Large valid observations return smaller pages with `next` at the last included event;
readers keep advancing through retained history and receive explicit retention gaps.

Under Standing → Facts lock order, the facts module validates capacity/semantics and durably
reserves an unpublished observation **before** the callback saves the pending policy. Other
appenders cannot consume its projection capacity, even if the process dies in the callback.
Only after the policy is durable is the reservation made replayable and its fact appended;
the current policy is committed last. Ordinary facts keep their existing append path.

Recovery syncs a visible prepared policy, completes its reserved fact once, commits the policy
and establishes durability before another action. If the durable policy has no pending
mutation, a matching unpublished next-revision reservation has no prepared data: recovery
discards only that reservation, preserving the current rules, revision and committed facts.
A rejected initial projection leaves no policy mutation. A failed fact reservation therefore
cannot strand an ask; the owner can still answer an existing ask to free capacity.

Recover standing before replaying runner callbacks that append facts. A facts-only read reports
the last committed sequence; it never publishes an unfinished standing preparation. The
standing read/guard APIs perform this recovery under their stable lock. No background worker
or task-state writer is added, and a failed observation stops before an effect.

The runner owns `oxa work rule|hold|ask`, actual action guards and local command proofs. The
lead joins detailed asks by ID from `Read` with the small shared situation. These adapters
must be wired and proven before claiming the complete #629 L2 user flow is delivered.
26 changes: 24 additions & 2 deletions oxa/oxa-proto/src/work.rs
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,16 @@ record!(
);
record!(AskClosed { id: String } | s | { atom(&s.id, 128) });
record!(Incident { id: String, subject: Subject, kind: IncidentKind, evidence: Option<Evidence> } |s| { atom(&s.id, 256) });
record!(
/// One durable standing revision. Ask details/answers stay in the protected standing file.
StandingChanged {
revision: u64, goal: Option<String>, ask_opened: Option<Ask>,
ask_closed: Option<AskClosed>, incident: Option<Incident>
} |s| {
require(s.revision > 0, "standing revision must be positive")?;
require(s.ask_opened.is_none() || s.ask_closed.is_none(), "standing mutation has two ask transitions")
}
);
record!(
Mechanical {
subject: Subject,
Expand All @@ -441,6 +451,7 @@ tagged!(
AskOpened(Ask) => "ask_opened",
AskClosed(AskClosed) => "ask_closed",
Incident(Incident) => "incident",
StandingChanged(StandingChanged) => "standing_changed",
Mechanical(Mechanical) => "mechanical",
}
);
Expand All @@ -451,6 +462,11 @@ impl Fact {
Self::Mechanical(_) => EventClass::Mechanical,
Self::Blocked(_) | Self::AskOpened(_) => EventClass::Attention,
Self::Incident(incident) => incident.kind.class(),
Self::StandingChanged(change) if change.ask_opened.is_some() => EventClass::Attention,
Self::StandingChanged(change) => change
.incident
.as_ref()
.map_or(EventClass::Routine, |incident| incident.kind.class()),
_ => EventClass::Routine,
}
}
Expand All @@ -463,8 +479,14 @@ record!(
at_ms: u64,
checkpoint: Checkpoint,
fact: Fact
} | s
| { require(s.seq > 0, "event sequence must be positive") }
} |s| {
require(s.seq > 0, "event sequence must be positive")?;
if let Fact::StandingChanged(change) = &s.fact {
require(s.checkpoint.source == "standing" && s.checkpoint.revision == change.revision, "standing checkpoint identity disagrees")?;
}
require(s.checkpoint.source != "standing" || matches!(s.fact, Fact::StandingChanged(_)), "standing source is reserved for standing revisions")?;
Ok(())
}
);
record!(
/// A bounded materialized read view, not task state. Never drop running/blocked/asks to fit.
Expand Down
Loading
Loading