docs(supabase): document the wasm-inline entry in the two files that ship - #951
Draft
tobyhede wants to merge 1 commit into
Draft
docs(supabase): document the wasm-inline entry in the two files that ship#951tobyhede wants to merge 1 commit into
tobyhede wants to merge 1 commit into
Conversation
…ship `@cipherstash/stack-supabase` has had two entry points since #912. The package root introspects the database and runs on Node; `/wasm-inline` carries the WASM engine, takes declared `schemas` instead of introspecting, and runs on Deno, Supabase Edge Functions and Cloudflare Workers. Introspection was the only thing needing a Postgres socket, so that entry does run in a Worker. Two shipping documents were never updated and still describe the state before that change: - `packages/stack-supabase/README.md` said the factory "cannot run in an edge Worker or the browser", and contained no occurrence of the word "wasm" at all. This file renders on the npm package page. - `skills/stash-supabase/SKILL.md` said the same in its setup section. The skill ships inside the `stash` tarball and `stash init` copies it into the customer's repo, where their agent reads it as instruction. The file's one correct mention of the edge entry sat in a callout the setup steps never pointed at, so a reader following the steps never learned it existed. The readers this misled hardest are the ones who need the edge entry most: server code on Lovable, v0, Bolt and Replit runs on an edge runtime, which is exactly what `/wasm-inline` was built for. The failure is silent — an agent that reads "cannot run in a Worker" concludes the product does not support the platform and stops. Both files now carry an entry-point table and the edge call shape, and name the four ways that entry differs, each checked against the source rather than restated: `schemas` is required (`create.ts:307-313`), `config` is required and carries all four `CS_*` values (`wasm-inline.ts:18-30`), `databaseUrl` throws at construction (`create.ts:359-361`), and `.withLockContext()` / `.audit()` throw rather than silently dropping an identity claim (`wasm-client-adapter.ts:40-66`, #797). The browser half of the old sentence was correct and is kept, with its reason named: the WASM client requires a workspace `clientKey` on every authentication path, so a browser build would ship the key with it (#804). Deliberately untouched: `packages/stack/CHANGELOG.md`, `packages/stack-supabase/CHANGELOG.md` and the superpowers design spec carry the same sentence and are historical records, accurate for their dates. `docs/reference/supabase-sdk.md` carries it too and is fixed separately — it is internal and ships in no package. Changeset: `stash` patch for the skill, `@cipherstash/stack-supabase` patch for the README. Closes #950 Refs #912, #804, #797 Claude-Session: https://claude.ai/code/session_01E1J2nVGJWVkqvLepDfinRf
🦋 Changeset detectedLatest commit: 2733d25 The changes in this PR will be included in the next version bump. This PR includes changesets to release 11 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This was referenced Aug 27, 2026
Draft
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
1 participant
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.
Summary
CipherStash Stack encrypts individual database columns.
@cipherstash/stack-supabaseis the Supabase integration, and since #912 it has shipped two entry points: the package root, which reads your column types straight out of Postgres and therefore needs Node; and@cipherstash/stack-supabase/wasm-inline, which takes the tables you declare instead and therefore runs on Deno, Supabase Edge Functions and Cloudflare Workers.The two documents that ship to customers were never updated. Both still said the wrapper cannot run in a Worker, which stopped being true nine days ago. This PR corrects them and documents the edge entry, which the README did not mention even once.
This matters most for the readers who need the edge entry: server code on managed AI platforms (Lovable, v0, Bolt, Replit) runs on an edge runtime. An agent that reads "cannot run in a Worker" does not file a bug — it concludes the product does not support the platform and stops.
Changes
skills/stash-supabase/SKILL.md— ships inside thestashnpm package;stash initcopies it into the customer's repository, where their coding agent reads it as instruction.wasm-inlineentry": an entry-point comparison table, the full call shape, and the four ways that entry differs.@cipherstash/stack/wasm-inline, which is the right entry for encrypting without the wrapper and the wrong one for using it.packages/stack-supabase/README.md— renders on the npm package page..changeset/supabase-docs-wasm-inline-entry.md—stashpatch (the skill ships in that tarball) and@cipherstash/stack-supabasepatch (the README).Verification
Every claim about the edge entry was checked against source rather than restated:
schemasis requiredpackages/stack-supabase/src/create.ts:307-313configis required and carries all fourCS_*valuespackages/stack-supabase/src/wasm-inline.ts:18-30databaseUrlthrows at constructionpackages/stack-supabase/src/create.ts:359-361.withLockContext()/.audit()throwpackages/stack-supabase/src/wasm-client-adapter.ts:40-66Test runs:
pnpm --filter @cipherstash/stack-supabase test— 565 passed, 16 files.pnpm --filter stash exec vitest run src/__tests__/skill-supabase-apply.test.ts— 29 passed. This is the guard that reads the shipped skills.npx vitest run scripts/__tests__/skills-retired-package-scopes.test.mjs scripts/__tests__/turbo-skills-inputs.test.mjs— 42 passed.Rebuilt
stash,@cipherstash/wizardand@cipherstash/stack-supabase.grep "cannot run in a Worker"overpackages/cli/dist/skills/andpackages/wizard/dist/skills/now returns nothing; before the rebuild both carried it at line 269, so annpm packshipped it.pnpm run code:checkdoes not pass on this machine, and does not onmaineither: it exits at the configuration stage on a nestedbiome.jsoninside a local.claude/worktrees/checkout, before linting anything. Biome does not lint Markdown in this repo regardless — run against the three changed files directly it reports all three as ignored, so this PR cannot affect that check either way.Related
Closes #950
Refs #912 (added the second entry point), #804 (the browser claim, which is correct and stays), #797 (
.withLockContext()on the WASM entry, which throws today).Review notes
This branch conflicts with #953 in
skills/stash-supabase/SKILL.md. Both edit the same paragraph: this one replaces the sentence at line 269, and that one inserts a paragraph immediately below it. The two are complementary — that PR explains why the browser is still ruled out, this one explains why the Worker no longer is — so whichever merges second should rebase and keep both.Three files carry the same stale sentence and are deliberately untouched:
packages/stack/CHANGELOG.md,packages/stack-supabase/CHANGELOG.md, anddocs/superpowers/specs/2026-07-09-supabase-v3-introspection-design.md. They are historical records and were accurate on the dates they were written.docs/reference/supabase-sdk.mdcarries it too, and is fixed in #952 instead — it is internal reference documentation and ships in no package, so it takes no changeset and did not belong in this one.