Agent docs

Contract changelog

What changed in the contract and when.

One line per bump of contract_version, and the notable canon changes between bumps. contract_version is what a module's manifest declares and a caller pins (canon/11); it changes only when a required route or shape changes.

Between 0.1 and the next bump#

  • 2026-08-19: the app and its GCP project are renamed from app-forge-v6 to versable-forge-v6 on the owner's word, the version marker kept for team reasons. D1's ruling stands and only the string changed; the D1 row and M7 in plans/v6-decision-set.md are annotated rather than rewritten, and this file's earlier entries keep the old name because they record what was true when written. Nothing inside the project is renamed: the forge resource prefix (service account, queue, Artifact Registry repo, Cloud SQL instance and database, VPC connector) is the product family per D10 and is deliberately not the project id. No contract shape changed, so contract_version does not move.

  • 2026-08-18 (late): owner ruling via the builder lane, "the contract stays wide": params, item, output are full draft 2020-12; the kit's lintSchema is guidance for a generated form, not a manifest gate (contracts/manifest.md § Validation, canon/11); foundry-2 becomes an advisory conformance row. Two vocabulary-independent rules added: no required field hidden by a form-only condition outside a discriminated branch, and $settings.<key> in x-when names only listed settings. The console is built in its own repo app-forge-v6 (D1 stands), kit-linked locally until the token lands.

  • 2026-08-18 (night): tree-wide adversarial review v2 folded (three opus seats, 44 findings, dispositions in ../.claude/output/20260818-contract-finish/). Shape changes inside 0.1: variants is an object on the create body, outcome and usage event; envelope code is a closed set; /manifest has an ETag; /review?group_by=reason; internal route POST /internal/tasks/{unit}; usage_ref is an array of event ids; outcome fields variant, reference_versions, judged_by named as conditional; local verifier context fixed; remote verifier everywhere; credential refusals 401, tenant and scope 403; six capability fields optional at 0.1 and required from 0.2 (J4); reserved codes; standard settings; co-hosting stated in canon/14 and adr/001; V1 carve-out in patterns/00; every canon doc opens with an Evidence marker; conformance section H (six n/r rows) by hands.

  • 2026-08-18 (evening): contracts/manifest.md second pass, folded from the opus review at ../.claude/output/20260818-contract-finish/manifest-review.md (20 findings, dispositions at its end). Shape changes, all inside 0.1 since nothing ships against it: a registry id IS its path (items[].input.<id> in, output.<id> out); requirement from names caller, <module>/<capability> or a bare capability; on_missing forms pinned; surface, identity, runtime given member grammar (identity.verifier gains remote; surface.routes entries are <METHOD> <path>); outputs.<name>.version required; cache.tenant_scoped required; deprecations entries are {kind, target, ...}; top-level states and ceilings.max_deferrals optional; retention keys pinned and duration = 7d/1y/never/ttl; cost_model.meters lists own meters only; standard settings table; skip reasons closed; registry gains part.gtin, part.category, attributes.destination, drops review.reason, growth rule and x. prefix. Every type cell now machine-read (scripts/build-manifest-schema.py), the job-id placeholder is {job_id} tree-wide, and guides/03 has contender F (central key service over HTTP) from the services-api scan.

  • 2026-08-18: V6 decisions ruled by the owner (plans/v6-decision-set.md, Rulings table): separate repos, app app-forge-v6; Cloud Run for the console; Next 16 held per ADR-001; qsync kept for V1; the vocabulary tagged as working names with forge (product app) and foundry (versable-builder plus this tree) added at the estate level (01-system-classes.md Names, 00-charter.md Terms). No route or shape changed; contract_version stays 0.1. instances/extraction.md corrected from a live read: the extractor worker runs minScale 10, not 1.

0.1, 2026-08-18#

First complete draft. Canon 00 to 15, contracts (module-surface, manifest, usage-event, runner-verbs, caller-keys, conformance), patterns 00 to 04, guides 00 to 03, adr 001 to 006, five instances, v6 mapping, working vocabulary. Reviewed tree-wide (31 findings, dispositions in evidence/20260817-adversarial-review.md) and the class model separately (29 findings). Not yet built against by any module.

Route and shape decisions taken during the review pass, all inside 0.1 because nothing has shipped against it: items[].payload is items[].input; /jobs/{id}/manifest is /jobs/{id}/envelope; the prose guide route is /guide (/usage may alias it for one release); /jobs/{id}/outcomes/{item_id}/log and /usage/events are on the surface contract; variants take the {dimension: {options, default}} shape; batching is a run_batch entry point, not a capability id; GET /jobs returns a list envelope with facets and updated_at and is a reconciliation surface, never a browsed list; outcomes filter by reason, error_type, item_id; codes carry {label, description}; attribution.user is {id, label}; child jobs may be created from a parent's item subset (vb-fable shape check, 2026-08-18); /build-info is {commit, built_at, branch?, name, version, contract_version} for modules and apps alike (settled with vb-fable, 2026-08-18).

@versable-git/ui · reference, canon, and method, read in place