Skip to content

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 GitSheets class (backend/lib/GitSheets.js) — early-prototype API. Replaced by Repository + 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/e2e Cypress) — 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.
  • deepmerge for --patch-existing — replaced by RFC 7396 JSON Merge Patch (Sheet.patch(query, partial)).

What’s reshaped

  • gitsheets is now a single npm package at the repo root (was backend/).
  • TypeScript-first, ESM-only. "type": "module". Node ≥ 20 or Bun ≥ 1.
  • [gitsheet.fields] config moves to [gitsheet.schema] (JSON Schema). The sort rules stay where they are. See the migrating-config recipe.
  • Errors are typed classes. No more string-matching on err.message. See api/errors.md for 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 through repo.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 import instead of CommonJS require
  • openRepo (factory) instead of new GitSheets() + await gs.init()
  • openSheet instead of getSheet (factory consistency)
  • Bundle multiple upserts into one transaction with repo.transact — same shape, atomic, one commit
  • queryFirst is 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 / default move to [gitsheet.schema.properties.<name>]
  • sort stays at [gitsheet.fields.<name>.sort] (different concept — canonical normalization)
  • trueValues / falseValues move 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 core
  • git sheet edit <sheet> <path> — new in v1.1: $EDITOR-based round-trip on a record
  • git sheet init <sheet> — new in v1.1: scaffold a starter .gitsheets/<sheet>.toml
  • git 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: null deletes, arrays replace)
  • --format (json|toml|csv upsert; json|csv|tsv|toml query/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 .md files with TOML frontmatter and a designated body field. Bodies are normalized through markdownlint --fix on write; the frontmatter stays canonical TOML. Default remains TOML — existing sheets are unchanged. See behaviors/content-types.md and the Markdown CMS recipe.
  • Lazy body loading. Sheet.query / queryFirst / queryAll accept opts.withBody (default true). Setting withBody: false on a markdown sheet skips body bytes entirely — useful for listing pages and bulk metadata reads. Hydrate on demand with await 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?). Adds opts.allowMissingBody for 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.patch handles { body: null } deletions transparently (it passes allowMissingBody: true to 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 when changed: false. Throws the same errors upsert would.
  • 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 enforces record.title === <body's first H1, or undefined> on every write — upsert with disagreeing values throws ValidationError; Sheet.patch({title: 'X'}) rewrites the body’s H1 for you, Sheet.patch({body: '# Y\n…'}) re-derives the title. Markdownlint’s MD041 auto-enables to fail loud on bodies that start with prose. Fully backward-compatible — sheets without [gitsheet.format].title behave exactly as v1.2. See behaviors/content-types.md and 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. See docs/axi.md. Install with npm install -g gitsheets-axi.

Repository layout (no consumer impact)

  • The repository was promoted to an npm workspaces monorepo. The published gitsheets package now lives at packages/gitsheets/; the agent-facing companion at packages/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 called deleteChild for every entry — fine at sheet sizes of a few hundred records, problematic at tens of thousands. The new implementation uses hologit’s TreeObject.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#finalize now 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 for upsert(record) where the record’s canonical bytes match what’s on disk, and delete + re-upsert of 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 pair markMutated with an actual mutation, so this shouldn’t affect any real consumer. Consumers who genuinely want empty commits should use git commit --allow-empty outside the library.

Dependency

  • hologit bumped from ^0.49.1 to ^0.50.2 to pick up TreeObject.clearChildren() (the O(1) primitive backing the new Sheet#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.hologitRepo no 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):

  1. Integer digit-group underscores drop — legacyId = 31_618 → legacyId = 31618 (the dominant class).
  2. String requote — strings containing both " and ' move from escaped single-line form to readable triple-quoted """…""" form.
  3. 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. delete then upsert is not a rename and never was.
  • tx.writeFile / tx.deleteFile are public; transact({ parent: null }) opens an orphan root commit; branch may 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 size and stream() everywhere; repo.readBlob(ref, path); streaming is in-core up to 1 MiB and piped from git cat-file above that. AttachmentBlobHandle is now an alias of BlobHandle.
  • 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 the git sheet merge-driver: record-level 3-way merge with canonical output.
  • Markdown sheets accept an explicit null body without allowMissingBody (absent/undefined still throws).
  • Python binding (gitsheets 0.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(), and new Date() with no arguments throw. In a path expression that is PathTemplateError (path_render_failed) on write or query; in a comparator it is ConfigError (config_invalid) on write or normalizeRecord. Both name the expression or field and the forbidden call.
  • Local-time Date methods read UTC on every host: getHours(), getDate(), getFullYear(), getTimezoneOffset() (always 0), toString(), and the multi-argument new 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, and Date.parse keep working. Strings parse only as ISO 8601 (exactly three fraction digits) or the toString() / toUTCString() forms; anything else is NaN.
  • Locale methods are locale-free in a comparator or template: a.localeCompare(b) is plain code-unit order ('a'.localeCompare('B') is 1), Number#toLocaleString() is String(n), and there is no Intl. A comparator that relied on localeCompare for human ordering should use sort = true (ICU collation) instead. On Node, normalizeRecord used 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 / pathForRecord used to stringify it with Date#toString(), whose : made the render throw PathTemplateError (path_invalid_chars); it now throws PathTemplateError (path_render_failed), as a write always did. Use a date bucket or an expression such as ${{ publishedAt.toISOString().slice(0, 10) }}.
  • A bigint outside 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 null array element, a bigint outside i64 — make Template.render / pathForRecord throw PathTemplateError (path_render_failed) and normalizeRecord throw ValidationError (validation_failed), even when the template or sort rules don’t touch that field. Before, the field was ignored.
  • normalizeRecord returns the core’s value: a fresh plain object with null / undefined keys removed (at every depth), class instances flattened to plain objects, bigints within ±(2^53−1) as numbers, and new Date objects. Before, it kept your values and nulls as they were.
  • sort = true order in normalizeRecord comes from the core’s pinned ICU collator (as on write) rather than the host’s localeCompare. They agree for ordinary input; if your Node’s ICU differs from the pinned one, normalizeRecord now follows the bytes you commit.
  • Comparators in normalizeRecord run in the core’s stable insertion sort instead of V8’s Array#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 renders 1970/01/01. Validate dates before writing; this marshalling is a known bug and will become an error.
  • normalizeRecord(null) (or undefined) throws ValidationError (validation_failed); it used to return {}.
  • Snippet error messages are one line. A path expression or comparator that throws now reports Kind: message for an Error (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.
  • queryTree drops function-valued query entries (they never pruned), and a query holding another value the core can’t represent throws PathTemplateError (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:

If you hit something the migration guide doesn’t cover, open an issue — likely a missing migration note, possibly an actual gap.