[cuibonobo]

Summary

Closes #426. A stack can now leave its storage whole, authorship and history included.

• copyStack(from, create) in @haverstack/core/adapter copies a whole stack into a new store that create makes, and returns that store open. It carries every Record (soft-deleted and unlisted included) with its versions and journal, every Type, and every blob. Blobs go before the Records that name them. Each is read as the store enumerates it (listTypes, listBlobs, queryRecords, and getRecord('_config')), never by what a Record says, so nothing is filtered on the way. Export, import and moving between storage engines are all this one call with a different source and a different kind of store to create.
• _config travels like every Record. A store is created from a StoreSeed: a _config record and its history. copyStack hands create the source's own seed, so the target's _config arrives with its versions and journal, and its identity is what the source's record holds now, not what the source adapter read when it was opened.
  • Every adapter that creates stores takes seed in place of ownerEntityId and timezone. Native takes it only with create: 'exclusive'.
  • newStoreSeed() makes a fresh one, so a new store's _config is written through the same path as any imported Record.
  • MemoryAdapter now holds a real _config record.
• What each side needs:
  • Both ends must have listBlobs(), so a copy never lands a stack where it can't be copied out again.
  • Source: must hold _config, and must not be written during the copy. Nothing checks the latter, and the spec and doc comment both say so.
  • Target: a store as its adapter creates one. Its owner is checked against the seed's with the same OwnerMismatchError open() throws. It must hold nothing else yet (no other Record, no Type, no blob) and have importRecord(). So a store already opened with Stack.open() is refused, since it holds the system Types.
  • Anything else is refused with InvalidAdapterError before anything is written.
• The target is the caller's. On success it comes back open for the caller to close. On a failure, copyStack closes it (it holds the only handle) and the caller removes it. The original error is the one rethrown.
• StackRecordAdapter.importRecord(record, { versions, journal }) is a new optional method. It writes a Record exactly as recorded, history included, in one atomic write, appends no entry of its own, and returns the StackRecord as createRecord() does. RecordHistory is two sets, keyed by version and seq: every snapshot below record.version, and journal seq values dense from 1, in any order. It's implemented by MemoryAdapter, the shared SQLite logic (both SQLite engines), adapter-local and combineAdapters. APIAdapter has none, since a server is the only writer of its own history tiers. Both journal writes in the SQLite logic run the same INSERT with only bound values.
• saveVersion() is removed from the adapter contract. Only tooling and tests used it, and importRecord() is now the one standalone history write.
• Stores are written whole, and opened one way.
  • writeNewStore(exec, seed) writes a new store's tables, its format row and its _config (with history) in one transaction. Opening an existing store runs no DDL, only the per-connection pragmas.
  • So the format table alone says whether a database holds a store. A store in another layout, or naming none, throws FormatMismatchError; that's the one refusal for a store that isn't whole in this layout.
  • Both SQLite engines open through one openStore() in sqlite-shared. It reads the store once, judges the create mode, checks the owner, and creates from a seed or a fresh one. So the two engines can't drift; the DO adapter now refuses an empty owner, as Node does.
  • A failed Node open() removes a file it created.
  • These rules are in adapters.md § Construction, beside OwnerMismatchError.
• The portable format is a LocalAdapter store: the SQLite database with attachments/<fileId> beside it.
  • portability.md lists every table and column, and gives the reason for each NULL exception.
  • Every SQLite store names its layout in a one-row format table, currently version 1. A layout belongs to a store that persists, so MemoryAdapter has none.
  • The derived index tables are part of the layout too, so an indexing change is a layout change like any other. The copy rebuilds them as it writes.
  • It's a table rather than PRAGMA user_version because Durable Object storage refuses that pragma.
  • A test compares the spec's tables and the format version with the schema a new store is created with.
  • adapter-json stays planned and would become one more kind of store to copy into.
• One name for the owner: a field is ownerEntityId when it can only hold the owner, and entityId when it may hold any entity. So _config's content ({ ownerEntityId, timezone }), ConfigContent, the discovery response and its fixtures now say ownerEntityId. Relationship targets and grantees keep entityId. This is a wire change: DiscoveryResponse.entityId is now ownerEntityId.
• Error messages: OwnerMismatchError and FormatMismatchError read <where> is owned by "X", not "Y" and <where> is format version N, not 1, so they fit both open() and copyStack().

Spec

• New docs/spec/portability.md: copying a stack (_config included, as the seed), writing history, the portable format (tables, encoding rules, columns, format version), tokens and installs. Listed in docs/spec.md.
• adapters.md § Construction: every store is created holding _config, from a fresh identity or a seed; stores are written whole; the format table says whether one is there; the FormatMismatchError rule, beside OwnerMismatchError.
• spec.md § The _config record: the owner-naming rule, and ownerEntityId as _config's immutable field.
• wire-format.md § Discovery and § Identity is trusted on transport: ownerEntityId.
• identity.md: _config.ownerEntityId.
• adapters.md: importRecord() among the optional capabilities; listBlobs() required of both ends of a copy; runCopyConformance() under Conformance.
• versioning.md, journal.md, wire-format.md: saveVersion() references replaced.
• data-model.md § Backdating on import and access-control.md link to the new page.

Verification

All six checks pass locally: format:check, check:refs, lint, test, build, typecheck.

• Record conformance suite: new importRecord() checks (exact round trip of record, versions and journal; returns the record; no entry of its own; conflict on an existing id; queryable after import; later writes continue the history), run against MemoryAdapter and NativeSQLiteRecordAdapter.
• runCopyConformance({ create, source? }): writes a stack with a past into a source store, _config's own patch included, then copies it into one create makes from the seed. Every Record (_config included), version, journal entry, Type and blob must arrive unchanged. The blobs include bytes a file-ref names with no metadata record. It runs against MemoryAdapter, and against LocalAdapter three ways: Local→Local, Memory→Local and Local→Memory.
• Core unit tests:
  • _config arrives with its history, and a timezone patched after the source was opened reaches the target;
  • paging past one page;
  • every listed blob is copied;
  • a source with no listBlobs() is refused before create is called;
  • each way a target can fail the rule is refused, and the target closed: no importRecord(), no listBlobs(), another owner (OwnerMismatchError), a Record, the system Types Stack.open() seeds, a blob.
• sqlite-shared (config.test.ts, on an in-memory node:sqlite database):
  • a database holding no store reads as missing;
  • a created store's identity reads back, an absent timezone included;
  • a store naming another version, or none, is refused, with no table written;
  • writeNewStore() writes the whole store or none of it, tables included.
• record-adapter-sqlite:
  • portable-format.test.ts compares the spec's column table with PRAGMA table_info on a new store, and checks its format row reads version 1;
  • a store naming another version, or none, fails open() with FormatMismatchError and releases the lock;
  • a store in another layout is refused before anything is written to it;
  • a create whose lazy owner throws leaves no file and no lock, and a later ifMissing or exclusive open creates the store.
• A Durable Object test for importRecord(), including that a write failing partway inside transactionSync leaves no row behind. The DO suite also creates stores through openStore(), which runs writeNewStore()'s DDL inside transactionSync.

Notes for reviewers

• APIAdapter can't be a copy source yet. It has no listBlobs(), because the wire lists no blobs, so copying out of a server-backed stack is refused. Test copying a stack out of an APIAdapter #471 now covers the wire endpoint and APIAdapter.listBlobs() as well as the round-trip test.
• The adapter's cached identity. Every adapter still reads ownerEntityId and timezone once at open(), so adapter.timezone, and stack.timezone, go stale after a _config patch until the store is reopened. That predates this PR. The copy no longer depends on it, since it reads _config itself.
• Wire version: the discovery field rename is a breaking wire change, which WIRE_PROTOCOL_VERSION's rule would make a major bump. It stays 1.0, as it has through earlier breaking changes, because nothing is installed yet.
• A database another program made holds no format table, so open() treats it as missing, and ifMissing or exclusive would add a store's tables to it. Telling such a file apart would need a rule about tables the stack doesn't own, which this PR doesn't add.
• Durable Objects: the DO adapter isn't run through runCopyConformance(), because it sits behind RPC. Its own risk, that importRecord runs inside transactionSync, has a dedicated test. Everything else is the SQLite code Local's copy suite already runs.
• Deliberate out-of-contract input: the SQLite and DO rollback tests pass two snapshots at the same version. It's the only way to make the engine fail after the record row is written; a comment on each test says so.
• History read orders: getVersions() returns newest first and getJournal() oldest first. That predates this PR and nothing here depends on it, since RecordHistory is keyed. Whether the two should match is Decide whether version history and the journal read in one order #472.
• The issue's third action (the "leaving never needs permission" design rule, and moving hosts in the trust model) belongs to Add trust, defaults, reversibility and formats to the existing design rules #421 and Spec: a trust model page #418, which create those documents; it's left for them once this lands.
• Changesets: portable-copy (minor for core, both SQLite record adapters, adapter-local, adapter-api and adapter-conformance) and owner-entity-id (minor for core, wire-types, conformance-fixtures, adapter-api and both SQLite record adapters).

🤖 Generated with Claude Code

https://claude.ai/code/session_01N8msm9Vp1KhFthR6Pyf2Jz

[changeset-bot]

🦋 Changeset detected

Latest commit: 817b6eb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@haverstack/core	Minor
@haverstack/wire-types	Minor
@haverstack/conformance-fixtures	Minor
@haverstack/adapter-api	Minor
@haverstack/record-adapter-sqlite	Minor
@haverstack/record-adapter-do-sqlite	Minor
@haverstack/adapter-local	Minor
@haverstack/adapter-conformance	Minor
@haverstack/blob-adapter-disk	Patch
@haverstack/blob-adapter-s3	Patch
@haverstack/commons	Patch

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