Migrating from pre-v1.0 ¶
If you’ve been running a pre-v1.0 internal install, here’s what changes and how to update.
What’s removed entirely ¶
- The
GitSheetsclass (backend/lib/GitSheets.js) — early-prototype API. Replaced byRepository+Sheet+Transaction. - The HTTP server (
backend/server.js) — Koa-based REST surface. The library no longer ships an HTTP layer; build your own with Fastify / Koa / Express / Hono and call the JS API. - The Vue frontend (
src/*Vue,tests/e2eCypress) — demo UI. If you need a UI, build it as a separate consumer. - CSV-ingest commands (
backend/commands/singer-target.js) — Singer target. Not in the v1.0 surface. deepmergefor--patch-existing— replaced by RFC 7396 JSON Merge Patch (Sheet.patch(query, partial)).
What’s reshaped ¶
gitsheetsis now a single npm package at the repo root (wasbackend/).- TypeScript-first, ESM-only.
"type": "module". Node ≥ 20 or Bun ≥ 1. [gitsheet.fields]config moves to[gitsheet.schema](JSON Schema). Thesortrules stay where they are. See the migrating-config recipe.- Errors are typed classes. No more string-matching on
err.message. Seeapi/errors.mdfor the hierarchy + stable codes.
API translation table ¶
| Pre-v1.0 | v1.0 |
|---|---|
new GitSheets({ gitDir }) |
await openRepo({ gitDir }) |
gitsheets.getSheet(name) |
await repo.openSheet(name) |
sheet.upsert(record) |
sheet.upsert(record) (same name, now goes through a transaction) |
sheet.delete(query) |
sheet.delete(query) (same name) |
sheet.query(filter) |
sheet.query(filter) async iterator (same name) |
sheet.commit(message) |
repo.transact({ message }, async tx => { await tx.sheet(...).upsert(...) }) |
--patch-existing (CLI, deepmerge) |
--patch (CLI, RFC 7396 — semantic change: null deletes, arrays replace) |
HTTP POST /sheets/:name |
Your own HTTP layer + sheet.upsert(...) |
Permissive vs strict mode ¶
Pre-v1.0, every upsert mutated the working tree and required an explicit commit() to make changes durable. v1.0 inverts this:
- Permissive default — standalone
sheet.upsert(record)auto-opens a transaction with an auto-generated commit message. Simple scripts just work. - Strict mode — call
repo.requireExplicitTransactions()to require every write to go throughrepo.transact. Useful when you want every commit to carry intentional metadata (author, message, trailers).
// Permissive (default)
await sheet.upsert({ slug: 'jane', email: 'jane@x.org' });
// → commits with message "users upsert"
// Strict
repo.requireExplicitTransactions();
await sheet.upsert({ slug: 'jane', email: 'jane@x.org' });
// ✗ throws TransactionError('transaction_required')
await repo.transact({ message: 'add jane' }, async (tx) => {
await tx.sheet('users').upsert({ slug: 'jane', email: 'jane@x.org' });
});
// ✓
For production / request-bound flows, prefer strict mode + explicit repo.transact — see the request-bound transactions recipe.
A worked translation ¶
Pre-v1.0 ¶
const { GitSheets } = require('gitsheets');
const gs = new GitSheets({ gitDir: '/data/.git' });
await gs.init();
const users = await gs.getSheet('users');
await users.upsert({ slug: 'jane', email: 'jane@x.org' });
await users.upsert({ slug: 'bob', email: 'bob@x.org' });
await users.commit('add users');
const found = await users.queryFirst({ slug: 'jane' });
v1.0 ¶
import { openRepo } from 'gitsheets';
const repo = await openRepo({ gitDir: '/data/.git' });
const users = await repo.openSheet('users');
await repo.transact(
{ message: 'add users' },
async (tx) => {
const s = tx.sheet('users');
await s.upsert({ slug: 'jane', email: 'jane@x.org' });
await s.upsert({ slug: 'bob', email: 'bob@x.org' });
},
);
const found = await users.queryFirst({ slug: 'jane' });
Differences:
- ESM
importinstead of CommonJSrequire openRepo(factory) instead ofnew GitSheets()+await gs.init()openSheetinstead ofgetSheet(factory consistency)- Bundle multiple upserts into one transaction with
repo.transact— same shape, atomic, one commit queryFirstis unchanged
Validation reshape ¶
If you had [gitsheet.fields] configs, see the migrating-config recipe for the field-by-field migration. The short story:
type/enum/defaultmove to[gitsheet.schema.properties.<name>]sortstays at[gitsheet.fields.<name>.sort](different concept — canonical normalization)trueValues/falseValuesmove to your CSV ingest code (no longer a sheet-config concern)
Error handling ¶
Pre-v1.0 you might have done:
try {
await users.upsert(record);
} catch (err) {
if (err.message.startsWith('invalid tree ref')) { /* ... */ }
}
v1.0:
import { GitsheetsError, ValidationError, RefError } from 'gitsheets';
try {
await users.upsert(record);
} catch (err) {
if (err instanceof ValidationError) {
// err.issues — structured ValidationIssue[]
} else if (err instanceof RefError) {
// err.code === 'ref_not_found' | 'not_an_ancestor'
} else if (err instanceof GitsheetsError) {
// err.code — stable string
// err.status — HTTP status hint
} else {
throw err;
}
}
Every gitsheets error extends GitsheetsError and carries a stable code. See specs/api/errors.md for the full hierarchy + code table.
CLI changes ¶
git sheet upsert/query/read/normalize— same command shape, rebuilt against the new coregit sheet edit <sheet> <path>— new in v1.1:$EDITOR-based round-trip on a recordgit sheet init <sheet>— new in v1.1: scaffold a starter.gitsheets/<sheet>.tomlgit sheet infer <sheet>/migrate-config <sheet>— new in v1.1: schema inference and pre-v1.0 fields-config migration--patch-existing→--patch(RFC 7396 semantics:nulldeletes, arrays replace)--format(json|toml|csvupsert;json|csv|tsv|tomlquery/read),--encoding,--delete-missing,--attachment <name>=<source>— all shipped in v1.1--prefix(GITSHEETS_PREFIX) for multi-tenant sub-tree scoping- New global flags:
--message,--author-name,--author-email,--trailer Key=Value,--ref,--commit-to - Exit codes are stable from v1.0 onward — see CLI reference
--working(read/write the working tree state) remains deferred — tracked at #165
v1.1 → v1.2 ¶
Fully additive minor release. Existing v1.1 code keeps working.
Library ¶
- Content-typed records. A sheet can opt into
[gitsheet.format] type = 'markdown'(or'mdx') to store records as.mdfiles with TOML frontmatter and a designated body field. Bodies are normalized throughmarkdownlint --fixon write; the frontmatter stays canonical TOML. Default remains TOML — existing sheets are unchanged. Seebehaviors/content-types.mdand the Markdown CMS recipe. - Lazy body loading.
Sheet.query/queryFirst/queryAllacceptopts.withBody(defaulttrue). SettingwithBody: falseon a markdown sheet skips body bytes entirely — useful for listing pages and bulk metadata reads. Hydrate on demand withawait sheet.loadBody(record). Index builds always use body-less reads (don’t index on body content). No effect on TOML sheets. Sheet.upsert(record, opts?). Addsopts.allowMissingBodyfor content-typed sheets — explicit opt-in to upsert a record without a body field. Default behavior throws if the body field is missing, so a body-less upsert can’t silently erase on-disk content.Sheet.patchhandles{ body: null }deletions transparently (it passesallowMissingBody: trueto the internal upsert).- New public types:
Format,FormatConfig,UpsertOptions.
CLI ¶
gitsheets check <sheet> <file> [--fix]— new. Verify a record file in the working tree is parseable, schema-valid, and canonical. With--fix, rewrite to canonical. Never commits. Designed for post-edit hooks (--fix) and CI pre-commit verification (no--fix). Exit codes: 0 ok, 1 not-canonical (no--fix), 22 ValidationError, 64 ConfigError.gitsheets query --no-body— new flag. For content-typed sheets, suppresses the body field in output. No effect on TOML sheets.
Tooling ¶
skills/gitsheets/— bundled Claude Code skill for developers consuming gitsheets. Reference material covering the CLI, the TypeScript API, and the sheet config syntax. Install it in your.claude/skills/(or via plugin) to give Claude focused gitsheets context.
v1.2 → v1.3 ¶
Fully additive minor release. Existing v1.2 code keeps working.
Library ¶
Sheet.willChange(record, opts?)— new in v1.3.0. Pre-flight idempotency check that runs upsert’s full validation + normalization + serialization pipeline and compares the resulting bytes to the existing blob at the rendered path — without mutating the tree. Returns{ changed, path, currentBlobHash?, nextText }. Consumers that want commit-skipping semantics (“only commit if something actually changed”) can pre-flight + skip whenchanged: false. Throws the same errorsupsertwould.- Title from body’s H1. Content-typed sheets can opt into
[gitsheet.format].title = '<field>'to denormalize the body’s first H1 into a frontmatter field. The library enforcesrecord.title === <body's first H1, or undefined>on every write —upsertwith disagreeing values throwsValidationError;Sheet.patch({title: 'X'})rewrites the body’s H1 for you,Sheet.patch({body: '# Y\n…'})re-derives the title. Markdownlint’sMD041auto-enables to fail loud on bodies that start with prose. Fully backward-compatible — sheets without[gitsheet.format].titlebehave exactly as v1.2. Seebehaviors/content-types.mdand the Markdown CMS recipe. - New utility exports:
parseToml,parseConfigToml,stringifyRecord(TOML round-tripping),getFormat,hasFormat,registerFormat,resolveFormatConfig(format dispatch). All were already in the package’s internal modules; v1.3 surfaces them at the package root for consumers who need raw-bytes round-tripping or custom format registration. - New public type:
WillChangeResult.
Tooling ¶
gitsheets-axi— new sibling npm package. Agent-facing CLI with TOON output, idempotent mutations, self-installing session hooks (Claude Code + Codex), format-aware default schemas. Lockstep-versioned with the library on minor. Seedocs/axi.md. Install withnpm install -g gitsheets-axi.
Repository layout (no consumer impact) ¶
- The repository was promoted to an npm workspaces monorepo. The published
gitsheetspackage now lives atpackages/gitsheets/; the agent-facing companion atpackages/gitsheets-axi/. Consumer code is unaffected —import { ... } from 'gitsheets'resolves the same surface as before, and the published tarball has the same shape.
CLI ¶
No new commands on the human gitsheets CLI in v1.3. The agent-facing operations (TOON output, idempotent mutations) live in gitsheets-axi rather than as flags on the human CLI — the two contracts disagree on too many defaults to coexist in one binary.
v1.3.0 → v1.3.1 ¶
Patch release. Two fixes in service of snapshot-importer-style workflows.
Library ¶
Sheet.clear()is now O(1). Previously walked the sheet’s subtree and calleddeleteChildfor every entry — fine at sheet sizes of a few hundred records, problematic at tens of thousands. The new implementation uses hologit’sTreeObject.clearChildren()(added in hologit 0.50.2) to point the subtree at git’s empty-tree hash in constant time. Same observable behavior; existing code unchanged.-
No-op transactions no longer produce empty commits.
Transaction#finalizenow compares the resulting tree-hash to the parent commit’s tree-hash; equality means the staged state matches the parent and no commit is created. Concretely, every “clear + re-upsert from snapshot” pattern against unchanged upstream data is now a clean no-op (commitHash === null). Same goes forupsert(record)where the record’s canonical bytes match what’s on disk, anddelete+ re-upsertof an identical record.Subtle behavior change: an explicit
tx.markMutated()call that isn’t paired with a real tree mutation no longer produces a commit. Internal callers (upsert/delete/setAttachments/etc.) always pairmarkMutatedwith an actual mutation, so this shouldn’t affect any real consumer. Consumers who genuinely want empty commits should usegit commit --allow-emptyoutside the library.
Dependency ¶
hologitbumped from^0.49.1to^0.50.2to pick upTreeObject.clearChildren()(the O(1) primitive backing the newSheet#clear()).
v1.x → v2.0 (the Rust core) ¶
v2.0 replaces the Node.js engine with the Rust gitsheets-core crate: TOML
parse/serialize, normalization, validation, path templates, record CRUD, and
the tree/blob/commit substrate all run natively, and the npm package becomes a
thin marshalling shell over the @gitsheets/core-napi addon. The API surface
is intentionally unchanged — but three behavior changes bite real consumers.
All three surfaced during the first production 1.4.1 → 2.x upgrade; this
section is what turns “16 mystery test failures” into “read the section, apply
3 changes.”
1. The hologit dependency is gone ¶
2.x drops hologit entirely (tree/blob/commit ops run on holo-tree/gitoxide
inside the core). Anything that reached into it breaks:
repo.hologitRepono longer exists.BlobObject(e.g.BlobObject.write) is no longer importable via gitsheets.
The replacement for the common pattern — hashing binary content and attaching it to a record — is the built-in blob primitive plus the attachment API:
// 1.x
import { BlobObject } from 'hologit';
const blob = await BlobObject.write(repo.hologitRepo, buffer);
await sheet.setAttachments(record, { 'avatar.jpg': blob });
// 2.x
const blob = await repo.writeBlob(buffer); // Promise<BlobHandle>
await sheet.setAttachments(record, { 'avatar.jpg': blob });
repo.writeBlob(buf) hashes the bytes into the object database and returns a
BlobHandle accepted everywhere a hologit BlobObject used to be
(setAttachment, setAttachments). getAttachment/getAttachments/
sheet.attachments() likewise return BlobHandles with .read()/.stream().
2. null/undefined-valued fields ¶
TOML has no null, so a cleared optional field and a never-set field are the
same on-disk state: an absent key. 1.x (@iarna/toml) enforced this by
silently dropping null-valued keys at serialize time. The initial 2.x
releases instead threw on marshal (cannot marshal JS value of type
Null/Undefined to a TOML value) — breaking the standard consumer pattern of
.nullable().optional() schemas with ?? null normalization on write.
Fixed in this release: the 1.x drop semantics are restored and now
specced (specs/behaviors/normalization.md).
A null/undefined-valued key is dropped, recursively (top-level fields,
nested tables, and objects inside arrays), before validation and
serialization — byte-identical to 1.x output, in every binding (Node and
Python). If you shimmed this with a stripNullish helper at your write
boundary, you can delete it.
One deliberate edge-case divergence from 1.x: a null/undefined array
element is an error naming the index (1.x silently dropped elements —
[1, null, 2] → [1, 2] — which shifts sibling indices and silently changes
data). Remove the element yourself if that’s what you mean. A required field
set to null fails JSON-Schema validation as missing, same as 1.x.
3. Canonical bytes re-baseline (one-time) ¶
The canonical serializer is now the core’s gitsheets-core::canonical (the
Rust toml crate’s formatting over a deep key sort), replacing @iarna/toml.
A record that was already canonical under 1.x may re-serialize to different —
but value-identical — bytes, once (#196).
Three reformat classes, all proven data-lossless and idempotent over a
~29.5k-record corpus (PR #205):
- Integer digit-group underscores drop —
legacyId = 31_618→legacyId = 31618(the dominant class). - String requote — strings containing both
"and'move from escaped single-line form to readable triple-quoted"""…"""form. - Multiline trailing-quote layout — a multiline string ending in
"loses@iarna’s line-continuation dance (same value, fewer lines).
Until you re-baseline, the first 2.x write of a record whose 1.x bytes fall in one of these classes shows a spurious-looking (but value-neutral) diff. The recommended migration is a one-time re-serialize commit over each existing repo, which is idempotent (a second run produces zero diff — that’s the adoption check):
# Re-normalize every *.toml record under a directory, in place.
cargo run -p gitsheets-core --example normalize_tree -- path/to/records
git add path/to/records
git commit -m "chore: re-baseline records to the Rust canonical form"
# Verify idempotence — a second pass must report 0 files re-normalized:
cargo run -p gitsheets-core --example normalize_tree -- path/to/records
(Or use git sheet normalize <sheet> per sheet from the CLI.) See the
canonical-form re-baseline notes
for the full contract.
v2.7 → v2.9 ¶
Two minor releases shipped together: 2.8.0 (eight consumer-filed features) and 2.9.0 (one removal). One check and one removal can stop a sheet from opening; everything else is additive.
1. A path template may only name schema-required fields (2.8.0) ¶
When a sheet has a persisted schema ([gitsheet.schema], declared contracts, or both), openSheet now fails with ConfigError('config_invalid') if a static template field — ${{ f }}, ${{ f/** }}, or a date bucket’s base field — is not in a top-level required list of the local schema or a declared contract. Expression components are exempt; schemaless sheets are not checked. The fix is one line per sheet:
[gitsheet.schema]
required = ['projectSlug', 'slug'] # every static template field
Why: a record missing a template field can never be stored (path_render_failed on every upsert, aborting the transaction), so a template on an optional field is a config bug the check now catches at open instead of on the first write. infer and migrate-config write template fields into required for you.
2. injectedFields is gone (2.9.0, breaking relative to 2.8.0) ¶
2.8.0 shipped a [gitsheet].injectedFields list exempting “writer-supplied” fields from that check. 2.9.0 removes it: a config still carrying the key fails to open with an error naming it. The principle — a record carries every field needed to render its path — is in specs/principles.md. A field your service used to splice in before the upsert (a tenant key, a parent’s slug) belongs on the record and in required; when a child’s path is keyed by its parent’s handle, that handle is the reference to the parent.
3. Additive (2.8.0) ¶
- Rename moves attachments. An upsert whose rendered path changes (the loaded record with its new key) moves the attachment directory too.
deletethenupsertis not a rename and never was. tx.writeFile/tx.deleteFileare public;transact({ parent: null })opens an orphan root commit;branchmay name a branch that does not exist yet.- Ref-pinned sheets:
openSheet(name, { ref }),openSheets({ ref }),openStore(repo, { ref })— read-only, never auto-refreshed. - Blob handles carry
sizeandstream()everywhere;repo.readBlob(ref, path); streaming is in-core up to 1 MiB and piped fromgit cat-fileabove that.AttachmentBlobHandleis now an alias ofBlobHandle. repo.sync()brings a branch up to date with a remote other writers push to;repo.isAncestor(a, b).repo.merge(),git sheet merge, and thegit sheet merge-driver: record-level 3-way merge with canonical output.- Markdown sheets accept an explicit
nullbody withoutallowMissingBody(absent/undefinedstill throws). - Python binding (
gitsheets0.4.0 / 0.5.0 on PyPI):transact(orphan=),write_file/delete_file,blob_header,sync_branch/is_ancestor,merge_sheets/merge_record_texts.
v2.9 → v2.12 ¶
Everything in 2.12.0 is additive; nothing stops a sheet from opening. Three new capabilities and the knobs that come with them:
1. Default-branch binding and submodule mode ¶
openRepo({ branch }), GITSHEETS_BRANCH, or git config gitsheets.branch binds a repository to a branch other than HEAD’s: live sheets read it, transactions commit to it, refresh / sync / the push daemon / merge / tag default to it. openRepo({ submodule }) (GITSHEETS_SUBMODULE, gitsheets.submodule) opens a data submodule whose HEAD is the superproject’s pointer; git sheet submodule init sets one up with no record checkout. The CLIs take --branch / --submodule; --ref now defaults to the resolved binding, which is HEAD when nothing is configured, so existing invocations behave as before. git sheet init accepts --commit (the explicit spelling of what it always did). New error codes: TransactionError sheet_derived and pointer_stage_failed; a tag, commit, or remote-only name as the binding is ConfigError config_invalid. Recipe: headless data.
2. Aggregation ¶
sheet.aggregate(filter, aggregates), git sheet aggregate --agg name=form[:field] [--group-by f], gitsheets-axi aggregate, and Python record_aggregate: count / sum / min / max / avg / distinct with where and groupBy, plus a reduce escape hatch that runs in the core’s deterministic engine. Failures are AggregationError (aggregation_failed). gitsheets-axi query --group-by is unchanged.
3. Rollup sheets ¶
A sheet config with [gitsheet.rollup] from = '<source>' and a path that is a prefix of the source’s template is a derived, read-only sheet: one record per partition, regenerated by every gitsheets commit that touches the partition (transactions, merge, sync replays) and stamped with sourceTree and configTree so a stale record is recomputed on read. sheet.materialize() / git sheet rollup [--check] repair after plain-git writes; writes to a rollup sheet are sheet_derived. Recipe: rollups.
Python binding (gitsheets 0.7.0 on PyPI): record_aggregate, record_query(sheet=, stale=), rollup_status, Transaction.materialize_rollups; the commit-time rollup pass runs inside transact with no Python-side work.
v2.12 → v2.13 ¶
Definition snippets run in a deterministic realm ¶
Path-template expression components (${{ … }}) and raw-JS sort comparators ([gitsheet.fields.<f>] sort = '<js body>') now run under the same rule aggregate reduce / finalize snippets already did (rust-core.md § Determinism rule), in the core and in the Node Template / normalizeRecord path alike:
Math.random(),Date.now(),Date(), andnew Date()with no arguments throw. In a path expression that isPathTemplateError(path_render_failed) on write or query; in a comparator it isConfigError(config_invalid) on write ornormalizeRecord. Both name the expression or field and the forbidden call.- Local-time
Datemethods read UTC on every host:getHours(),getDate(),getFullYear(),getTimezoneOffset()(always0),toString(), and the multi-argumentnew Date(y, m, d, …)constructor. An offset-less ISO date-time string ('2026-01-01T05:00') parses at UTC.toLocaleString()/toLocaleDateString()/toLocaleTimeString()throw. new Date(ms),new Date(isoString),Date.UTC, andDate.parsekeep working. Strings parse only as ISO 8601 (exactly three fraction digits) or thetoString()/toUTCString()forms; anything else isNaN.- Locale methods are locale-free in a comparator or template:
a.localeCompare(b)is plain code-unit order ('a'.localeCompare('B')is1),Number#toLocaleString()isString(n), and there is noIntl. A comparator that relied onlocaleComparefor human ordering should usesort = true(ICU collation) instead. On Node,normalizeRecordused to apply the host’s locale here while the write path did not, so the two could disagree; they now match. - Query predicates (
{"$pred": …}) and index key snippets are not covered: they keep the clock, though local time there is also UTC.
Who is affected: any sheet whose template or comparator reads the clock, randomness, or host local time. A template that called getFullYear(), getMonth(), getHours(), etc. on a datetime field and ran on a host whose time zone is not UTC rendered paths in that zone; it now renders them at UTC, so records written that way may now live at a path the template no longer produces (for a date near midnight, or always for an hour bucket). On a UTC host nothing moves. A template or comparator using Date.now() / Math.random() was never reproducible and now fails loudly.
Fix: spell the accessor you mean in UTC (getUTCFullYear(), getUTCHours()), or better, use the declarative date-bucket form (${{ publishedAt: YYYY/MM }}), which has always rendered at UTC. Then run git sheet normalize <sheet> once: it re-upserts every record through the current template in a single commit, so any record whose rendered path changed shows up there as a rename you can review. Derive anything time-based from a record field rather than the clock.
v2.13 → v2.14 ¶
Template and normalizeRecord run in the core ¶
The exported Template (render, queryTree), and so sheet.pathForRecord, and sheet.normalizeRecord now call the core — the same renderer and normalizer a write uses — instead of evaluating snippets in a Node node:vm realm. What they return is now exactly what an upsert of the same record commits. Most records see no difference; these do:
- A bare datetime field in a path (
${{ publishedAt }}) fails with a different code:Template.render/pathForRecordused to stringify it withDate#toString(), whose:made the render throwPathTemplateError(path_invalid_chars); it now throwsPathTemplateError(path_render_failed), as a write always did. Use a date bucket or an expression such as${{ publishedAt.toISOString().slice(0, 10) }}. - A
bigintoutside i64 in a path field is a render failure (path_render_failed); it used to render its digits. Writes already rejected it. - Records the core can’t represent — a function or symbol value anywhere in the record, a
nullarray element, abigintoutside i64 — makeTemplate.render/pathForRecordthrowPathTemplateError(path_render_failed) andnormalizeRecordthrowValidationError(validation_failed), even when the template or sort rules don’t touch that field. Before, the field was ignored. normalizeRecordreturns the core’s value: a fresh plain object withnull/undefinedkeys removed (at every depth), class instances flattened to plain objects,bigints within ±(2^53−1) asnumbers, and newDateobjects. Before, it kept your values and nulls as they were.sort = trueorder innormalizeRecordcomes from the core’s pinned ICU collator (as on write) rather than the host’slocaleCompare. They agree for ordinary input; if your Node’s ICU differs from the pinned one,normalizeRecordnow follows the bytes you commit.- Comparators in
normalizeRecordrun in the core’s stable insertion sort instead of V8’sArray#sort. A consistent comparator gives the same order; an inconsistent one now gives the order a write gives. - An invalid
Date(new Date(NaN)) crosses into the core as the epoch,1970-01-01T00:00:00Z— what a write already stored for it. A date-bucket template that used to fail on it now renders1970/01/01. Validate dates before writing; this marshalling is a known bug and will become an error. normalizeRecord(null)(orundefined) throwsValidationError(validation_failed); it used to return{}.- Snippet error messages are one line. A path expression or comparator that throws now reports
Kind: messagefor anError(failed: TypeError: Date.now() is not available …) or the thrown value itself (throw "nope"→failed: "nope"), with no source position or stack frames. The error class and code are unchanged; match on those, not the message. queryTreedrops function-valued query entries (they never pruned), and a query holding another value the core can’t represent throwsPathTemplateError(path_render_failed).
The sort-keys dependency is gone.
Float path segments render as JavaScript does (write path) ¶
A path field holding a float (a TOML float, or a Python float; a JS number with an integral value within ±(2^53−1) is an integer and is unaffected) now renders exactly as JavaScript’s String(x) — on write, pathForRecord, and queries, in every binding. Before, the core cast integral floats to a 64-bit integer, which saturated: 1e19 and 1e20 both rendered 9223372036854775807, so two records could silently land in the same file. Changes:
| Float value | Was | Now |
|---|---|---|
1e19 |
9223372036854775807 |
10000000000000000000 |
1e20 |
9223372036854775807 |
100000000000000000000 |
2**60 |
1152921504606846976 |
1152921504606847000 |
-1e20 |
-9223372036854775808 |
-100000000000000000000 |
1e21 |
1000000000000000000000 |
1e+21 |
1e-7 |
0.0000001 |
1e-7 |
5e-324 |
0.000…0005 (324 digits) |
5e-324 |
Infinity |
inf |
Infinity |
Ordinary floats (1.5, 2026.0, 0.1) render as before. Who is affected: a sheet whose path template references a float field holding an integral value of magnitude 2^53 or more, a value of 1e21 or more, a nonzero value below 1e-6, or an infinity. Such records may now live at a path the template no longer renders. Fix: run git sheet normalize <sheet> once; records whose path changed show up as renames in that commit (and any that had collided were already overwritten — check history if you stored such values).
Going forward ¶
Once migrated, the recipes are the fastest path to common patterns:
- Typed sheet with Zod
- Request-bound transactions in Fastify
- Secondary indices
- Production push daemon
- Headless data
- Rollups
If you hit something the migration guide doesn’t cover, open an issue — likely a missing migration note, possibly an actual gap.