From 7825632ac8a439aff09f7e012e0f0b9f8c56b06e Mon Sep 17 00:00:00 2001 From: Ryan Dombrowski Date: Mon, 10 Aug 2026 15:09:46 -0400 Subject: [PATCH] docs: document the shipped ./browser and ./adapter-types subpaths; backfill five releases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The package went 0.2.0 → 0.3.2 with real behavior changes and no doc updates, so the README described a package two gate-scopes and two export subpaths behind what npm actually ships. - `./browser` (shipped in 0.3.2) was documented nowhere. It is the boundary dspack-studio's Composer runs the governed pipeline on in the page — gates and emission in the browser, only the proposal leaves — and the `node:crypto` aliasing caveat existed only in a source header. - `./adapter-types` was documented only in a 0.1.3 changelog line. It is the seam a host implements its own provider against (dspack-studio's agent uses it for the OpenAI-compatible adapter that does NOT live in this package). - S2's documented scope omitted sub-component containment (0.3.0, spec v0.4 §5.1) and the fact that containment errors are repairable in-loop; S3's omitted `requiredCategories` (0.2.2, §4.3). - CHANGELOG stopped at 0.2.0. Backfilled 0.2.1, 0.2.2, 0.3.0, 0.3.1, 0.3.2 and corrected the now-narrow emit peer range sentence. - The cross-reference to dspack-emit's exit codes omitted `5` (`--strict-surface`). - docs/CONTRACT-PIN.md still said the migration is "gated on the dspack-emit representation milestone" — that milestone shipped as emit 0.6.0 and this package already admits ^0.6.0, so the pin is now a reviewable fixture-corpus decision, not a wait. Verified: `npm test` 138 passing, and the documented `context` command runs against the pinned fixture. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 25 +++++++++++++++++++++++++ README.md | 23 +++++++++++++++++++++-- docs/CONTRACT-PIN.md | 7 ++++++- 3 files changed, 52 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 273e47d..18924e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,30 @@ # Changelog +## 0.3.2 + +- `./browser` export: a supported browser-safe boundary — `runPipeline`, + `RunOptions`, `RunResult`, `PipelineEvent`, `ScriptedAdapter`. Hosts bring + their own adapter for the model turn and alias `node:crypto` to a + synchronous SHA-256 shim. + +## 0.3.1 + +- dspack-emit peer range admits `^0.6.0`. + +## 0.3.0 + +- **S2 sub-component containment** (spec v0.4 §5.1): a sub-declared id may + appear only within its declaring compound. Containment errors ride the + repair message, so they are repairable in-loop. + +## 0.2.2 + +- **S3 evaluates `requiredCategories`** (spec v0.4 §4.3 amendment). + +## 0.2.1 + +- dspack-emit peer range admits `^0.5.0`. + ## 0.2.0 - **`RunOptions.conversation`** — prior turns seeded between the contract's diff --git a/README.md b/README.md index c115afd..85c1c03 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,8 @@ rename; the old package is deprecated with a pointer). | Gate | Check | Where | |---|---|---| | S1 | generic dspack surface schema | here (pre-emission) | -| S2 | contract vocabulary (components, sub-components, props, enum values, slots) | here (pre-emission) | -| S3 | governance rules (typed, deterministic, rationale-bearing) | here (pre-emission) | +| S2 | contract vocabulary (components, sub-components, props, enum values, slots) **and sub-component containment** — a sub-declared id may appear only inside its declaring compound (spec v0.4 §5.1); containment errors are repairable in-loop | here (pre-emission) | +| S3 | governance rules (typed, deterministic, rationale-bearing), including `required-props`, category-based `forbidden-composition`, and `requiredCategories` (spec v0.4 §4.3) | here (pre-emission) | | A1–A3 | schema-compile / catalog-shape / instance validation | dspack-emit (per emitted target) | S1/S2 are checks on **any** produced surface; constrained decoding may implement S2 during @@ -133,6 +133,25 @@ its read-only/no-network security posture. The boundary is enforced by import { compileContext, lintSurface } from "@aestheticfunction/dspack-gen/core"; ``` +`@aestheticfunction/dspack-gen/browser` is the **browser-safe** subpath: the +same `runPipeline` plus `ScriptedAdapter`, without the Node-only adapters and +emitter plumbing, so a page can run the governed pipeline itself and bring its +own adapter for the model turn (dspack-studio's Composer does exactly this — +gates and emission in the browser, only the proposal goes out): + +```ts +import { runPipeline, ScriptedAdapter } from "@aestheticfunction/dspack-gen/browser"; +``` + +One caveat the host must handle: the provenance hash reaches for `node:crypto`, +so bundlers should alias it to a synchronous SHA-256 shim. + +`@aestheticfunction/dspack-gen/adapter-types` exposes the adapter interface +alone (`GenerationAdapter`, `GenerateRequest`, `GenerateResult`, +`AdapterOutputError`, `parseJsonOutput`) for hosts implementing their own +provider — the seam dspack-studio's agent uses for its OpenAI-compatible +adapter. + The CLI installs as `dspack-gen` (same commands as the repo scripts): `context`, `lint`, `run`, `serve`. Outside this repository, always pass `--dspack ` (the `serve` default path points at a repo fixture). diff --git a/docs/CONTRACT-PIN.md b/docs/CONTRACT-PIN.md index b72fe7c..488198b 100644 --- a/docs/CONTRACT-PIN.md +++ b/docs/CONTRACT-PIN.md @@ -11,7 +11,12 @@ > **Not current shadcn/ui coverage.** This package's fixtures, goldens, grammar-alignment corpus, and pipeline tests were built against the 8-component contract. Do not cite them as production-shadcn evidence. -**Why:** dspack#35 moved `main` to the production contract on 2026-08-05; `check:sync` follows `main` and runs before the test suite in CI, so every branch here went red (or green-by-stale-lockfile) with no code change. Syncing forward would break the fixture corpus rather than widen it — the migration is gated on the dspack-emit representation milestone (aestheticfunction/dspack-emit#28). +**Why:** dspack#35 moved `main` to the production contract on 2026-08-05; `check:sync` follows `main` and runs before the test suite in CI, so every branch here went red (or green-by-stale-lockfile) with no code change. Syncing forward would break the fixture corpus rather than widen it — the migration was gated on the dspack-emit representation milestone +(aestheticfunction/dspack-emit#28), **which shipped as dspack-emit 0.6.0** (T1-T4 + +layered dissolution; this package's peer range already admits `^0.6.0`). The +blocker is therefore cleared and the pin is now a deliberate, reviewable +fixture-corpus decision rather than a wait — migrating means rebuilding the +goldens and grammar corpus against the production contract. **Enforcement:** the sync check verifies the pinned artifact's sha256 on every run (a pinned ref must be immutable; a change means force-push or CDN mismatch — `TAMPERED`, exit 1), still fails on local drift, and always prints how far behind `main` the pin sits. Verified: clean → 0, mutated hash → 1, restored → 0.