@kohala/devkit 0.1.0 → 0.1.1

package/docs/DEPLOY.md

@@ -0,0 +1,48 @@
+# Deploying to kohala.ai
+
+Everything in the devkit works without an account. Deploy is the one step
+that needs one — it pushes your locally-validated agent to the hosted
+platform, unchanged.
+
+## Login
+
+```bash
+kohala login          # paste your pk_ key from kohala.ai account settings
+```
+
+The key is stored at `~/.kohala/credentials.json` with permissions `600`.
+The `KOHALA_API_KEY` environment variable **always takes precedence** over
+the file — use it in CI.
+
+## Deploy
+
+```bash
+kohala deploy my-agent --dry-run   # print exactly what would be sent
+kohala deploy my-agent             # do it
+kohala deploy my-agent --run       # ...and trigger a manual hosted run
+kohala deploy my-agent --base-url https://staging.kohala.ai   # non-prod target
+```
+
+## What deploy does
+
+Deploy maps `kohala.json` onto the platform REST API, in order:
+
+1. `POST /api/v1/agents` — create or update the agent. **Idempotent on the
+   agent name**: deploying twice updates, never duplicates.
+2. `POST /api/v1/agents/:id/skills` — upload each skill script.
+3. `PUT /api/v1/agents/:id/quota` — set the token caps.
+4. (with `--run`) `POST /api/v1/agents/:id/agent-runs/manual` — trigger a
+   run and print its URL.
+
+Deploy is **additive only** — it never deletes agents, skills, or memory
+remotely. Removing a skill from kohala.json does not remove it from the
+platform; do that in the Kohala dashboard.
+
+## Errors you might see
+
+- **401 Unauthorized** — the key was rejected. Re-run `kohala login` with a
+  fresh `pk_` key, or check `KOHALA_API_KEY`.
+- **403 Forbidden** — your plan does not allow the operation. Check your
+  plan at kohala.ai.
+
+Both messages tell you this directly; nothing is retried silently.

package/docs/EMULATOR.md

@@ -0,0 +1,93 @@
+# How the emulator works
+
+`kohala run <agent> --local` executes one **shift** with the same enforcement
+order the hosted platform uses. Nothing is mocked, nothing is billed.
+
+## Enforcement order
+
+1. **Admission (per-day cap).** Before any work, the emulator sums today's
+   (UTC) token usage from `.kohala/usage/<agent>.json`. If it has already
+   reached `caps.perDayTokens`, the shift is refused with
+   `PER_DAY_TOKEN_CAP` — exactly like the platform's admission check.
+2. **Tool allowlist.** Every tool call — from a wrap-mode script over RPC or
+   from the llm-mode loop — is checked against `toolAllowlist`. Disallowed
+   calls fail with `TOOL_DENIED` and the denial is recorded in the trace.
+3. **Per-run cap.** Before each LLM turn (an `llm.complete` call in wrap
+   mode, or a loop turn in llm mode), the emulator projects the turn's token
+   cost. If the projection would cross `caps.perRunTokens`, the run aborts
+   with `PER_RUN_TOKEN_CAP` instead of crossing it.
+4. **Validators + repair loop.** After the output is produced, all
+   validators run. On failure, wrap mode re-runs the script with feedback,
+   at most **2** repair attempts (platform default), then the run is marked
+   `failed`.
+
+## Token accounting — counted, never billed
+
+Tokens are estimated at ~4 characters/token for projections; actual LLM
+usage comes from the provider's response. Totals are written to the trace
+(`tokens` events) and to the per-day ledger. **No money is involved
+locally, ever.** The caps exist so your agent behaves identically when
+deployed.
+
+## The script boundary (wrap mode)
+
+Skill scripts run as a separate Python process and talk to the emulator over
+a loopback HTTP RPC endpoint — the same boundary shape the platform uses.
+The emulator passes:
+
+| Env var | Meaning |
+| --- | --- |
+| `KOHALA_RPC_URL` | Loopback endpoint for tool calls (`skills/_tools.py` uses it) |
+| `KOHALA_AGENT` | Agent name |
+| `KOHALA_RUN_ID` | Unique shift id |
+| `KOHALA_REPAIR_ATTEMPT` | `0` first try, `1`–`2` on repair attempts |
+| `KOHALA_VALIDATOR_FEEDBACK` | Why validators failed last attempt |
+
+The script's **stdout is the run output**; stderr passes through to your
+terminal for debugging.
+
+## llm mode
+
+A real Anthropic tool-use loop with your own `ANTHROPIC_API_KEY`:
+
+- `charter` → system prompt
+- skill file contents → task context
+- allowlisted tools → tool definitions (the model can't even see others)
+- every tool invocation goes through the same dispatcher as wrap mode
+
+**`ANTHROPIC_API_KEY` is required for `runtimeMode: "llm"`.** The loop uses
+the Anthropic tool-use API. `GEMINI_API_KEY` enables `llm.complete` calls
+inside wrap-mode skill scripts, but not the llm-mode tool-use loop.
+
+If no Anthropic key is configured the run fails with a clear error message.
+There is no mock fallback by design.
+
+`kohala doctor` reports both cases separately so you can see exactly which
+features your current environment supports.
+
+## Models
+
+The emulator defaults to the same models the hosted platform runs:
+
+| Provider | Default model | Override env var |
+| --- | --- | --- |
+| Anthropic | `claude-sonnet-4-6` | `ANTHROPIC_MODEL` |
+| Gemini | `gemini-flash-latest` | `GEMINI_MODEL` |
+
+Both can be overridden with `KOHALA_LLM_MODEL` (takes precedence over the
+provider-specific vars). Example:
+
+```bash
+ANTHROPIC_MODEL=claude-3-5-haiku-latest kohala run my-agent --local
+```
+
+Because caps are token-based and consumption varies by model, keeping the
+local default in sync with the hosted platform means your cap tuning carries
+over when you deploy.
+
+## The trace
+
+Every shift appends JSONL events to `.kohala/trace/<agent>.jsonl`:
+`run_started`, `tool_call` (with allow/deny and duration), `tokens`,
+`validator_result`, `repair_attempt`, `run_finished`. Inspect with
+`kohala trace <agent>` (`--follow`, `--json`).

package/docs/MANIFEST.md

@@ -0,0 +1,84 @@
+# Manifest reference — kohala.json
+
+`kohala.json` is the agent's single source of truth, and it maps 1:1 onto
+platform fields. Deploying never re-interprets it — what you validate locally
+is what goes live.
+
+## Full example
+
+```json
+{
+  "name": "weather-logger",
+  "charter": "Fetch current weather once per shift and store it in memory.",
+  "toolAllowlist": ["s3.put", "s3.get", "s3.list", "http.post_json"],
+  "runtimeMode": "wrap",
+  "skills": { "collect": "main.py" },
+  "schedule": "0 * * * *",
+  "caps": {
+    "perRunTokens": 10000,
+    "perDayTokens": 50000,
+    "billingTokens": 1000000,
+    "billingPeriod": "month"
+  },
+  "validators": [
+    { "type": "shape", "minBytes": 20 },
+    { "type": "freshness", "asset": "weather/latest", "maxAgeHours": 2 },
+    { "type": "invariant", "pattern": "temperature", "mustMatch": true }
+  ]
+}
+```
+
+## Fields
+
+| Field | Platform field | Meaning |
+| --- | --- | --- |
+| `name` | agent name | Identity. Deploy is idempotent on it. Letters, digits, `-`, `_`. |
+| `charter` | `agentCharter` | The agent's mission. In llm mode this is the system prompt. |
+| `toolAllowlist` | `agentToolAllowlist` | Exactly the tools the agent may call. No implicit grants. |
+| `runtimeMode` | `agentRuntimeMode` | `"wrap"` or `"llm"` (see below). |
+| `skills` | `agentSkills` | Map of skill name → script filename in `skills/`. |
+| `schedule` | `agentScheduleCron` | Cron expression. Only used on deploy; local runs are manual. |
+| `caps.perRunTokens` | `agentPerRunTokenCap` | Hard token ceiling per shift. |
+| `caps.perDayTokens` | `agentPerDayTokenCap` | Cumulative ceiling per UTC day. |
+| `caps.billingTokens` | `agentBillingCapTokens` | Billing-period cap. Ignored locally. |
+| `caps.billingPeriod` | `agentBillingCapPeriod` | `"day"`, `"week"`, or `"month"`. Required with `billingTokens`. |
+| `validators` | agent validators | Output checks (below). |
+
+## Runtime modes
+
+- **`wrap`** — the emulator executes the skill script directly (Python 3).
+  The script's **stdout is the run output** that validators evaluate; stderr
+  is for your debug logging. The script uses `skills/_tools.py` to call
+  tools over the loopback RPC boundary.
+- **`llm`** — a real tool-use loop against your own `ANTHROPIC_API_KEY`. The
+  charter is the system prompt, the skill file's contents are the task
+  context, and allowlisted tools are exposed to the model. The final text
+  reply is the run output.
+
+## Tools
+
+`s3.put`, `s3.get`, `s3.list`, `s3.delete`, `http.post_json`,
+`llm.complete`, `notify.send`, `metrics.record` — identical names and
+semantics locally and hosted. Locally, `notify.send` and `metrics.record`
+land in the trace instead of sending anything.
+
+## Validators
+
+- `{"type": "shape", "minBytes": n}` — output must exist and be ≥ n bytes.
+- `{"type": "freshness", "asset": "key", "maxAgeHours": h}` — the memory
+  asset at `key` must have been updated within the last `h` hours.
+- `{"type": "invariant", "pattern": "regex", "mustMatch": true|false}` —
+  output must match (or must not match) the regex.
+
+On failure, wrap mode re-runs the script up to **2** more times with
+`KOHALA_REPAIR_ATTEMPT` and `KOHALA_VALIDATOR_FEEDBACK` set — the platform's
+bounded repair loop.
+
+## Validation errors
+
+`kohala validate <agent>` prints every problem with a fix hint, e.g.:
+
+```
+kohala.json failed validation
+  • caps.perRunTokens: Expected number, received string (hint: set caps.perRunTokens and caps.perDayTokens as positive integers)
+```

package/docs/MEMORY.md

@@ -0,0 +1,81 @@
+# Memory & the MCP server
+
+Agent memory locally has the same surface as the hosted platform:
+
+- `s3.put(key, body, category?)` — store under a logical key. Category
+  defaults to `"agentoutput"` (run results).
+- `s3.get(keyOrId)` — resolve by active logical key first, then record id.
+- `s3.list(prefix?, limit?)` — active assets, newest first.
+- `s3.delete(keyOrId)` — remove the body + deactivate the index entry
+  (soft delete).
+
+Logical keys are unique among active assets: putting to an existing key
+updates it in place.
+
+## Backends
+
+### file (default)
+
+```
+.kohala/memory/<agent>/
+├── index.json     # asset index: key, category, timestamps, active flag
+└── bodies/<id>    # raw body bytes, one file per asset
+```
+
+The index is rewritten atomically (temp file + rename) on every mutation.
+
+### postgres
+
+```bash
+kohala memory serve --backend postgres --url postgres://...   # or DATABASE_URL
+kohala run my-agent --local --backend postgres
+```
+
+One table, `kohala_memory`, created automatically on first connect. Bodies
+are stored as `bytea` in the same row — a deliberate design decision so any
+plain Postgres URL works with no filesystem coupling. Requires the optional
+`pg` package (`npm install pg`).
+
+## The MCP server
+
+`kohala memory serve` exposes memory over the
+[Model Context Protocol](https://modelcontextprotocol.io) so any MCP client
+(Claude Desktop, MCP Inspector, your own tools) can read and write agent
+memory with the platform's exact tool names.
+
+The command must know which agent's memory to scope to. Pass `--agent
+<name>` explicitly, **or** run it from inside an agent directory (one that
+contains `kohala.json`) and it will read the agent name automatically:
+
+```bash
+# Option 1: explicit agent name — run from anywhere
+kohala memory serve --agent my-agent
+
+# Option 2: run from inside the agent directory
+cd my-agent
+kohala memory serve          # reads agent name from ./kohala.json
+
+# Streamable HTTP — for MCP Inspector etc.
+kohala memory serve --agent my-agent --http --port 8787
+# endpoint: http://127.0.0.1:8787/mcp
+```
+
+Tools: `s3.put`, `s3.get`, `s3.list`, `s3.delete`.
+Resource: `memory://index` — a JSON listing of all active assets.
+
+Claude Desktop config example:
+
+```json
+{
+  "mcpServers": {
+    "kohala-memory": {
+      "command": "kohala",
+      "args": ["memory", "serve", "--agent", "my-agent"]
+    }
+  }
+}
+```
+
+Run it from the directory that contains your `.kohala/` folder (or from
+inside the agent directory — the server resolves the agent name from
+kohala.json and uses the parent directory as the workspace root).

package/docs/QUICKSTART.md

@@ -0,0 +1,70 @@
+# Quickstart
+
+From zero to a running agent in under five minutes. No account needed.
+
+## Install
+
+```bash
+npm install -g @kohala/devkit
+kohala --version
+kohala doctor        # checks Node, Python, keys
+```
+
+Requirements: Node.js ≥ 20 and Python 3 on your PATH.
+
+## Create an agent
+
+```bash
+kohala init my-agent
+```
+
+This scaffolds:
+
+```
+my-agent/
+├── kohala.json        # manifest: charter, tools, caps, validators
+├── README.md
+└── skills/
+    ├── main.py        # the skill — its stdout is the run output
+    └── _tools.py      # the local tool SDK (stdlib-only, don't edit)
+```
+
+## Run it
+
+```bash
+kohala validate my-agent
+kohala run my-agent --local
+```
+
+You'll see the run status, token count, validator results, and the output.
+The emulator enforces the platform's exact rules — per-day admission, tool
+allowlist, per-run token caps, validators with a bounded repair loop — but
+**never bills anything**.
+
+## Inspect the audit trail
+
+```bash
+kohala trace my-agent            # pretty view
+kohala trace my-agent --follow   # tail it live
+kohala trace my-agent --json     # raw JSONL
+```
+
+Every tool call, token increment, validator result, and repair attempt is in
+there.
+
+## Iterate
+
+Edit `my-agent/skills/main.py` and `my-agent/kohala.json`, then run again.
+Try removing a tool from `toolAllowlist` and watch the call fail loudly with
+`TOOL_DENIED` — that is exactly what the platform would do.
+
+## Go live (optional)
+
+```bash
+kohala login                    # paste your pk_ key from kohala.ai
+kohala deploy my-agent --dry-run    # see exactly what would be sent
+kohala deploy my-agent --run        # deploy + trigger a hosted run
+```
+
+Next: [Manifest reference](MANIFEST.md) · [How the emulator works](EMULATOR.md)
+· [Memory & MCP](MEMORY.md) · [Deploying](DEPLOY.md)

package/examples/llm-notes/README.md

@@ -0,0 +1,18 @@
+# llm-notes example
+
+`runtimeMode: "llm"` — a real tool-use loop against your own
+`ANTHROPIC_API_KEY`. The charter is the system prompt, `skills/task.md` is
+the task context, and the allowlisted tools (`s3.put`, `s3.get`, `s3.list`,
+`notify.send`) are exposed to the model. Every tool call the model makes goes
+through the same allowlist + trace + token accounting as wrap mode.
+
+Before each turn the emulator projects the request's token cost against
+`caps.perRunTokens` and aborts with `PER_RUN_TOKEN_CAP` rather than crossing
+it.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+cd examples
+kohala run llm-notes --local
+kohala trace llm-notes
+```

package/examples/llm-notes/kohala.json

@@ -0,0 +1,16 @@
+{
+  "name": "llm-notes",
+  "charter": "You are a note-keeping agent. Each shift, review the notes already in memory (s3.list, s3.get), write one new short observation about what you find under notes/<n>, and finish with a one-line summary.",
+  "toolAllowlist": ["s3.put", "s3.get", "s3.list", "notify.send"],
+  "runtimeMode": "llm",
+  "skills": {
+    "observe": "task.md"
+  },
+  "caps": {
+    "perRunTokens": 30000,
+    "perDayTokens": 120000
+  },
+  "validators": [
+    { "type": "shape", "minBytes": 10 }
+  ]
+}

package/examples/llm-notes/skills/task.md

@@ -0,0 +1,7 @@
+# Task
+
+1. List what is currently stored under the `notes/` prefix.
+2. Store one new note at `notes/<next-number>` — a single short sentence
+   observing something about the existing notes (or, if there are none, a
+   first observation about starting fresh).
+3. Reply with a one-line summary of what you stored.

package/examples/rss-digest/README.md

@@ -0,0 +1,13 @@
+# rss-digest example
+
+Wrap-mode agent that fetches Hacker News front-page headlines and summarizes
+them with `llm.complete` — using **your own** `ANTHROPIC_API_KEY` (or
+`GEMINI_API_KEY`). Without a key the run fails loudly with `NO_LLM_KEY`;
+there is no mock fallback.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+cd examples
+kohala run rss-digest --local
+kohala trace rss-digest     # note the `tokens` events — counted, never billed
+```

package/examples/rss-digest/kohala.json

@@ -0,0 +1,17 @@
+{
+  "name": "rss-digest",
+  "charter": "Summarize the newest items from a feed into a short digest and store it under digest/latest.",
+  "toolAllowlist": ["s3.put", "s3.get", "llm.complete", "notify.send"],
+  "runtimeMode": "wrap",
+  "skills": {
+    "digest": "main.py"
+  },
+  "caps": {
+    "perRunTokens": 20000,
+    "perDayTokens": 80000
+  },
+  "validators": [
+    { "type": "shape", "minBytes": 40 },
+    { "type": "freshness", "asset": "digest/latest", "maxAgeHours": 25 }
+  ]
+}

package/examples/rss-digest/skills/_tools.py

@@ -0,0 +1,125 @@
+"""Kohala tool SDK (local twin).
+
+Your skill script talks to the Kohala runtime through these helpers. Locally
+they call the emulator over a loopback RPC endpoint; on the hosted platform
+the same functions talk to the real runtime. Your script does not change.
+
+Uses only the Python standard library — no pip installs needed.
+
+Available tools (each must also be listed in kohala.json -> toolAllowlist):
+
+    s3_put(key, body, category=None)   store text in agent memory
+    s3_get(key_or_id)                  fetch a memory asset
+    s3_list(prefix=None, limit=None)   list active memory assets
+    s3_delete(key_or_id)               remove + deactivate an asset
+    http_post_json(url, body, headers=None)  POST JSON to an external API
+    llm_complete(prompt, model=None)   complete text with YOUR OWN LLM key
+    notify_send(channel, message)      send a notification (trace, locally)
+    metrics_record(name, value, tags=None)   record a metric (trace, locally)
+
+Every helper raises KohalaToolError on failure — including TOOL_DENIED when
+the tool is not in your allowlist, and PER_RUN_TOKEN_CAP when an LLM call
+would cross your per-run token cap. Errors are loud on purpose.
+"""
+
+import json
+import os
+import urllib.request
+
+
+class KohalaToolError(Exception):
+    """A tool call failed. `code` is the platform's machine-readable code."""
+
+    def __init__(self, code, message):
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+
+
+def _rpc(tool, args):
+    rpc_url = os.environ.get("KOHALA_RPC_URL")
+    if not rpc_url:
+        raise KohalaToolError(
+            "NO_RUNTIME",
+            "KOHALA_RPC_URL is not set. Run this script via `kohala run <agent> --local`, "
+            "not directly with python.",
+        )
+    payload = json.dumps({"tool": tool, "args": args}).encode("utf-8")
+    request = urllib.request.Request(
+        rpc_url,
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(request) as response:
+        body = json.loads(response.read().decode("utf-8"))
+    if not body.get("ok"):
+        error = body.get("error") or {}
+        raise KohalaToolError(error.get("code", "UNKNOWN"), error.get("message", "tool call failed"))
+    return body.get("result")
+
+
+def s3_put(key, body, category=None):
+    args = {"key": key, "body": body}
+    if category is not None:
+        args["category"] = category
+    return _rpc("s3.put", args)
+
+
+def s3_get(key_or_id):
+    return _rpc("s3.get", {"keyOrId": key_or_id})
+
+
+def s3_list(prefix=None, limit=None):
+    args = {}
+    if prefix is not None:
+        args["prefix"] = prefix
+    if limit is not None:
+        args["limit"] = limit
+    return _rpc("s3.list", args)
+
+
+def s3_delete(key_or_id):
+    return _rpc("s3.delete", {"keyOrId": key_or_id})
+
+
+def http_post_json(url, body, headers=None):
+    args = {"url": url, "body": body}
+    if headers is not None:
+        args["headers"] = headers
+    return _rpc("http.post_json", args)
+
+
+def llm_complete(prompt, model=None):
+    args = {"prompt": prompt}
+    if model is not None:
+        args["model"] = model
+    return _rpc("llm.complete", args)
+
+
+def notify_send(channel, message):
+    return _rpc("notify.send", {"channel": channel, "message": message})
+
+
+def metrics_record(name, value, tags=None):
+    args = {"name": name, "value": value}
+    if tags is not None:
+        args["tags"] = tags
+    return _rpc("metrics.record", args)
+
+
+def run_context():
+    """Info about the current shift, including repair-loop state.
+
+    Returns a dict with:
+      agent            the agent name
+      run_id           unique id of this shift
+      repair_attempt   0 on the first try, 1..2 on repair attempts
+      validator_feedback  why validators failed last attempt (empty on first try)
+    """
+    return {
+        "agent": os.environ.get("KOHALA_AGENT", ""),
+        "run_id": os.environ.get("KOHALA_RUN_ID", ""),
+        "repair_attempt": int(os.environ.get("KOHALA_REPAIR_ATTEMPT", "0")),
+        "validator_feedback": os.environ.get("KOHALA_VALIDATOR_FEEDBACK", ""),
+    }

package/examples/rss-digest/skills/main.py

@@ -0,0 +1,49 @@
+"""rss-digest — summarize headlines with YOUR OWN LLM key.
+
+Demonstrates: llm.complete (requires ANTHROPIC_API_KEY or GEMINI_API_KEY in
+your environment — the devkit never mocks completions), plus the per-run
+token cap: if the call would cross caps.perRunTokens it fails loudly with
+PER_RUN_TOKEN_CAP.
+"""
+
+import sys
+import urllib.request
+import xml.etree.ElementTree as ET
+
+from _tools import s3_put, llm_complete, notify_send, KohalaToolError
+
+FEED_URL = "https://hnrss.org/frontpage"
+
+
+def fetch_titles(limit=8):
+    with urllib.request.urlopen(FEED_URL, timeout=30) as response:
+        tree = ET.parse(response)
+    titles = [item.findtext("title") or "" for item in tree.iter("item")]
+    return [title for title in titles if title][:limit]
+
+
+def main():
+    titles = fetch_titles()
+    if not titles:
+        print("feed returned no items", file=sys.stderr)
+        raise SystemExit(1)
+
+    prompt = (
+        "Summarize these headlines into a 3-sentence digest for a busy reader:\n- "
+        + "\n- ".join(titles)
+    )
+    try:
+        completion = llm_complete(prompt)
+    except KohalaToolError as error:
+        # NO_LLM_KEY or PER_RUN_TOKEN_CAP — both are loud by design.
+        print(f"llm.complete failed: {error}", file=sys.stderr)
+        raise SystemExit(1)
+
+    digest = completion["text"].strip()
+    s3_put("digest/latest", digest)
+    notify_send("dev", "digest updated")
+    print(digest)
+
+
+if __name__ == "__main__":
+    main()

package/examples/weather-logger/README.md

@@ -0,0 +1,12 @@
+# weather-logger example
+
+Wrap-mode agent that fetches current weather from Open-Meteo (no API key
+needed) and stores it in memory. Shows `http.post_json`, `s3.put`, a
+`freshness` validator, and an `invariant` validator.
+
+```bash
+cd examples
+kohala validate weather-logger
+kohala run weather-logger --local
+kohala trace weather-logger
+```

package/examples/weather-logger/kohala.json

@@ -0,0 +1,19 @@
+{
+  "name": "weather-logger",
+  "charter": "Fetch current weather conditions once per shift and store them in memory under weather/latest.",
+  "toolAllowlist": ["s3.put", "s3.get", "s3.list", "http.post_json", "metrics.record"],
+  "runtimeMode": "wrap",
+  "skills": {
+    "collect": "main.py"
+  },
+  "schedule": "0 * * * *",
+  "caps": {
+    "perRunTokens": 10000,
+    "perDayTokens": 50000
+  },
+  "validators": [
+    { "type": "shape", "minBytes": 20 },
+    { "type": "freshness", "asset": "weather/latest", "maxAgeHours": 2 },
+    { "type": "invariant", "pattern": "temperature", "mustMatch": true }
+  ]
+}