@sleepy_panda_srl/portulan 0.3.0 → 0.4.0

package/spec/workspace.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://portulan.dev/spec/2.13/workspace.schema.json",
-  "title": "Portulan Workspace Definition v2.13",
+  "$id": "https://portulan.dev/spec/2.16/workspace.schema.json",
+  "title": "Portulan Workspace Definition v2.16",
   "description": "The manifest at the root of a workspace. It is an index, not a container: it names the slots the engine resolves against and points at the Markdown that holds each slot's content and rationale. Written in a deliberately small subset of JSON Schema 2020-12 — see spec/README.md for the subset and for what validates it.",
   "type": "object",
   "additionalProperties": false,
@@ -145,6 +145,10 @@
           "description": "The `id` of the recipe the Stop-gate runs when nothing more specific applies. Constrained to the same shape as an id, so a value no recipe could ever carry is rejected by the schema rather than only by `doctor`.",
           "$ref": "#/$defs/slug"
         },
+        "stopTimeout": {
+          "description": "Optional, added in 2.14. Stop recipe deadline in seconds; undeclared, 90. A positive integer whose recipe and outer hook timers fit Node's timer range, checked by doctor and every reader. Compile gives the Stop hook sixty additional seconds for other checks and cleanup.",
+          "type": "number"
+        },
         "recipes": {
           "type": "array",
           "minItems": 1,
@@ -247,20 +251,65 @@
     },
 
     "handoffs": {
-      "description": "Optional, added in 2.5. What the handoff series' generated index is called — the same split as `memory` above, and for the same reason: `slots.handoffs` is the series, this is the machine configuration over it. One key and no more. There is deliberately NO budget here, and the absence is the considered half: a budget's only permitted remedy is consolidation — merge, compress, split, retire (core/operating/memory.md) — and a handoff series is append-only by construction. Retiring a handoff to buy headroom destroys the record it exists to keep; SPLITTING one — the move 2.8 added for the per-record rail — leaves the series no smaller; and raising the budget in the change that breached it is the one repair that doctrine rules out. Every remedy such a budget could ask for is barred, which makes it a rail designed to be broken. Whether the series should be budgeted on some other axis is a maintainer's question, deferred rather than answered here — and a key that exists but must never be set would be this specification pre-empting that answer in the shape of an invitation.",
+      "description": "Optional. Configuration over slots.handoffs. Since 2.15 an individual new handoff may have a token cap and the generated index may carry a token-budgeted window. The append-only series has no aggregate budget. Proposal 0037 supplies the rule and repair boundary.",
       "type": "object",
       "additionalProperties": false,
-      "required": ["index"],
+      "required": [
+        "index"
+      ],
       "properties": {
         "index": {
-          "description": "Required whenever `handoffs` is present, which is the one way this object differs from `memory` above. There, an object with no `index` is coherent — a workspace may rail its store's size and generate nothing. Here the object has exactly one key and no budget, so `handoffs: {}` configures nothing at all: a no-op that reads as configured to anyone who greps for it, which is the same failure `librarian.staleness.proposal_days` without `slots.proposals` is refused for. The generated index over the handoff series. Built by `cli/index.mjs` and byte-compared by a verify recipe on the same terms as the memory index: every field on a line is derived from the series — the ISO date off the filename, the title off the record's own H1 — so nothing in the file can be edited into disagreement with what it indexes. Its path must resolve OUTSIDE `slots.handoffs`: a file in that directory whose name carries no date already fails the `record` check, and one that did carry a date would be counted as a handoff by the correspondence check. Sited beside the series, both stay true without either check learning a filename to ignore.",
+          "description": "Required whenever handoffs is present. The derived newest-first index lives outside slots.handoffs. A kept copy is byte-compared; absent means render on demand. An optional token budget selects a contiguous newest-first window, preserving every source handoff.",
           "type": "object",
           "additionalProperties": false,
-          "required": ["path"],
+          "required": [
+            "path"
+          ],
           "properties": {
             "path": {
               "description": "Where the generated index is written, relative to the workspace root.",
               "$ref": "#/$defs/filePath"
+            },
+            "budget": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "tokens"
+              ],
+              "properties": {
+                "tokens": {
+                  "type": "number",
+                  "description": "Added in 2.15. Positive integer, explicitly declared, measured at context.ratio. The entire index, header and omission notice included, must fit. Too small for overhead is refused with the minimum required budget."
+                }
+              }
+            }
+          }
+        },
+        "series": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "budget"
+          ],
+          "properties": {
+            "budget": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "record_tokens",
+                "cutoff"
+              ],
+              "properties": {
+                "record_tokens": {
+                  "type": "number",
+                  "description": "Added in 2.15. Positive integer token cap on each handoff dated strictly after cutoff, at the explicit context.ratio. Compression or moving facts to their owning records repairs a breach; never splitting or deleting history."
+                },
+                "cutoff": {
+                  "type": "string",
+                  "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+                  "description": "Required real YYYY-MM-DD day. Set to the declaring change date or newest merged handoff date, whichever is later. The cutoff day stays unbound. Moves only with a tighter cap or lower ratio, never backward; review holds those history-dependent rules."
+                }
+              }
             }
           }
         }
@@ -341,17 +390,17 @@
           }
         },
         "ratio": {
-          "description": "How bytes become tokens. Declared, and measured exactly on demand rather than on every run: the exact count asks the host, which is a network call no verify recipe may make, and a ratio that moved between runs would make one tree red on one run and green on the next.",
+          "description": "How bytes become tokens. Manually declared for a compile host rather than recalibrated on every run. The on-demand provider counter returns an estimate of the measured project corpus, including API framing, not actual host usage; the maintainer accepted this limit for #506 on 2026-11-09. No verify recipe may invoke the network mode.",
           "type": "object",
           "additionalProperties": false,
           "required": ["bytes_per_token", "calibrated_by"],
           "properties": {
             "bytes_per_token": {
-              "description": "Bytes per token, as the host's exact count measured them. At least 1: a token covers at least one byte, so a smaller figure is tokens per byte entered inverted, and `doctor` refuses it, since the subset has no `minimum`.",
+              "description": "Manually assessed bytes per token for the host's measured domain. At least 1, guarding against inverted units; doctor refuses a smaller declaration because the subset has no minimum. A tiny corpus counted with API framing can yield an effective ratio below this floor, which the provider report labels not declarable.",
               "type": "number"
             },
             "calibrated_by": {
-              "description": "The host whose exact count calibrated the ratio, by the id `compile` gives that host. No date is recorded here: the commit that changes the ratio dates it.",
+              "description": "The compile host whose measurement domain the manually declared ratio describes, by its compile ID. Provider/model attribution stays in the count report; it is not a new compile host. Doctor checks a non-empty string, not the calibration's provenance. The commit that changes the ratio dates it.",
               "$ref": "#/$defs/slug"
             }
           }
@@ -395,7 +444,7 @@
       }
     },
     "spend": {
-      "description": "Optional, added in 2.12. The multipliers and the horizon the restart threshold is computed at, `F × (1 + m_w / (n × m_r))` in proposal 0038's arithmetic, from its ruling 2: the manifest declares the multipliers, as `context.ratio` declares bytes per token, so a team's contracted rates and its host's real prices are one declared value. Nothing is defaulted in the manifest: undeclared, `cli/ledger.mjs` and the restart advisory use the general multipliers, a cache read at a tenth of an uncached input token and a write at 1.25× for five minutes or 2× for an hour, and the 20-request horizon of ruling 3, and say `undeclared`. Declared, `compile` writes the figures onto the advisory's commands, and `cli/ledger.mjs --workspace` reads them. `restart`, added in 2.13, says what a crossed threshold does. The subset has neither `minimum` nor `maximum`, so every range below is `doctor`'s.",
+      "description": "Optional, added in 2.12. The multipliers and the horizon the restart threshold is computed at, `F × (1 + m_w / (n × m_r))` in proposal 0038's arithmetic, from its ruling 2: the manifest declares the multipliers, as `context.ratio` declares bytes per token, so a team's contracted rates and its host's real prices are one declared value. Nothing is defaulted in the manifest: undeclared, `cli/ledger.mjs` and the restart advisory use the general multipliers, a cache read at a tenth of an uncached input token and a write at 1.25× for five minutes or 2× for an hour, and the 20-request horizon of ruling 3, and say `undeclared`. Declared, `compile` writes the figures onto the advisory's commands, and `cli/ledger.mjs --workspace` reads them. `restart`, added in 2.13, says what a crossed threshold does. `resume.tokens`, added in 2.16, prices additional restart expense; the threshold gains resume / (horizon × read). Unknown resume expense makes the comparison a lower bound and never holds a Stop. The subset has neither `minimum` nor `maximum`, so every range below is `doctor`'s.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
@@ -439,8 +488,15 @@
             }
           }
         },
+        "resume": {
+          "description": "Optional, added in 2.16. Additional restart expense in uncached-input-token equivalents, excluding the fresh-context write and baseline reads already priced. Include handoff output, boot/state recovery and additional rereads over the horizon. These are weighted cost units: 2,000 output tokens at 5x contribute 10,000 equivalents. Absent means unknown; explicit zero is priced. Doctor checks the finite nonnegative bound.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["tokens"],
+          "properties": { "tokens": { "type": "number" } }
+        },
         "restart": {
-          "description": "Optional, added in 2.13. What a crossed restart threshold does: `advise`, what an undeclared workspace gets, says the advisory's line once with a tool result or at a prompt; `block` also holds a turn's end once, at the first stop at or past the threshold that no block provoked, with the same line as the reason, compiled as a second `Stop` command beside the Stop-gate's. Nothing ends the session either way. Proposal 0038's ruling 3: a report by default, a rail by declaration.",
+          "description": "Optional, added in 2.13. What a crossed restart threshold does: `advise`, what an undeclared workspace gets, says the advisory's line once with a tool result or at a prompt; `block` also holds a turn's end once, only with an explicit horizon and resume expense and finite strictly positive estimated savings at a stop that no block provoked, with the same line as the reason, compiled as a second `Stop` command beside the Stop-gate's. Nothing ends the session either way. Proposal 0038's ruling 3: a report by default, a rail by declaration.",
           "type": "string",
           "enum": ["advise", "block"]
         }