docs: document the shipped ./browser + ./adapter-types subpaths; backfill five releases - #56
Merged
Merged
Conversation
…ckfill five releases 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 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Updates dspack-gen’s public documentation to reflect shipped subpath exports and previously undocumented behavior changes across releases 0.2.1–0.3.2, aligning the README/contract pin rationale/changelog with current package behavior.
Changes:
- Expanded gate documentation (S2 containment; S3 requiredCategories) in
README.md. - Documented the shipped
./browserand./adapter-typessubpaths and their intended usage inREADME.md. - Backfilled
CHANGELOG.mdentries for 0.2.1, 0.2.2, 0.3.0, 0.3.1, 0.3.2; updateddocs/CONTRACT-PIN.mdrationale around the emit milestone being shipped.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | Updates gate descriptions and documents ./browser + ./adapter-types usage. |
| docs/CONTRACT-PIN.md | Clarifies why the fixture contract pin remains and updates milestone status context. |
| CHANGELOG.md | Adds missing release notes for 0.2.1–0.3.2, including ./browser export documentation. |
Suppressed comments (2)
docs/CONTRACT-PIN.md:23
- This paragraph explains the dspack-emit representation milestone has already shipped (0.6.0), but the Removal section below still reads as if that milestone is pending. Updating the Removal wording will keep the doc internally consistent with the new rationale.
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.
**Removal:** after the emit representation capabilities land and the profile migration completes — remove the `pin` block, `node scripts/check-sync.mjs --write`, regenerate goldens, commit together.
README.md:153
- The PR description says the README’s cross-reference to dspack-emit exit codes was updated to include code
5(--strict-surface), but the Exit codes section in this README still only mentions3and4. Please update that earlier Exit codes note so the docs match the PR description.
`@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.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+136
to
+140
| `@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): |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
From an ecosystem-wide documentation audit. The package shipped 0.2.0 → 0.3.2 with real behavior changes and no doc updates.
./browserwas documented nowhere despite shipping in 0.3.2. It's the boundary dspack-studio's Composer uses to run the governed pipeline in the page (gates + emission in the browser; only the proposal leaves), and thenode:cryptoaliasing caveat lived only in a source header../adapter-typesappeared only in a 0.1.3 changelog line. It's the seam a host implements its own provider against — dspack-studio's agent uses it for the OpenAI-compatible adapter, which deliberately does not live in this package.requiredCategories(0.2.2, §4.3).5(--strict-surface).docs/CONTRACT-PIN.mdsaid the contract migration is "gated on the dspack-emit representation milestone" — that shipped as emit 0.6.0, and this package already admits^0.6.0, so the pin is now a reviewable fixture-corpus decision rather than a wait.Verified:
npm test138 passing; the documentedcontextcommand runs against the pinned fixture. The CLI, exit codes, adapters,/core, env var, and every fixture reference audited clean and are untouched.🤖 Generated with Claude Code