@sleepy_panda_srl/portulan 0.1.3 → 0.2.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.8/workspace.schema.json",
-  "title": "Portulan Workspace Definition v2.8",
+  "$id": "https://portulan.dev/spec/2.13/workspace.schema.json",
+  "title": "Portulan Workspace Definition v2.13",
   "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,
@@ -127,6 +127,10 @@
         "personas": {
           "description": "Optional, added in 2.6. The workspace's own per-persona layer: one directory per persona whose memory scope a composed pack declares. It is NOT where personas are defined — those live in `core/personas/` and in the packs — it is where the memory each of them scopes lands, in the layer its owner controls (docs/vision.md thesis 6: storage follows ownership). Declared rather than derived from `slots.memory`, and both halves of that are deliberate. Not derived, because a path this specification computed would be Portulan choosing a location inside every adopter's workspace in a key nobody typed — the same reasoning that leaves every memory budget undefaulted. And not a subdirectory of the store, because `core/operating/memory.md` holds per-agent memory apart precisely so a reviewer's recall does not spend the implementer's budget, and a nested store would be counted by the store's own KB rail and invisible to the walk that counts it (issue #76). Each directory is **empty until earned**: the pack declares the scope and carries none of its contents.",
           "$ref": "#/$defs/dirPath"
+        },
+        "context": {
+          "description": "Optional, added in 2.10. The guidance a host loads, one unit per Markdown file, each declaring in its own frontmatter the load tier it belongs in: `always`, `on-path` (with the `paths` it is scoped to), `on-invoke` or `on-read`, the four tiers of core/operating/context.md. Its pair is the top-level `context`: this slot holds the guidance and that key its budget, as `slots.memory` holds the records and `memory` their configuration. `compile` reads it and emits each host's own form of each tier, and a tier a host cannot express degrades to an on-read pointer, never to nothing. The frontmatter is `compile`'s to check, since this subset cannot see inside a file, and so is that the slot lies outside `.claude/` and the workspace's `compile/`, where `compile` writes; spec/slots.md carries the contract.",
+          "$ref": "#/$defs/dirPath"
         }
       }
     },
@@ -227,8 +231,13 @@
                   "type": "number"
                 },
                 "record_kilobytes": {
-                  "description": "Optional, added in 2.8. The most kilobytes (1024 bytes) any ONE record may hold. This is to `kilobytes` what `memory.index.budget.columns` is to `memory.index.budget.lines`: an aggregate cannot see inside its units, so one enormous record absorbs what a store budget counts, exactly as one enormous line absorbs what a line budget counts. Breaches are LOCAL — record X over its cap never blocks writer Y — and the repair menu is live rather than barred: SPLIT the record where it holds more than one fact (which spends the count axis, `memory.index.budget.lines`), COMPRESS it, or DEMOTE its narrative to the provenance layer. Never a raise in the change that breached it (core/operating/memory.md). A positive integer, on the same terms as `lines`.",
+                  "description": "Optional, added in 2.8. The most kilobytes (1024 bytes) any ONE record may hold. This is to `kilobytes` what `memory.index.budget.columns` is to `memory.index.budget.lines`: an aggregate cannot see inside its units, so one enormous record absorbs what a store budget counts, exactly as one enormous line absorbs what a line budget counts. Breaches are LOCAL — record X over its cap never blocks writer Y — and the repair menu is live rather than barred: SPLIT the record where it holds more than one fact (which spends the count axis, `memory.index.budget.lines`), COMPRESS it, or DEMOTE its narrative to the provenance layer. Never a raise in the change that breached it (core/operating/memory.md). A positive integer, on the same terms as `lines`. With `cutoff` beside it (2.11), it binds only the records dated after the cutoff.",
                   "type": "number"
+                },
+                "cutoff": {
+                  "description": "Optional, added in 2.11, and only beside `record_kilobytes`, which `doctor` checks because the subset has no `dependentRequired`. The day from which the per-record cap binds, forward only, in proposal 0037's shape for a handoff: a record dated after it and over the cap is red, one dated on or before it is reported and never railed. Every record then carries a `**dated:** YYYY-MM-DD` line, the day its text last changed, because a verify rail may not read git; an edit re-dates a record, so an old one meets the cap in the change that next rewrites it. A missing or unreal date is refused, and so is one more than a day after the UTC date the check runs on. The cutoff is set to the declaring change's date or the newest record's, whichever is later, and moves only in a change that tightens the cap; it never moves earlier, a rule the change's review holds, since no rail reads git history. A real day written YYYY-MM-DD, which `doctor` checks past this pattern.",
+                  "type": "string",
+                  "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
                 }
               }
             }
@@ -238,7 +247,7 @@
     },
 
     "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, one per session, held to the Session log by a verify recipe's count-based correspondence. Retiring a handoff to buy headroom would either red that check or destroy the record it exists to keep; SPLITTING one — the move 2.8 added for the per-record rail — would put two dated handoffs against a single session and red the same correspondence from the other direction; 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, 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.",
       "type": "object",
       "additionalProperties": false,
       "required": ["index"],
@@ -304,6 +313,138 @@
           }
         }
       }
+    },
+    "context": {
+      "description": "Optional, added in 2.9. What the always tier may cost, and the ratio it is counted at: the machine half of core/operating/context.md, the way `memory` is of core/operating/memory.md, and the page is the one source for what each load tier holds. Requires `ratio`, because a token budget with nothing to count it by is not a budget; that is the one dependency here the subset can state, so it is the schema's rather than `doctor`'s. Nothing is defaulted, on the memory budgets' reasoning: a default would be this specification setting a policy for every workspace that adopts it, in a key nobody typed.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ratio"],
+      "properties": {
+        "always": {
+          "description": "The always tier, as core/operating/context.md defines it. Named for its tier, so a budget on a later tier would sit beside it rather than force a rename.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["budget"],
+          "properties": {
+            "budget": {
+              "description": "A rail, not an aim, and never repaired by a raise in the same change (core/operating/context.md): a breach is repaired by demotion to a later tier, by merge or by retirement.",
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["tokens"],
+              "properties": {
+                "tokens": {
+                  "description": "The most tokens the always tier may load, counted at `ratio.bytes_per_token`. Must be a POSITIVE INTEGER: the subset has no `minimum` and cannot say `integer`, so `doctor` refuses zero, negative and non-integer values.",
+                  "type": "number"
+                }
+              }
+            }
+          }
+        },
+        "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.",
+          "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`.",
+              "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.",
+              "$ref": "#/$defs/slug"
+            }
+          }
+        }
+      }
+    },
+    "sessions": {
+      "description": "Optional, added in 2.11. The host switches that change what a fresh session writes into the prompt cache: the machine half of core/operating/sessions.md, from proposal 0038's rules 3 and 4. Nothing is defaulted: an undeclared switch is the host's own default and `compile` emits nothing for it, and a switch is declared once an A/B run has shown it cuts spend with no loss.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "git_instructions": {
+          "description": "`false` drops the host's git instructions from every session in the repository: on Claude Code, the startup git snapshot and the commit and pull-request instructions, compiled into the project settings as `includeGitInstructions`. A session that needs them is started with them restored (core/operating/sessions.md).",
+          "type": "boolean"
+        },
+        "cache_lifetime": {
+          "description": "The main conversation's prompt-cache lifetime, compiled into the project settings as Claude Code's `promptCacheTtl`: five minutes where the next use of the prefix comes within five minutes, an hour where sessions idle.",
+          "type": "string",
+          "enum": ["5m", "1h"]
+        },
+        "headless": {
+          "description": "What Portulan's own runners apply to the sessions they start, and never compiled: the exclusion below is no host setting, only a flag or an SDK option, so only whatever starts a session can ask for it.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "git_instructions": {
+              "description": "`false` starts those sessions without the host's git instructions.",
+              "type": "boolean"
+            },
+            "cache_lifetime": {
+              "description": "Their prompt-cache lifetime.",
+              "type": "string",
+              "enum": ["5m", "1h"]
+            },
+            "exclude_dynamic_sections": {
+              "description": "`true` starts them with the per-machine sections (working directory, platform, memory paths, the git snapshot) moved from the system prompt into the first message, so runs in different directories or on different machines share the system prompt.",
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    },
+    "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.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "multipliers": {
+          "description": "What each class of input costs, as a multiple of an uncached input token. Both halves or neither: a threshold priced by one declared multiplier and one general one would be priced by nobody's figures.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["read", "write"],
+          "properties": {
+            "read": {
+              "description": "A cache read's cost as a multiple of an uncached input token. Above 0 and at most 1: the threshold divides by it, and a token read from cache never costs more than the same token sent uncached. The subset has neither `minimum` nor `maximum`, so `doctor` refuses a value outside that range.",
+              "type": "number"
+            },
+            "write": {
+              "description": "A cache write's cost as a multiple of an uncached input token, for each lifetime a write can be made at. Both lifetimes: the host records which one a session's writes used, and the threshold takes the write of the lifetime it recorded.",
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["5m", "1h"],
+              "properties": {
+                "5m": {
+                  "description": "A five-minute cache write's cost. At least 1: writing a token to the cache costs at least what sending it uncached does, and `doctor` refuses a smaller figure, since the subset has no `minimum`.",
+                  "type": "number"
+                },
+                "1h": {
+                  "description": "A one-hour cache write's cost. At least 1, on the same terms as `5m`.",
+                  "type": "number"
+                }
+              }
+            }
+          }
+        },
+        "horizon": {
+          "description": "How far ahead the threshold looks: the `n` of the arithmetic above.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["requests"],
+          "properties": {
+            "requests": {
+              "description": "The requests still to go at which the restart threshold is judged. Must be a POSITIVE INTEGER: the subset has no `minimum` and cannot say `integer`, so `doctor` refuses zero, negative and non-integer values.",
+              "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.",
+          "type": "string",
+          "enum": ["advise", "block"]
+        }
+      }
     }
   },