wowbagger 0.1.0-alpha.7 → 0.1.0-alpha.9

package/CHANGELOG.md

@@ -7,6 +7,180 @@ consolidation. The first tagged release inherits this file.
 
 ## Unreleased
 
+## 0.1.0-alpha.9 - 2026-08-23
+
+### Added
+
+- **A public Wowbagger brand asset.** The repository now carries an optimized
+  1024px image of Bowerick Wowbagger directing robotic agent cats at consoles
+  with a circuit-lit shepherd's staff. The asset is included in the npm
+  package for README and GitHub presentation.
+
+### Changed
+
+- **Public product prose now describes the current engine.** README, npm
+  metadata, Claude plugin metadata, marketplace metadata, and the installed
+  skill now explain report sequencing dashboards, named views, facets, graph
+  filtering, guarded CAS mutations, claims, fencing, reconciliation, and the
+  separation between core and host responsibilities.
+- **Agent onboarding is explicit.** The README and skill include a concise
+  agent TL;DR, exact core setup checks, the separate plugin/skills installer
+  routes, and the response-loss rule.
+
+## 0.1.0-alpha.8 - 2026-08-23
+
+### Added
+
+- **A published launch seam for a host that cannot run a shell.** The package
+  now declares `exports`, and its main entry `wowbagger` exposes
+  `CORE_SCRIPT_PATH`, `MINIMUM_NODE_MAJOR`, and `resolveCoreLaunch(argv)`, which
+  returns the exact process tuple a direct-core host needs: an absolute Node
+  executable, an argument array whose first element is the absolute
+  `bin/wowbagger.js`, and `shell: false`. A host that resolves its own runtime
+  gets `resolveCoreLaunch(argv, { nodeExecutable })`, and a relative or bare
+  executable name is refused rather than left for PATH to answer. The script
+  path is also resolvable on its own as `wowbagger/wowbagger.js` for a host that
+  wants the path without importing anything. Deep imports that already worked —
+  `wowbagger/src/limits.js` and every other published path — keep resolving
+  through an explicit `"./*"` subpath. No command accepts, refuses, emits, or
+  writes anything different.
+
+- **The machine contract ships as JSON Schema, not only as prose and fixtures.**
+  Seventeen JSON Schema 2020-12 documents under `schemas/` are published with
+  the package and resolvable as `wowbagger/schemas/<file>.json`, with
+  `schemas/index.json` naming each one's response domain and that domain's
+  version. They cover the core envelope and its four exact root shapes, the
+  capabilities envelope with every advertised limit as a constant, the two bare
+  results, the list query and its page and refusals, the default and workbench
+  inspect projections, the transition request, success, and every documented
+  refusal with its mutation state, the `ledger-mutation` fence refusals, report
+  configuration versions 1 and 2, and the report responses including a named
+  view. Every schema fixes its root members exactly and pins the version of its
+  own domain, so a core envelope refuses a namespaced refusal, a version 4
+  envelope, or an extra root member, and a version 1 report configuration
+  refuses a version 2 one. Exactness reaches the members too: an item core must
+  carry both relation lists, because the core view always emits them, and a
+  refusal raised before a commit is established pins its state to `unchanged`
+  rather than admitting the indeterminate state that only an interrupted write
+  can report. The validator is a test-only dependency; the runtime still has
+  exactly one dependency.
+
+### Documentation
+
+- **`docs/host-contract.md` publishes the direct-core host boundary.** One
+  document now states what a UI plugin or other non-agent consumer needs and
+  what it must supply itself: the package resolution seam and the four-part
+  launch — Node.js 20 or later, an absolute Node executable, the absolute
+  `wowbagger.js`, an argument array, and `shell: false`; bounded stdin or a
+  host-created request file, never shell source and never inline unbounded argv
+  JSON; captured stdout and stderr; the owning-host path rule for a worktree, a
+  plain folder, direct SSH, and WSL, with no cross-runtime path guessing;
+  namespace-first response dispatch and the exit table; every advertised limit
+  with its exact value; the once-only dispatch sequence for a lost response; and
+  the seventeen packaged JSON Schemas by domain. It states that a missing
+  executable is a host-level result rather than malformed Wowbagger JSON, that
+  the host owns executable discovery, working directory, timeout, cancellation,
+  process-tree containment, stream caps, and routing, and that Wowbagger will
+  not add automatic transitions, mirrored ledger state, operation identity,
+  remote routing, or a daemon. The full `inspect` read is documented as
+  deliberately unbounded, with the reason. The README, the installed skill, and
+  `SPEC.md` section 10 point at it, and it ships in the npm package.
+- **The public version and lifecycle vocabulary agrees with the runtime.**
+  `SPEC.md` section 10 said core mutation contracts 1 and 2 were defined and
+  that the runtime emitted version 2; it now says 1 through 5 and version 5. The
+  mutation contract's status line said versions 1, 2, and 3 with the runtime on
+  3; it now says 1 through 5 and version 5. `deferred` has been a real status
+  since it shipped, but `SPEC.md` omitted it from the status field, the
+  lifecycle table, the transition table, the terminal-date invariants, the
+  decision-action list, and the terminal-decision table, and the mutation
+  contract omitted the `deferred` date from the lossless core view; all seven
+  now name it, along with the `resolve`, `defer`, and `undefer` decision actions
+  the validator has always accepted. No behaviour changed: these were prose
+  omissions, and the tests that guard them read the vocabularies from
+  `src/lifecycle.js` and `src/validate.js` rather than retyping them.
+- **Response loss is a named contract instead of folklore.** The mutation
+  contract, the adapter contract, the README, and the installed skill now carry
+  the same sequence for a mutation whose response never arrived: dispatch once,
+  never replay, invalidate the inspected revision, reconnect, then re-read the
+  ledger. The mutation contract's new section 10 table separates the outcomes a
+  caller may act on — committed success, proven non-write, committed recovery,
+  unknown publication — from the two that establish nothing, a signalled or
+  timed-out transport and a missing envelope, and states that a later item state
+  never proves that the lost dispatch caused it. Adapter contract section 6.2
+  documents the `mutation_outcome: "unknown"` envelope and its per-command
+  `recovery` object exactly as the adapter emits them, and states that exit 4
+  `revision-conflict` is a proven non-write that is never relabelled response
+  loss. There is no operation ID, durable outcome store, or replay endpoint;
+  adding correlation requires a new contract decision. No command accepts,
+  refuses, emits, or writes anything different. Two conformance vectors now pin
+  the core's own exit-6 `write-outcome-unknown` and `post-commit-recovery-required`
+  envelopes at the adapter's process-outcome seam, taking the adapter vector set
+  to 212 assertions.
+- **The exit tables state where `report` actually lands.** Both contracts filed
+  exit 1 as a bare-result-only condition and exit 3 as every invalid ledger,
+  while `report` answers an invalid ledger, an unreadable input, and a failed
+  publication at exit 1. The mutation contract now carries an exit 1 row naming
+  those codes, lists `report-config-invalid` and `report-view-not-found` in its
+  exit 2 row, and scopes exit 3 to every command except `report`; the host
+  contract's exit 1 and exit 3 conditions say the same. Two guards assert the
+  rows against the codes the runtime emits.
+
+### Changed
+
+- **The report filters by facet groups instead of one value at a time.** The
+  drill-down's single-value mapped-field selects and its All/Ready/Blocked/
+  Ineligible buttons are gone. In their place is one group of checkbox chips per
+  dimension of the open set — Readiness, Status, Kind, and every configured
+  mapped field, so a mapped `class: bug` is a chip rather than a value hidden in
+  a dropdown. Values inside a group are alternatives, groups narrow each other,
+  and the search box is one more condition; every chip states the count it would
+  leave, measured against the search and the other groups but never against its
+  own, so two selections in one group cannot make their siblings read zero. A
+  visible result count, per-chip selected state, and `Clear filters` are new, and
+  opening a Work next or Attention row still clears whatever detached its card,
+  facets included.
+- **The ledger graph filters by lifecycle status.** One chip group above the
+  stage carries the statuses the ledger holds, all selected, with `Select all`
+  and `Clear`. Deselecting a status drops its nodes, every link incident to one,
+  and their labels, reheats the layout in place, and takes a hidden node off the
+  hover card; the roster and node count follow the same selection, and an empty
+  selection draws an empty graph that says so. The legend, the WebGL-less
+  roster, camera interaction, and the no-fetch contract are unchanged, and
+  nothing here reads or writes the ledger.
+
+### Fixed
+
+- **A report failure before publication says so, and never arrives causeless.**
+  An output path the filesystem cannot resolve — a `--out` under a regular
+  file, an unreadable directory on the way to it — was a raw runtime error
+  escaping into the command's catch-all, answered as `report-write-failed` with
+  empty `details` even though nothing had been rendered or replaced. It is now
+  `report-read-failed` with `details.operation` naming which resolution failed,
+  `details.path` naming the path the caller configured or passed, and
+  `details.cause` naming the filesystem's own code. An error no report path
+  throws on purpose still answers `report-write-failed`, because nothing
+  reached the output path, but it now carries `{operation, cause}` instead of
+  `{}`. Every `details.cause` is a bounded token — an error code, or the
+  error's kind when the runtime gave no code — so a publication failure no
+  longer republishes a runtime message, and the paths, credentials, and
+  run-specific values a message carries stay out of the envelope. Atomic
+  publication is unchanged: a report already at the selected path survives
+  every one of these refusals.
+- **An empty named view stops blaming the reader.** A view whose criteria
+  matched nothing rendered the drill-down's `No items match these filters.` and
+  the graph's `No status is selected`, sending a reader to controls that could
+  not bring an item back. A named artifact with no items now states
+  `No ledger item matches this view's criteria.` and, in the graph, that it has
+  nothing to draw — visibly, without waiting for scripting. A report that holds
+  items keeps the filter and status copy, which is the honest answer when the
+  reader is the one who narrowed it, and the base report's bytes are unchanged.
+- **`core-report-response.json` named a member the report never emitted.** The
+  published `ledger-invalid` refusal required `details.validation_errors`,
+  which is the mutation commands' member name; `report` has always emitted
+  `details.errors`. A consumer validating a real refusal against the shipped
+  schema failed on the runtime's own bytes. The schema now states `errors`, and
+  a live invalid-ledger report run is validated against it.
+
 ## 0.1.0-alpha.7 - 2026-08-18
 
 ### Changed
@@ -157,6 +331,44 @@ consolidation. The first tagged release inherits this file.
 
 ### Added
 
+- **`inspect` answers a bounded per-item lifecycle affordance projection.**
+  `inspect --ledger <dir> (--id <id> | --number <n>) --workbench --as-of
+  YYYY-MM-DD --json` returns, from one complete validated ledger snapshot,
+  `result.workbench`: the projection version, the as-of date, the ledger
+  snapshot witness, an `observation` member, a bounded item summary, and one
+  `transition_options` entry for every lifecycle target the native edge table
+  allows out of that item's kind and status. Each option names its target
+  status, its generated decision action or `null`, whether a caller-supplied
+  summary and rationale are required, the minimum legal transition date
+  `max(created, updated)`, its observed enabled state, and the observed
+  precondition issues and multi-item blockers in the exact `transition`
+  vocabulary. A workbench can now show a person which transitions an item can
+  take without duplicating lifecycle logic and without submitting a mutating
+  probe.
+
+  The read is an observation, not a lease, and says so in the response:
+  `observation.authority` is `observed-snapshot` and `observation.rechecked_by`
+  names what a later `transition` rechecks under lock — revision, lock, claim
+  fence, reconciliation, and candidate validation. It writes no item, lock,
+  claim journal, reconciliation log, or Git state, and it takes no lock.
+  `transition` and the projection share one lifecycle definition
+  (`src/lifecycle.js`), and a differential guard dispatches every projected
+  option and every unadvertised target through the real mutation, so an
+  advertised affordance cannot drift from what the mutation does.
+
+  Every variable-size field is bounded and says what it left out: the projected
+  title, the relation lists, each option's issues and blockers, and the related
+  IDs inside an issue. `--workbench` requires `--as-of`, an unpaired `--as-of`
+  is refused rather than ignored, and an `inspect` invocation without
+  `--workbench` is byte-identical to before. `capabilities` advertises
+  `operations.inspect.workbench` and the three exact bounds
+  `max_workbench_title_characters`, `max_workbench_collection_entries`, and
+  `max_workbench_response_bytes`; the core contract version stays 5, and the
+  projection is negotiated by its own `projection_version`. An invalid ledger is
+  `ledger-invalid` at exit 3 with no projection attached, and a projection that
+  would exceed its response bound is refused whole with
+  `workbench-response-too-large` at exit 2.
+
 - **The conformance suite now measures real core outcomes end to end.** A new
   equivalence case, `16-core-outcome-e2e`, carries nine hand-authored scenarios
   that each run the direct real core in one isolated temporary workspace and,
@@ -570,7 +782,7 @@ consolidation. The first tagged release inherits this file.
   every read and every guarded mutation on that ledger, including ones that
   never touch the misplaced item, so the refusal has to say where the item
   belongs. The claim fence is not involved: `claim-verify` reports no finding
-  on such a ledger, refuting the PropertyCompass2 PR #2184 claim that a
+  on such a ledger, refuting an earlier consumer report that a
   root-misplaced item makes the fence report `stale-write-detected` with
   `actual_revision: null`. Fixtures pin both configuration orders — layout
   bound first, and layout bound after the item was already committed at the