Skip to content

Commit 53e884a

Browse files
authored
docs: a hosting layer may re-place an arena_exhausted run; the development service does not (#542)
docs: a hosting layer may re-place an arena_exhausted run; the development service does not Four docs stated that a hosting layer re-places a run that fails with arena_exhausted on "the next rung of a trusted ladder, escalation cap 2". The current development service has no such ladder: it makes one attempt on a fixed template arena, never retries, and returns the typed failure as engine_failed. The docs now say a hosting layer MAY re-place the run on a larger arena, and that the development service does not: docs/design/arena-bound.md, docs/design/arena-bound-corpus-census.md, docs/scratch-store.md, and the two matching lines of the memory-management page. Docs only; no code, no behaviour change. Removed sentences, named for the doc-reverts gate (both were introduced by commit 91353de): - docs/design/arena-bound.md: "A typed `arena_exhausted` re-places the run on the next rung of COMPUTE's trusted ladder, with escalation cap 2." - docs/design/arena-bound-corpus-census.md: "COMPUTE uses the default attempt-0 arena and its trusted escalation ladder: a typed `arena_exhausted` re-places the run on the next rung, escalation cap 2, never charged to the user, with an alert." docs: drop the last escalation promise; scope the charging and alert policy to COMPUTE Follow-up to the arena_exhausted re-placement correction. - docs/design/arena-bound.md, the "Unbounded emitting loop" row: "Default attempt-0 arena and escalation apply." becomes "Default attempt-0 arena applies." (the development service has no escalation). - docs/design/arena-bound.md and docs/design/arena-bound-corpus-census.md: "Arena exhaustion is never charged to the user and raises an alert" is now scoped: it is COMPUTE's policy, and the development service's behaviour is the one stated beside it (one attempt on a fixed template arena, no retry, returned as engine_failed). The charge and alert behaviour is not claimed for the development service. Docs only; no code, no behaviour change.
1 parent 4c113fc commit 53e884a

4 files changed

Lines changed: 28 additions & 20 deletions

File tree

‎docs/design/arena-bound-corpus-census.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,12 @@ currently unavailable facts, each known probe has the three sizing names in
4545
| finalizerStream | 312 | 0 | 312 |
4646

4747
All 312 known probes therefore have no tightening available. COMPUTE uses
48-
the default attempt-0 arena and its trusted escalation ladder: a typed
49-
`arena_exhausted` re-places the run on the next rung, escalation cap 2,
50-
never charged to the user, with an alert. Today no run has the facts needed
51-
for certified tightening; the bound tightens nothing yet.
48+
the default attempt-0 arena: a typed `arena_exhausted` is not retried by
49+
the current development service (one attempt on a fixed template arena; a
50+
hosting layer MAY re-place the run on a larger arena). COMPUTE's policy is
51+
that arena exhaustion is not charged to the user and raises an alert; the
52+
development service's behaviour is the one stated here. Today no run has the
53+
facts needed for certified tightening; the bound tightens nothing yet.
5254

5355
| Informational term | Own unbounded/unknown flag | Proved unbounded | UNCLASSIFIED |
5456
| --- | ---: | ---: | ---: |
@@ -91,7 +93,7 @@ For each source-marked probe:
9193
probe list, counts for the three names in unboundedTerms, and a separate
9294
informational childPrivate flag count. Missing input or unclassified
9395
coverage makes the certification harness fail; production uses the
94-
default attempt-0 arena and escalation.
96+
default attempt-0 arena.
9597

9698
The source inventory is deliberately not a complete Pine type/dataflow
9799
analyzer. No trusted general finite-proof producer currently exists in
@@ -105,7 +107,7 @@ retained in `corpus_run`. It guards a lab proof that compares actual arena
105107
usage to a certified value. Passing without any certified run would claim
106108
evidence that does not exist. This guard does not implement production
107109
admission or routing and does not contradict the default arena and
108-
escalation policy.
110+
re-placement policy.
109111

110112
## Re-run on a populated checkout (reading only)
111113

‎docs/design/arena-bound.md‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -82,16 +82,19 @@ make both its population and byte lengths finite.
8282
For 1.7.0, COMPUTE starts attempt 0 with its default arena. A certified bound
8383
only tightens attempt 0 where the required facts exist. A true top-level
8484
`unbounded` means **no tightening available**: retain the named unresolved
85-
sizing terms and use the default attempt-0 arena and the escalation ladder.
85+
sizing terms and use the default attempt-0 arena.
8686
This applies equally to missing proofs, proved unbounded growth and finite
8787
bounds outside the representation range.
8888

89-
A typed `arena_exhausted` re-places the run on the next rung of COMPUTE's
90-
trusted ladder, with escalation cap 2. Arena exhaustion is never charged to
91-
the user and raises an alert. The child's private allocations are capped by
92-
its `RLIMIT_AS`; exceeding that cap is the strategy's own typed
89+
A typed `arena_exhausted` is a failure that a hosting layer MAY answer by
90+
re-placing the run on a larger arena. The current development service does
91+
not: it makes one attempt on its fixed template arena, never retries, and
92+
returns the typed failure as `engine_failed`. COMPUTE's policy is that arena
93+
exhaustion is not charged to the user and raises an alert; the development
94+
service's behaviour is the one stated above. The child's private allocations
95+
are capped by its `RLIMIT_AS`; exceeding that cap is the strategy's own typed
9396
`memory_limit`, charged to the user. The calculator reports facts and
94-
verdicts; COMPUTE owns the default, ladder and re-placement policy.
97+
verdicts; COMPUTE owns the default arena and any re-placement policy.
9598

9699
## Facts and the producer's proof obligations
97100

@@ -769,7 +772,7 @@ The eight JSON vectors were calculated by hand:
769772
| Unicode | D=2,Q=4,L=2,T=2,R=2,E=2; B=48+64+197+125+260+1024+180+1024+15192+32=18146; b=1+14=15; q=1; A=18*1048576=18874368. |
770773
| Million points | B=24*1048576+1222=25167046; ceil=25 MiB; b=25+14=39; q=36//13=2; A=(39+6)*1048576=47185920 (45 MiB). K=2 MiB leaves Bcert=39 MiB. Half=23592960 rounds down to 22 complete chunks=23068672, below the actual 24 MiB curve=25165824 even before any command reservation. |
771774
| All terms | B=18146, b=15, q=1; A=18*1048576=18874368 as for Unicode. Primary one-page RSS/two-page AS; extra bar+two column+close buffers consume four pages with RSS copies=2: RSS=36864, AS=24576. Counts T/E/O/V/K/X/H=3/2/2/5/1/3/2; line maxima 717/154/190/263/71/140/25. U=2097152+2151+308+380+1315+71+420+50=2101847. Private RSS/AS are null and its own flag is true; top-level unbounded=false, unboundedTerms=[], reason="". |
772-
| Unbounded emitting loop | Null arena inputs except E=2; no finite guessed size. unboundedTerms=[arena,ohlcv,finalizerStream]; childPrivate remains informational. Default attempt-0 arena and escalation apply. |
775+
| Unbounded emitting loop | Null arena inputs except E=2; no finite guessed size. unboundedTerms=[arena,ohlcv,finalizerStream]; childPrivate remains informational. Default attempt-0 arena applies. |
773776

774777
All eight vectors use the three-term verdict; CR150-CX's combined-arena
775778
arithmetic leaves the current logical B contributions unchanged. The first six have
@@ -950,7 +953,7 @@ and cause incomplete proof coverage to fail. The
950953
retained: this lab harness must not pass without any certified arena to
951954
compare with actual usage. It is a certification failure, not a production
952955
admission or sizing decision. Production still uses the default attempt-0
953-
arena and escalation ladder without a bound. Every measured run prints actual,
956+
arena without a bound. Every measured run prints actual,
954957
bound and actual/bound; the minimum ratio identifies worst conservatism.
955958
No measured worst ratios exist yet. An 18 MiB allowance for a one-chunk
956959
curve can be 18x over actual; the fixture's deliberately loose fill/lot

‎docs/pages/memory-management.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,9 @@ can add them up; each is read from the source named in
202202
`scripts/arena_bound.py` returns a certified byte count or marks the term
203203
`unbounded`. It certifies nothing for a general strategy in this release, because
204204
the compiler facts it needs are not produced yet, so a host starts from its
205-
default arena and re-places the run on a larger one after `arena_exhausted`.
205+
default arena and may re-place the run on a larger one after `arena_exhausted`
206+
(a host that makes one attempt, such as the current development service,
207+
returns the failure instead).
206208
* An engine export or report field that returns a planned byte count before a
207209
run: none exists in this release, so the formula and the constants above are the
208210
only way to size a run before it starts.
@@ -233,7 +235,7 @@ or bounds the row.
233235
| Signal | Meaning |
234236
| --- | --- |
235237
| `scratch_capacity_exceeded`, argument `resource` | A slab region ran out. Admit larger maxima before another attempt |
236-
| `report_sink_failed`, reason `arena_exhausted` | The inherited arena filled. The host re-places the run on a larger arena |
238+
| `report_sink_failed`, reason `arena_exhausted` | The inherited arena filled. A host may re-place the run on a larger arena; one that makes a single attempt returns the failure |
237239
| `scratch_io_failed` | A scratch read, write, create or resize failed, or the command-scratch byte cap was reached |
238240
| `scratch_configuration_invalid` | `PINEFORGE_COMMAND_SCRATCH_MAX_BYTES` is not a positive decimal |
239241
| `out_of_memory` | The allocator failed. It is not relabelled as a capacity failure |

‎docs/scratch-store.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,7 @@ using the arena's 1 MiB chunks. Each store has at least one chunk of capacity.
226226
The complete K/chunk directory is reserved once at open; writes do not allocate
227227
a directory.
228228
Crossing K is typed `arena_exhausted` before claiming any chunks,
229-
at every arena size including the default and largest hosting rung.
229+
at every arena size including the default and the largest a host offers.
230230
The run byte budget is reserved before growth and released on
231231
failed growth or destruction. Arena mode supports `buffered` sync; `data` and
232232
`full` return `programming_error`.
@@ -241,9 +241,10 @@ particular, arena exhaustion remains `report_sink_failed` with reason
241241
`needed_bytes_lower_bound` is the ARENA size that can satisfy this store:
242242
ceil(chunkCeil(required store extent after the refused write) / f), using exact
243243
integer arithmetic and saturating at INT64_MAX, the failure-argument transport
244-
maximum. It is not the store's own shortfall. The hosting layer re-places a run
245-
on this typed failure; a need beyond its largest arena continues to raise the
246-
same failure until the host stops re-placement. A separate command byte-budget
244+
maximum. It is not the store's own shortfall. A hosting layer MAY re-place a run
245+
on this typed failure (the current development service does not: it makes one
246+
attempt on a fixed template arena); a need beyond a host's largest arena
247+
continues to raise the same failure until the host stops re-placement. A separate command byte-budget
247248
refusal retains its existing status-only `io_error`.
248249

249250
Every attempted `read_page`, `write_page` and `sync` is reported once to the

0 commit comments

Comments
 (0)