@kumwe/studio-protocol 0.1.0-alpha.5 → 0.1.0-beta.2

package/README.md

@@ -1,22 +1,88 @@
 # `@kumwe/studio-protocol`
 
-Status: pre-Gate-A foundation alpha. Its draft contracts may change and are not a supported protocol.
+Status: governed beta development, still pre-Gate-A and not production-supported. The exact coordinated
+version is in the workspace `studio-release.json`; these draft contracts may change and are not a supported
+protocol.
 
 Serializable contracts shared by Studio hosts, renderers, extensions, and non-JavaScript clients.
 The package deliberately contains no DOM or framework dependency. JSON Schemas are published under
 the `schemas` export for authoritative validation outside TypeScript.
 
 The initial contract covers blueprints, block definitions, design profiles, host capabilities,
-commands and canonical command vectors, preview messages, host port errors, media asset
+commands and canonical command vectors, preview messages and identity vectors, host port errors, media asset
 projections, persisted media references, media upload sessions, portable rich text, plugin
 manifests, and entries. `MediaAsset` describes host-owned library state; the smaller
 `MediaReference` is the portable value stored in an artifact. Consumers validate the document's
 `contractVersion` and separately negotiate the SemVer wire `protocolVersion`; neither value may be
 inferred from the other or from the `/studio/v1/` schema epoch URI.
 
-Beyond document shapes, the package projects the host adapter surface (`HostAdapter` and its nine
+The package exports deterministic schema-generated `Generated*` models for all 55 Version 2 protocol schema
+roots and their 253 top-level reusable `$defs` definitions. `GeneratedProtocolModelMap` binds each schema
+filename to its root model, `GENERATED_PROTOCOL_SCHEMA_FILES` exposes the complete checked registry, and
+`GENERATED_TYPESCRIPT_MODEL_METADATA` records generator name/version, schema-manifest digest, schema epoch,
+document contract revision, and supported wire-protocol range. Regenerate with
+`npm run protocol:models:generate`; `npm run protocol:models:check` fails on byte drift.
+
+Generated models are structural compile-time conveniences, not validators. Callers validate untrusted input
+against the matching exported JSON Schema before using `roundTripGeneratedProtocolModel`; JSON Schema and
+the normative contracts remain authoritative for patterns, numeric/string and maximum array bounds, exact
+object closure, integer-ness, uniqueness, conditionals, dependencies, and `oneOf` exclusivity. The generator
+models `minItems`, `prefixItems`, and open additional members; it fails closed if a canonical schema introduces
+`patternProperties`. Object and array keywords receive a narrower structural projection only when the schema
+declares the corresponding `type`; without it, scalar instances remain valid under JSON Schema and the generated
+projection deliberately stays broad. The handwritten protocol interfaces remain the ergonomic runtime/port API
+and may not widen the generated wire shape.
+
+The test lane directly assigns every manifest-listed applicable positive corpus literal to its exact
+filename-specific generated root except the two maximum-JSON-depth schema-profile vectors. Those vectors are an
+explicit TypeScript 6 `TS2321` compiler-depth boundary, not a cast: the boundary test requires that diagnostic,
+and the runtime lane schema-validates and round-trips the complete manifest-derived inventory.
+
+The contextual authoring foundation is canonical protocol, not a shell-local convention. It exports the
+bounded `AuthoringTargetDeclaration`, host-owned `ReusableContentTypeDefinition`, full
+`AuthoringSessionSnapshot`, exact Model/Blueprint/Entry coordinates, explicit save intent/plan/result documents,
+and the three distinct commit requests. `HostAdapter.authoring` adds resource-bound target resolution, type
+listing, session start, save planning, and explicit item/new-version/new-type operations without changing the
+legacy artifact port. A contextual start returns complete separately identified documents; reusable types never
+carry Entry values.
+
+The typed composition API covers all six canonical contribution payload families. Manifest `block`
+declarations map to `BlockDefinition` documents whose discriminator is `block-definition`; patterns, design
+vocabulary, migrations, inspectors, and field adapters retain matching discriminators. `InspectorContribution`
+and `FieldAdapterContribution` are declarative data types only—execution remains a negotiated host capability.
+
+The authoring message-catalog schema defines versioned locale bundles with closed message entries,
+default text, and explicit named parameters. The canonical English shell catalog is published by
+`@kumwe/studio` and replayed as a byte-identical testkit fixture.
+
+Beyond document shapes, the package projects the host adapter surface (`HostAdapter` and its ten
 typed ports sharing one request envelope), the stable host error taxonomy with the
-`isHostPortError` guard, the extension lifecycle state vocabulary, and the preview message guard.
-`schemas/manifest.json` records the schema epoch plus the file, canonical `$id`, and sha256 digest
-of every published schema so generated SDKs can pin the exact corpus they were built against.
+`isHostPortError` guard, and the JavaScript `HostPortFailure` rejection wrapper with its
+`isHostPortFailure` guard. A stale generation remains `invalid-request` and is distinguished by the
+stable `studio.host/stale-session-generation` diagnostic, also exported as
+`STUDIO_STALE_SESSION_GENERATION_DIAGNOSTIC_CODE`, allowing a composed session to invalidate the
+complete handle without treating every invalid request as stale. The package also projects the
+extension lifecycle state vocabulary and preview guards for the message, rendered inventory, and
+canonical marker grammar. Preview draft.2 closes its message discriminator,
+requires artifact/revision/digest plus session-unique render-attempt correlation, and applies the same
+safe local-name and 240–10000 pixel viewport bounds in schema and runtime guards.
+`schemas/manifest.json` records its own generator version, the schema epoch, document contract revision, and
+the file, canonical `$id`, and sha256 digest of every published schema. The generated TypeScript metadata
+records the digest of those exact manifest bytes, so consumers can identify the corpus it was built against.
 Canonical command vectors and the negative-fixture corpus ship through `@kumwe/studio-testkit`.
+The protocol package also exports the single-exchange and ordered host-vector schemas. The sequence
+schema fixes the idempotency scope/preimage and its deterministic clock/render control steps; the
+portable corpora and runner-neutral digest manifest ship through the testkit. The published
+`authoring-web-vector` schema similarly carries semantic keyboard, pointer and explicit-control lanes
+without selectors or component-library types; its target profile remains unclaimed until the full
+browser and accessibility matrix is reproduced.
+
+Canonical production values include chart, drawing, exact-decimal money, text-only tables, and the closed Studio
+presentation intent. The latter carries semantic alignment, sizing, spacing, position, print,
+scrolling, marker, motion, and responsive-visibility choices without carrying CSS or JavaScript.
+
+`@kumwe/studio-protocol/studio-release.json` is a byte-identical copy of the canonical workspace
+release record. It binds the exact fixed eight-package family to the wire protocol and testkit corpus
+digest. The publication guard requires all eight versions to equal its `release` coordinate. The abandoned
+historical `0.1.0-rc.1` record listed nine proposed profile claims; it was not accepted evidence or a
+production-support claim. The current beta record deliberately claims none.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third-party notices
+
+<!-- Generated by scripts/generate-third-party-notices.mjs. Do not edit by hand. -->
+
+Package: `@kumwe/studio-protocol`
+
+Production closure SHA-256: `4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945`
+
+This package has no third-party runtime dependencies.