@astrale-os/sdk 0.6.0-beta.39 → 0.6.0-beta.40

package/docs/release.md

@@ -0,0 +1,155 @@
+# SDK release lifecycle
+
+Release Please owns the versions and GitHub releases for the SDK package set:
+
+- `@astrale-os/sdk`
+- `@astrale-os/adapter-cloudflare`
+- `@astrale-os/adapter-astrale`
+- `create-astrale-domain`
+
+The Node workspace plugin follows local dependency edges. Every internal release edge uses
+`workspace:*`, so a changed SDK refreshes the dependent adapter and scaffolder packages in the same
+Release Please pull request and publication rewrites each edge to that dependency's exact version.
+Never use a caret or tilde for an internal release edge: an immutable adapter must not resolve a
+newer SDK or adapter after publication. The shared publisher consumes those versions; it never
+invents a release version.
+
+Dependency installation, authoritative publication, and public qualification are npmjs-only. npm
+publication uses OIDC Trusted Publishing. After that proof completes, the workflow mirrors the exact
+SDK and adapter tarballs to private GitHub Packages copies. GitHub Packages is never a consumer,
+build, installation, or qualification source. Never add a PAT, an npm token, an auth file, or a
+repository package token; no credential may enter a tracked file, lockfile, package archive, or build
+log.
+
+## Normal beta release
+
+Prerequisite: every exact Kernel dependency in the SDK manifest is already published on npm and the
+SDK passes typecheck, test, build, pack, and fresh-consumer gates against those artifacts. Never use
+a local checkout, tarball, or override to make the release build pass.
+
+1. Merge conventional feature and fix pull requests into `main`.
+   The squash-merge title is Release Please input: use `feat` for a public capability or API change
+   and `fix` for a behavioral defect. Never classify a publication-bearing change as `refactor`,
+   `docs`, `chore`, or `test`; those types do not advance the beta
+   package cohort.
+2. The `Release` workflow creates or refreshes the single Release Please pull request.
+3. Select **Approve workflows to run** for that bot-authored pull request and wait for every required
+   check. GitHub can mark these workflows `action_required`; this is an approval gate, not a passed
+   run.
+4. Review every changed package version, exact internal dependency, changelog, and
+   `.release-please-manifest.json` entry.
+5. Merge the Release Please pull request.
+6. Release Please creates an immutable GitHub prerelease for every released component. Only then does
+   `Release` dispatch the standalone `Publish` workflow with the exact released commit SHA, preserving
+   its npm Trusted Publishing identity. Publish rejects a non-SHA or a checkout mismatch before npm I/O.
+7. The shared package publisher builds the workspace and publishes every public package to npm. A
+   `-beta.N` version advances npm `beta`; npm `latest` remains on the last stable version.
+8. The same workflow then runs `pnpm run qualify:publications` without a token. This creates isolated
+   temporary stores, installs the four exact manifest versions from npmjs, generates a Domain with
+   `linkWorkspacePackages: false`, pins that generated project to the exact SDK and adapter versions,
+   and runs its typecheck, tests, build, and package command. Any missing publication, transitive
+   dependency, wrong version, non-exact internal cohort edge, local source, override, or GitHub
+   registry reference fails the workflow.
+9. A separate least-privilege job downloads the exact SDK and adapter tarballs from npm, verifies
+   their npm SHA-512 integrity, mirrors them with `GITHUB_TOKEN`, and then requires byte-identical
+   GitHub downloads, matching release-channel tags, private visibility, and an exact link to
+   `astrale-os/sdk`. The scaffolder remains npm-only.
+
+The publisher receives package directories in strict producer order: SDK, Cloudflare adapter,
+Astrale adapter, then scaffolder. The shared action validates this dependency order and completes npm
+plus the exact release-channel dist-tag for one package before it starts the next. A linked workspace
+build is therefore never treated as publication proof.
+
+npm publication has no token fallback. All four npm packages must configure GitHub Actions Trusted
+Publishing for this repository and the `publish.yml` workflow. A missing Trusted Publisher or a wrong
+dist-tag is an explicit, fail-closed publication error; do not work around it with a PAT or npm token.
+
+The mirror job starts only after the anonymous npm qualification succeeds. It has `packages: write`
+but no npm OIDC permission, performs no build or workspace install, and cannot publish to npm. A
+mirror failure makes `Publish` red without undoing the already-complete npm release. Rerunning the
+failed job is safe: existing versions must be byte-identical, no version is overwritten or deleted,
+and tags are reconciled only when npm still points them at that exact version. Do not backfill older
+version gaps during initial rollout; the next ordinary beta release is the admission proof.
+
+Ordinary source pushes do not publish. Do not manually edit package versions, manually dispatch
+`Publish`, or push release tags during the normal flow.
+
+## Start the new Auth beta series
+
+The session-owned Auth API starts a new SDK beta series at `0.6.0-beta.0`. Its feature PR sets
+only the SDK's package-local `release-as` to that version. Release Please owns the actual manifest
+and cohort bumps. Remove that one-shot override from the generated release PR before merging it.
+This keeps the release on npm `beta`, while existing SDK `0.5.0` prerelease ranges retain the old API.
+
+## Promote the package set to stable
+
+Create one promotion pull request that removes only these beta settings from
+`.release-please-config.json`:
+
+```json
+"versioning": "prerelease",
+"prerelease": true,
+"prerelease-type": "beta"
+```
+
+Keep the Node workspace plugin, `always-update`, package map, and workflows unchanged. In the same
+promotion pull request, temporarily add these package-local overrides:
+
+```json
+"packages": {
+  ".": { "component": "sdk", "release-as": "0.6.0" },
+  "adapter-cloudflare": { "component": "adapter-cloudflare", "release-as": "0.5.0" },
+  "adapter-astrale": { "component": "adapter-astrale", "release-as": "0.5.0" },
+  "create-astrale-domain": {
+    "component": "create-astrale-domain",
+    "release-as": "0.3.0"
+  }
+}
+```
+
+After that promotion pull request lands, Release Please proposes those stable versions. Remove all
+four `release-as` properties from the generated stable release pull request, rerun its checks, and
+merge it. This publishes npm `latest` and ordinary GitHub releases. The npm `beta` tags intentionally
+remain on the last beta and do not affect bare installs.
+
+## Verification
+
+Always name npmjs explicitly when inspecting releases so the verification also proves the public
+registry boundary.
+
+```bash
+gh run list --repo astrale-os/sdk --workflow Release --limit 5
+gh run list --repo astrale-os/sdk --workflow Publish --limit 5
+npm view @astrale-os/sdk dist-tags --json --registry=https://registry.npmjs.org
+npm view @astrale-os/adapter-cloudflare dist-tags --json --registry=https://registry.npmjs.org
+npm view @astrale-os/adapter-astrale dist-tags --json --registry=https://registry.npmjs.org
+npm view create-astrale-domain dist-tags --json --registry=https://registry.npmjs.org
+gh api orgs/astrale-os/packages/npm/sdk --jq '{visibility,repository:.repository.full_name}'
+gh api orgs/astrale-os/packages/npm/adapter-cloudflare --jq '{visibility,repository:.repository.full_name}'
+gh api orgs/astrale-os/packages/npm/adapter-astrale --jq '{visibility,repository:.repository.full_name}'
+```
+
+The SDK, adapters, scaffolder, generated manifest, and every transitive runtime dependency must be
+installable from npmjs without authentication. Prove that boundary from a clean temporary directory:
+
+```ini
+# ./npmrc (in the smoke-test parent directory)
+registry=https://registry.npmjs.org/
+always-auth=false
+```
+
+Then run the complete smoke test:
+
+```bash
+NPM_CONFIG_USERCONFIG="$PWD/npmrc" npm install @astrale-os/sdk@beta
+NPM_CONFIG_USERCONFIG="$PWD/npmrc" npx -y create-astrale-domain@beta beta-smoke --yes
+cd beta-smoke
+NPM_CONFIG_USERCONFIG="../npmrc" pnpm install --no-frozen-lockfile
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Inspect the generated lockfile and installed package manifests. They must resolve the released SDK and
+adapter package set and the SDK-owned public Kernel dependencies from npmjs, not `latest`, GitHub
+Packages, workspace links, Git URLs, or an older manually published beta.

package/docs/schema-cost.md

@@ -0,0 +1,124 @@
+# What a compiled Schema costs
+
+A compiled Domain is large, and its size is not driven by how much the Domain declares. This
+records what the weight is made of, where it is paid, and which levers belong to this repository.
+
+Every figure comes from `scripts/bench/`, on synthetic Domains built around `KernelSchema`. Node
+counts and byte weights follow from the compiled format and hold anywhere. **Timings do not.** The
+benches run under Bun, which is JavaScriptCore, and workerd is V8. On the same graph and the same
+walk:
+
+| walk | V8 (Node 26) | JavaScriptCore (Bun) |
+| --- | --- | --- |
+| seal, as shipped | 10.4 ms | 73.7 ms |
+| seal, arrays indexed and primitives skipped | 5.9 ms | 48.2 ms |
+
+Close to an order of magnitude apart. Read every millisecond below as a JavaScriptCore
+millisecond: useful for ranking two strategies against each other, worthless as a production
+figure. Any claim about cold start has to be re-measured on the real bundle in workerd.
+
+## The cost law
+
+Growing a Domain two ways, plain classes against classes carrying one format-constrained
+property (`bun scripts/bench/schema-cost.ts`):
+
+| classes | plain | one constrained property each |
+| --- | --- | --- |
+| 0 | 19 522 | 19 522 |
+| 5 | 19 587 | 22 157 |
+| 20 | 19 782 | 30 062 |
+| 50 | 20 172 | 45 872 |
+
+Three readings, each counter-intuitive.
+
+**An empty Domain is not empty.** 19 522 nodes and 554 KiB before anything is declared. That is
+the floor the `KernelSchema` dependency sets, and every Astrale Domain pays it.
+
+**Classes and properties are nearly free.** Fifty classes and a hundred plain properties add a
+thousand nodes, about twenty per class. The size of the model is not the problem.
+
+**One thing is expensive: a string carrying a format.** The same constraint on fifty classes adds
+26 350 nodes, about **527 nodes per property**, and fifty separate automata for one expression.
+`resolve` and `compile` both roughly double over the same range.
+
+## Where the weight is
+
+On the Kernel floor, by region (`bun scripts/bench/compiled-graph.ts`):
+
+| region | nodes | share |
+| --- | --- | --- |
+| `values[].patterns` | 15 856 | 81.2 % |
+| `values[].nodes` | 3 031 | 15.5 % |
+| `definitions.*` | 563 | 2.9 % |
+| everything else | 6 | 0.0 % |
+
+The weight is compiled regular-expression automata. A bounded quantifier is unrolled into one
+state per repetition, so `{64}` becomes 162 states and `{0,253}` becomes 528. Each state carries
+two arrays, each transition an array of ranges, and each range is itself a two-element array.
+That is also why a compiled graph holds more arrays than objects.
+
+Nothing is shared between copies. Sixteen automata stand for seven distinct expressions:
+`sha256:[0-9a-f]{64}`, nineteen characters, weighs 576 nodes and exists five times over. Interning
+by source would remove 7 973 of the 15 794 pattern nodes at identical semantics, since two
+automata for one expression are structurally identical and immutable.
+
+## Where it is paid
+
+1. **At build time**, in `compile`. Once, on a contributor's machine.
+2. **In the Worker bundle.** The material is emitted as an inline literal, so the automata ship as
+   bytes: 44 % of a bare compiled Schema, 65 % once a Domain constrains its strings.
+3. **At cold start, the material path.** The emitted literal is allocated, sealed, and realized on
+   the first request of every isolate.
+4. **At cold start, the authoring path**, when application code builds the Schema from source at
+   runtime. `resolve` is memoised per Schema value, so it is a once-per-isolate cost like the
+   material path, not a per-request one.
+5. **In any client** that builds the Schema, a browser included.
+
+## Sealing the material
+
+`schema.compiled` is almost the whole material graph, so sealing cost is a question of how many
+times that graph is walked (`bun scripts/bench/freeze-strategies.ts`):
+
+| strategy | cost |
+| --- | --- |
+| before: two SDK passes and one DSL pass | 131.6 ms |
+| current: one SDK pass and one DSL pass | 74.7 ms |
+| candidate: the DSL owns `schema.compiled` | 62.0 ms |
+
+Two results matter more than the ranking.
+
+**Most of the remaining cost is not the Schema.** Sealing `schema.compiled` alone is 17.2 ms.
+Sealing `schema.bundle.bytes` alone is 43.9 ms, because it is one array of tens of thousands of
+numbers and the walker calls `Object.values` on it. A walker that indexes arrays in place and
+never recurses into a primitive takes one pass from 61.2 ms to 43.5 ms. `Object.freeze` on an
+array of numbers already seals its elements, so that recursion changes nothing: it is cost
+without a guarantee behind it.
+
+**The emitter throws away sharing the compiler produced.** The compiled graph holds 19 522 nodes
+as built and 32 882 after a JSON round trip, because JSON has no references. 13 360 nodes, two
+thirds again, exist only because the material is emitted as a flat literal. Hoisting identical
+subtrees into shared bindings at emission would restore sharing rather than invent it, and would
+cut bundle bytes at the same time.
+
+Sealing is a guarantee, not decoration: `realize()` retains live references into the graph, and
+the material is one singleton shared by every concurrent request in the isolate. None of the
+changes above give that up. They stop walking what is already sealed, or what sealing a container
+already covers.
+
+## Which levers are here
+
+Owned by this repository: how many times the material is walked, how the walker treats a flat
+array, whether the emitter shares identical subtrees, and whether the SDK hands out the Domain
+that a restored Build already carries instead of leaving an application to rebuild it.
+
+Owned by `kernel-dsl`: the cost of `resolve`, the pattern table in the compiled format, and the
+unrolling of bounded quantifiers. The last of these pays at all five sites at once and is where
+most of the weight is. None of it can be reached from here.
+
+## Verifying a change
+
+`scripts/bench/freeze-equivalence.ts` compares the frozen state of every reachable node between
+two sealing implementations and exits non-zero on a divergence or a vacuous walk. Spine assertions
+cannot tell a deep seal from a shallow one: `material()` returns a shallow-frozen envelope, so a
+walker treating a frozen container as proof of a sealed interior would seal nothing and still
+satisfy them. `src/deployment/build/__tests__/realization.test.ts` carries the standing audit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.6.0-beta.39",
+  "version": "0.6.0-beta.40",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",
@@ -20,7 +20,8 @@
   },
   "files": [
     "dist",
-    "!dist/**/*.map"
+    "!dist/**/*.map",
+    "docs"
   ],
   "type": "module",
   "sideEffects": false,