gitsheets 1.0.5 → 1.2.0

package/dist/sheet.js

@@ -1,13 +1,18 @@
 // Sheet — typed handle to one declared sheet in a Repository.
 // See specs/api/sheet.md and specs/concepts.md.
+import { execFile, spawn } from 'node:child_process';
 import { runInNewContext } from 'node:vm';
-import { ConfigError, IndexError, NotFoundError, PathTemplateError, TransactionError, } from './errors.js';
+import { promisify } from 'node:util';
+import { createPatch as rfc6902CreatePatch } from 'rfc6902';
+import { ConfigError, IndexError, NotFoundError, PathTemplateError, RefError, TransactionError, } from './errors.js';
 import { mergePatch } from './patch.js';
 import { Template } from './path-template/index.js';
-import { stringifyRecord, parseToml, parseConfigToml } from './toml.js';
+import { parseConfigToml } from './toml.js';
 import sortKeys from 'sort-keys';
 import { transactionContext } from './transaction.js';
 import { validateRecord, } from './validation.js';
+import { getFormat, resolveFormatConfig } from './format/index.js';
+const exec = promisify(execFile);
 export const RECORD_SHEET_KEY = Symbol.for('gitsheets-sheet');
 export const RECORD_PATH_KEY = Symbol.for('gitsheets-path');
 // --- Helpers ---
@@ -131,7 +136,31 @@ async function loadConfig(workspace, configPath) {
         }
         schema = schemaRaw;
     }
-    const config = { root, path, fields: fieldsClean, schema };
+    let format;
+    try {
+        format = resolveFormatConfig(gitsheet['format']);
+    }
+    catch (err) {
+        throw new ConfigError('config_invalid', `${configPath}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    // Body-field collision: a sheet whose path template references the body
+    // field would render the same key for a record regardless of body content.
+    if (format.body !== undefined) {
+        if (format.type !== 'markdown' && format.type !== 'mdx') {
+            throw new ConfigError('config_invalid', `${configPath}: [gitsheet.format].body only applies to markdown/mdx formats`);
+        }
+        // Static check: the path template's getFieldNames must not include the
+        // body field. Tested against the registered field name only — expressions
+        // referencing body are caught lazily during render.
+        const fieldNames = Template.fromString(path).getFieldNames();
+        if (fieldNames.includes(format.body)) {
+            throw new ConfigError('config_invalid', `${configPath}: [gitsheet.format].body = ${JSON.stringify(format.body)} collides with the path template — the body field cannot also identify the record`);
+        }
+    }
+    else if (format.type === 'markdown' || format.type === 'mdx') {
+        throw new ConfigError('config_invalid', `${configPath}: [gitsheet.format].body is required when type is "markdown" or "mdx"`);
+    }
+    const config = { root, path, fields: fieldsClean, schema, format };
     CONFIG_CACHE.set(node.hash, config);
     return config;
 }
@@ -163,15 +192,178 @@ function validateSortRule(sort, configPath, field) {
 // cache the TOML *text* (not the parsed object) so each reader gets a fresh
 // parsed copy — avoiding the original cache's v8.serialize/Date-subclass
 // issue without leaking mutable shared state.
-const TOML_TEXT_CACHE = new Map();
-async function readBlobTomlCached(blob) {
-    const cached = TOML_TEXT_CACHE.get(blob.hash);
+const RECORD_TEXT_CACHE = new Map();
+async function readBlobTextCached(blob) {
+    const cached = RECORD_TEXT_CACHE.get(blob.hash);
     if (cached !== undefined)
         return cached;
     const text = await blob.read();
-    TOML_TEXT_CACHE.set(blob.hash, text);
+    RECORD_TEXT_CACHE.set(blob.hash, text);
     return text;
 }
+// Minimum-viable MIME map — covers the bulk of typical attachment uses
+// (images, audio, video, docs). Unknown extensions get application/octet-stream.
+const MIME_BY_EXT = {
+    // Text
+    txt: 'text/plain',
+    md: 'text/markdown',
+    csv: 'text/csv',
+    tsv: 'text/tab-separated-values',
+    toml: 'application/toml',
+    json: 'application/json',
+    yaml: 'application/yaml',
+    yml: 'application/yaml',
+    xml: 'application/xml',
+    html: 'text/html',
+    htm: 'text/html',
+    css: 'text/css',
+    js: 'application/javascript',
+    ts: 'application/typescript',
+    svg: 'image/svg+xml',
+    // Images
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    bmp: 'image/bmp',
+    ico: 'image/vnd.microsoft.icon',
+    tiff: 'image/tiff',
+    // Audio / video
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    m4a: 'audio/mp4',
+    flac: 'audio/flac',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    // Documents / archives
+    pdf: 'application/pdf',
+    zip: 'application/zip',
+    gz: 'application/gzip',
+    tar: 'application/x-tar',
+    '7z': 'application/x-7z-compressed',
+};
+function inferMimeType(filename) {
+    const dot = filename.lastIndexOf('.');
+    if (dot < 0 || dot === filename.length - 1)
+        return 'application/octet-stream';
+    const ext = filename.slice(dot + 1).toLowerCase();
+    return MIME_BY_EXT[ext] ?? 'application/octet-stream';
+}
+function makeAttachmentBlobHandle(gitDir, hash) {
+    return {
+        hash,
+        async read() {
+            return new Promise((resolve, reject) => {
+                const child = execFile('git', ['cat-file', 'blob', hash], { cwd: gitDir, encoding: 'buffer', maxBuffer: 1024 * 1024 * 1024 }, (err, stdout) => {
+                    if (err)
+                        return reject(err);
+                    resolve(stdout);
+                });
+                child.stdin?.end();
+            });
+        },
+        stream() {
+            const child = spawn('git', ['cat-file', 'blob', hash], { cwd: gitDir });
+            child.stdin.end();
+            return child.stdout;
+        },
+    };
+}
+function parseDiffTreeZ(output) {
+    // `git diff-tree -z -r --no-commit-id` formats each entry as:
+    //   :<srcMode> <dstMode> <srcHash> <dstHash> <statusToken>\0<srcPath>\0[<dstPath>\0]
+    // The `-z` flag NUL-separates the metadata line from each path, so any
+    // path with special characters in it is preserved verbatim. Status R/C
+    // emits two paths; everything else emits one.
+    const parts = output.split('\0');
+    const out = [];
+    let i = 0;
+    while (i < parts.length) {
+        const meta = parts[i];
+        if (!meta || !meta.startsWith(':')) {
+            i++;
+            continue;
+        }
+        const tokens = meta.slice(1).split(' ');
+        if (tokens.length < 5) {
+            i++;
+            continue;
+        }
+        const srcMode = tokens[0];
+        const dstMode = tokens[1];
+        const srcHash = tokens[2];
+        const dstHash = tokens[3];
+        const statusToken = tokens[4];
+        const statusChar = statusToken[0] ?? '';
+        const status = mapDiffStatus(statusChar);
+        if (!status) {
+            i++;
+            continue;
+        }
+        i++;
+        const srcPath = parts[i++] ?? '';
+        let canonicalPath = srcPath;
+        if (statusChar === 'R' || statusChar === 'C') {
+            const dstPath = parts[i++] ?? srcPath;
+            canonicalPath = dstPath;
+        }
+        out.push({
+            status,
+            statusChar,
+            srcMode: srcMode === '000000' ? null : srcMode,
+            dstMode: dstMode === '000000' ? null : dstMode,
+            srcHash: /^0+$/.test(srcHash) ? null : srcHash,
+            dstHash: /^0+$/.test(dstHash) ? null : dstHash,
+            canonicalPath,
+        });
+    }
+    return out;
+}
+function mapDiffStatus(ch) {
+    switch (ch) {
+        case 'A':
+            return 'added';
+        case 'M':
+        case 'T':
+            return 'modified';
+        case 'D':
+            return 'deleted';
+        case 'R':
+        case 'C':
+            return 'renamed';
+        default:
+            return null;
+    }
+}
+async function readBlobAsRecord(gitDir, hash, format, formatConfig) {
+    try {
+        const { stdout } = await exec('git', ['cat-file', 'blob', hash], {
+            cwd: gitDir,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return format.parse(stdout, formatConfig);
+    }
+    catch {
+        // Blob unreadable or unparsable — caller treats this as "no record".
+        return null;
+    }
+}
+function stripRecordPath(rawPath, root, extension) {
+    let p = rawPath;
+    const cleanRoot = root.replace(/^\/+|\/+$/g, '');
+    if (cleanRoot && cleanRoot !== '.' && cleanRoot !== '') {
+        const prefix = `${cleanRoot}/`;
+        if (p.startsWith(prefix))
+            p = p.slice(prefix.length);
+    }
+    if (p.endsWith(extension))
+        p = p.slice(0, -extension.length);
+    return p;
+}
 export class Sheet {
     #repo;
     #workspace;
@@ -180,6 +372,7 @@ export class Sheet {
     #configPath;
     #transaction;
     #validator;
+    #prefix;
     #indexes = new Map();
     constructor(opts) {
         this.#repo = opts.repo;
@@ -189,6 +382,26 @@ export class Sheet {
         this.#configPath = opts.configPath;
         this.#transaction = opts.transaction;
         this.#validator = opts.validator;
+        this.#prefix = (opts.prefix ?? '').replace(/^\/+|\/+$/g, '');
+    }
+    /**
+     * The effective tree path where this sheet's records live, formed by
+     * joining `config.root` and the optional `prefix`. Normalized; never has
+     * leading/trailing slashes.
+     */
+    #effectiveRoot(config) {
+        const root = config.root.replace(/^\/+|\/+$/g, '');
+        if (!this.#prefix)
+            return root;
+        return joinTreePath(root, this.#prefix);
+    }
+    /** Options to forward when delegating into a `tx.sheet(name, opts)` call. */
+    #txDelegateOpts() {
+        return this.#prefix ? { prefix: this.#prefix } : {};
+    }
+    /** Resolve the active `Format` for this sheet's storage type. */
+    #getFormat(config) {
+        return getFormat(config.format.type);
     }
     get name() {
         return this.#name;
@@ -218,15 +431,24 @@ export class Sheet {
             throwAborted(signal);
         const config = await this.readConfig();
         const template = Template.fromString(config.path);
-        const sheetRoot = await this.#getSheetRoot(config.root);
+        const sheetRoot = await this.#getSheetRoot(this.#effectiveRoot(config));
         if (!sheetRoot)
             return;
+        const format = this.#getFormat(config);
+        const withBody = opts.withBody ?? true;
+        const bodyField = config.format.body;
+        // Guard: if the consumer asked for body-less reads but their filter
+        // references the body field, we'd silently match zero records. Fail
+        // loudly at query start instead.
+        if (!withBody && bodyField !== undefined && bodyField in filter) {
+            throw new TypeError(`Sheet.query: filter references body field ${JSON.stringify(bodyField)} while withBody: false — bodies aren't loaded so the filter would match nothing`);
+        }
         // hologit's TreeObject/BlobObject are structurally compatible with the
         // path-template tree interface; the casts bridge the type lattices.
-        for await (const { blob, path: blobPath } of template.queryTree(sheetRoot, filter)) {
+        for await (const { blob, path: blobPath } of template.queryTree(sheetRoot, filter, { extension: format.extension })) {
             if (signal?.aborted)
                 throwAborted(signal);
-            const record = (await this.#readRecordFromBlob(blob, blobPath));
+            const record = (await this.#readRecordFromBlob(blob, blobPath, config, { headerOnly: !withBody }));
             if (!queryMatches(filter, record))
                 continue;
             yield record;
@@ -245,6 +467,121 @@ export class Sheet {
         }
         return results;
     }
+    /**
+     * Hydrate a body-less record returned by `query`/`findByIndex` with its
+     * full body. Re-reads the record blob at the path annotation symbol and
+     * returns a fresh record with the body field populated.
+     *
+     * For TOML sheets (no body concept) this returns the input record
+     * unchanged after a fresh parse. For markdown/mdx sheets the body field
+     * is populated from the on-disk blob.
+     *
+     * @see specs/behaviors/content-types.md#lazy-body-loading
+     */
+    async loadBody(record) {
+        const recordPath = record[RECORD_PATH_KEY];
+        if (typeof recordPath !== 'string') {
+            throw new TypeError(`Sheet.loadBody: record is missing the path annotation (RECORD_PATH_KEY) — did it come from query()?`);
+        }
+        const config = await this.readConfig();
+        const format = this.#getFormat(config);
+        const fullPath = joinTreePath(this.#effectiveRoot(config), `${recordPath}${format.extension}`);
+        const node = await this.#dataTree.getChild(fullPath);
+        if (!node || !isBlob(node)) {
+            throw new NotFoundError('record_not_found', `Sheet.loadBody: no record blob at ${fullPath}`);
+        }
+        return (await this.#readRecordFromBlob(node, recordPath, config));
+    }
+    /**
+     * Async iterator of changes between `srcCommitHash` and the current tree,
+     * scoped to this sheet's root. `srcCommitHash` accepts a commit hash, a
+     * tree hash, or a ref name; if omitted it defaults to the empty tree
+     * (every current record yields `status: 'added'`).
+     *
+     * Currently scoped to `*.toml` entries — attachment-blob diffs are
+     * out-of-scope for v1.1.
+     *
+     * See specs/api/sheet.md#diffFrom and specs/behaviors/attachments.md.
+     */
+    async *diffFrom(srcCommitHash, opts = {}) {
+        const config = await this.readConfig();
+        const gitDir = this.#repo.gitDir;
+        const { TreeObject } = await import('hologit');
+        const srcRef = srcCommitHash ?? TreeObject.getEmptyTreeHash();
+        const dstTreeHash = await this.#dataTree.getHash();
+        const args = ['diff-tree', '-z', '-r', '-M', '--no-commit-id', srcRef, dstTreeHash];
+        const effectiveRoot = this.#effectiveRoot(config);
+        if (effectiveRoot && effectiveRoot !== '.') {
+            args.push('--', effectiveRoot);
+        }
+        let stdout;
+        try {
+            const result = await exec('git', args, {
+                cwd: gitDir,
+                maxBuffer: 64 * 1024 * 1024,
+            });
+            stdout = result.stdout;
+        }
+        catch (err) {
+            throw new RefError('ref_not_found', `Sheet.diffFrom: git diff-tree failed for src=${srcRef} dst=${dstTreeHash}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        const format = this.#getFormat(config);
+        const entries = parseDiffTreeZ(stdout);
+        for (const entry of entries) {
+            // Scope to record files for this sheet's storage format. Attachments
+            // (any extension), hidden files, and `.gitsheets/` config blobs are
+            // filtered out — they're not records.
+            if (!entry.canonicalPath.endsWith(format.extension))
+                continue;
+            if (entry.canonicalPath.startsWith('.gitsheets/'))
+                continue;
+            const recordPath = stripRecordPath(entry.canonicalPath, this.#effectiveRoot(config), format.extension);
+            const change = {
+                path: recordPath,
+                status: entry.status,
+                srcMode: entry.srcMode,
+                dstMode: entry.dstMode,
+                srcHash: entry.srcHash,
+                dstHash: entry.dstHash,
+            };
+            if (opts.blobs) {
+                if (entry.srcHash) {
+                    change['srcBlob'] = this.#repo.hologitRepo.createBlob({
+                        hash: entry.srcHash,
+                        mode: entry.srcMode ?? '100644',
+                    });
+                }
+                if (entry.dstHash) {
+                    change['dstBlob'] = this.#repo.hologitRepo.createBlob({
+                        hash: entry.dstHash,
+                        mode: entry.dstMode ?? '100644',
+                    });
+                }
+            }
+            if (opts.records || opts.patches) {
+                const src = entry.srcHash
+                    ? await readBlobAsRecord(gitDir, entry.srcHash, format, config.format)
+                    : null;
+                const dst = entry.dstHash
+                    ? await readBlobAsRecord(gitDir, entry.dstHash, format, config.format)
+                    : null;
+                if (opts.records) {
+                    if (src !== null)
+                        change['src'] = src;
+                    if (dst !== null)
+                        change['dst'] = dst;
+                }
+                if (opts.patches) {
+                    // rfc6902 treats undefined/null specially. For added: src is null,
+                    // dst is the object → patch is a single `add` op. For deleted: src
+                    // is the object, dst is null → patch is a single `remove` op. For
+                    // modified: a sequence of ops describing the diff.
+                    change['patch'] = rfc6902CreatePatch(src, dst);
+                }
+            }
+            yield change;
+        }
+    }
     async pathForRecord(record) {
         const config = await this.readConfig();
         return Template.fromString(config.path).render(record);
@@ -270,12 +607,12 @@ export class Sheet {
     async clear() {
         if (this.#transaction === undefined) {
             await this.#repo.transact({ message: `${this.#name} clear` }, async (tx) => {
-                await tx.sheet(this.#name).clear();
+                await tx.sheet(this.#name, this.#txDelegateOpts()).clear();
             });
             return;
         }
         const config = await this.readConfig();
-        const sheetTree = await this.#dataTree.getSubtree(config.root, true);
+        const sheetTree = await this.#dataTree.getSubtree(this.#effectiveRoot(config), true);
         if (sheetTree) {
             const children = await sheetTree.getChildren();
             const names = [];
@@ -300,9 +637,9 @@ export class Sheet {
         }
         return new Sheet(opts);
     }
-    async upsert(record) {
+    async upsert(record, opts = {}) {
         if (this.#transaction !== undefined) {
-            return this.#upsertInTx(this.#transaction, record);
+            return this.#upsertInTx(this.#transaction, record, opts);
         }
         this.#checkStrictMode();
         // The tx-bound Sheet returned by tx.sheet(name) doesn't carry this
@@ -326,9 +663,9 @@ export class Sheet {
         }
         const tx = transactionContext.getStore();
         if (tx !== undefined) {
-            return tx.sheet(this.#name).upsert(validated);
+            return tx.sheet(this.#name, this.#txDelegateOpts()).upsert(validated, opts);
         }
-        return this.#autoTransact(async (innerTx) => innerTx.sheet(this.#name).upsert(validated), (r) => `${this.#name} upsert ${r.path}`);
+        return this.#autoTransact(async (innerTx) => innerTx.sheet(this.#name, this.#txDelegateOpts()).upsert(validated, opts), (r) => `${this.#name} upsert ${r.path}`);
     }
     /**
      * RFC 7396 JSON Merge Patch. Reads the matching record, merges `partial`,
@@ -347,7 +684,10 @@ export class Sheet {
         if (typeof existingPath === 'string') {
             merged[RECORD_PATH_KEY] = existingPath;
         }
-        return this.upsert(merged);
+        // patch may produce a record missing the body field (e.g., `{body: null}`
+        // deletes per RFC 7396). The consumer's intent is explicit at the patch
+        // call site, so we don't trip the upsert allowMissingBody guard here.
+        return this.upsert(merged, { allowMissingBody: true });
     }
     async delete(target) {
         if (this.#transaction !== undefined) {
@@ -357,12 +697,12 @@ export class Sheet {
         this.#checkStrictMode();
         const tx = transactionContext.getStore();
         if (tx !== undefined) {
-            await tx.sheet(this.#name).delete(target);
+            await tx.sheet(this.#name, this.#txDelegateOpts()).delete(target);
             return;
         }
         const path = typeof target === 'string' ? target : await this.pathForRecord(target);
         await this.#repo.transact({ message: `${this.#name} delete ${path}` }, async (innerTx) => {
-            await innerTx.sheet(this.#name).delete(target);
+            await innerTx.sheet(this.#name, this.#txDelegateOpts()).delete(target);
         });
     }
     defineIndex(name, optsOrFn, maybeFn) {
@@ -414,17 +754,43 @@ export class Sheet {
     async getAttachment(record, name) {
         const config = await this.readConfig();
         const recordPath = typeof record === 'string' ? record : await this.pathForRecord(record);
-        const node = await this.#dataTree.getChild(joinTreePath(config.root, recordPath, name));
+        const node = await this.#dataTree.getChild(joinTreePath(this.#effectiveRoot(config), recordPath, name));
         return node && isBlob(node) ? node : null;
     }
     async getAttachments(record) {
         const config = await this.readConfig();
         const recordPath = typeof record === 'string' ? record : await this.pathForRecord(record);
-        const dir = await this.#dataTree.getChild(joinTreePath(config.root, recordPath));
+        const dir = await this.#dataTree.getChild(joinTreePath(this.#effectiveRoot(config), recordPath));
         if (!dir || !isTree(dir))
             return null;
         return dir.getBlobMap();
     }
+    /**
+     * Async iterator over a record's attachments. Each yielded item carries
+     * `name`, an extension-inferred `mimeType`, and a `blob` handle with
+     * `.read()` (returns `Buffer`) and `.stream()` (returns a Readable).
+     *
+     * The iterator is the friendlier consumer surface for browsing attachments.
+     * For programmatic blob-hash access, `getAttachments` remains.
+     *
+     * See specs/behaviors/attachments.md.
+     */
+    async *attachments(record) {
+        const blobMap = await this.getAttachments(record);
+        if (!blobMap)
+            return;
+        const gitDir = this.#repo.gitDir;
+        for (const name in blobMap) {
+            const blob = blobMap[name];
+            if (!blob)
+                continue;
+            yield {
+                name,
+                mimeType: inferMimeType(name),
+                blob: makeAttachmentBlobHandle(gitDir, blob.hash),
+            };
+        }
+    }
     async setAttachment(record, name, blob) {
         await this.setAttachments(record, { [name]: blob });
     }
@@ -433,21 +799,78 @@ export class Sheet {
             this.#checkStrictMode();
             const tx = transactionContext.getStore();
             if (tx !== undefined) {
-                await tx.sheet(this.#name).setAttachments(record, attachments);
+                await tx.sheet(this.#name, this.#txDelegateOpts()).setAttachments(record, attachments);
                 return;
             }
             await this.#repo.transact({ message: `${this.#name} attachments` }, async (innerTx) => {
-                await innerTx.sheet(this.#name).setAttachments(record, attachments);
+                await innerTx.sheet(this.#name, this.#txDelegateOpts()).setAttachments(record, attachments);
             });
             return;
         }
         const config = await this.readConfig();
         const recordPath = typeof record === 'string' ? record : await this.pathForRecord(record);
         for (const [aName, content] of Object.entries(attachments)) {
-            await this.#dataTree.writeChild(joinTreePath(config.root, recordPath, aName), content);
+            await this.#dataTree.writeChild(joinTreePath(this.#effectiveRoot(config), recordPath, aName), content);
         }
         this.#transaction.markMutated();
     }
+    /**
+     * Remove a single attachment. Throws `NotFoundError` if the named attachment
+     * doesn't exist (so callers can't silently miss bugs). Sibling attachments
+     * are left intact. See specs/behaviors/attachments.md.
+     */
+    async deleteAttachment(record, name) {
+        if (this.#transaction === undefined) {
+            this.#checkStrictMode();
+            const tx = transactionContext.getStore();
+            if (tx !== undefined) {
+                await tx.sheet(this.#name, this.#txDelegateOpts()).deleteAttachment(record, name);
+                return;
+            }
+            await this.#repo.transact({ message: `${this.#name} deleteAttachment ${name}` }, async (innerTx) => {
+                await innerTx.sheet(this.#name, this.#txDelegateOpts()).deleteAttachment(record, name);
+            });
+            return;
+        }
+        const config = await this.readConfig();
+        const recordPath = typeof record === 'string' ? record : await this.pathForRecord(record);
+        const fullPath = joinTreePath(this.#effectiveRoot(config), recordPath, name);
+        const existing = await this.#dataTree.getChild(fullPath);
+        if (!existing || !isBlob(existing)) {
+            throw new NotFoundError('record_not_found', `${this.#name}: no attachment at ${joinTreePath(recordPath, name)}`);
+        }
+        await this.#dataTree.deleteChild(fullPath);
+        this.#transaction.markMutated();
+    }
+    /**
+     * Remove all attachments for a record. No-op if the record has no
+     * attachment directory (same idempotent shape as the cascade behavior in
+     * `Sheet.delete`). See specs/behaviors/attachments.md.
+     */
+    async deleteAttachments(record) {
+        if (this.#transaction === undefined) {
+            this.#checkStrictMode();
+            const tx = transactionContext.getStore();
+            if (tx !== undefined) {
+                await tx.sheet(this.#name, this.#txDelegateOpts()).deleteAttachments(record);
+                return;
+            }
+            await this.#repo.transact({ message: `${this.#name} deleteAttachments` }, async (innerTx) => {
+                await innerTx.sheet(this.#name, this.#txDelegateOpts()).deleteAttachments(record);
+            });
+            return;
+        }
+        const config = await this.readConfig();
+        const recordPath = typeof record === 'string' ? record : await this.pathForRecord(record);
+        const fullPath = joinTreePath(this.#effectiveRoot(config), recordPath);
+        const existing = await this.#dataTree.getChild(fullPath);
+        if (!existing || !isTree(existing)) {
+            // No attachment dir — true no-op, don't even mark the tx mutated.
+            return;
+        }
+        await this.#dataTree.deleteChild(fullPath);
+        this.#transaction.markMutated();
+    }
     // --- Private helpers ---
     #checkStrictMode() {
         if (this.#repo.isStrictMode()) {
@@ -471,9 +894,18 @@ export class Sheet {
         void message;
         return staged;
     }
-    async #upsertInTx(tx, record) {
+    async #upsertInTx(tx, record, opts = {}) {
         const config = await this.readConfig();
         const template = Template.fromString(config.path);
+        // Body presence guard: upsert is a full-record replace. A markdown sheet
+        // whose record omits the body field would silently erase the on-disk
+        // body. Require explicit opt-in to make the trade visible.
+        const bodyField = config.format.body;
+        if (bodyField !== undefined &&
+            !opts.allowMissingBody &&
+            record[bodyField] === undefined) {
+            throw new TypeError(`Sheet.upsert: record is missing the body field ${JSON.stringify(bodyField)}. Pass { allowMissingBody: true } to opt in, or use Sheet.patch for body-preserving frontmatter updates.`);
+        }
         // Validate before normalizing — per specs/behaviors/validation.md order:
         // JSON Schema → Standard Schema (may transform) → normalize → render → write.
         let validated = (await validateRecord({
@@ -511,25 +943,27 @@ export class Sheet {
                 throw new IndexError('index_unique_conflict', `unique index "${state.name}" on sheet "${this.#name}": key ${JSON.stringify(key)} is already used by ${ownerPath}`, { conflictingPaths: [ownerPath, recordPath] });
             }
         }
+        const format = this.#getFormat(config);
         // Rename: if the source record was loaded from a different path, delete the old one.
         if (typeof existing === 'string' && existing !== recordPath) {
             try {
-                await this.#dataTree.deleteChild(joinTreePath(config.root, `${existing}.toml`));
+                await this.#dataTree.deleteChild(joinTreePath(this.#effectiveRoot(config), `${existing}${format.extension}`));
             }
             catch {
                 // Old path may not exist — ignore.
             }
         }
-        const toml = stringifyRecord(stripSymbols(normalized));
-        const blob = await this.#dataTree.writeChild(joinTreePath(config.root, `${recordPath}.toml`), toml);
+        const text = await format.serialize(stripSymbols(normalized), config.format);
+        const blob = await this.#dataTree.writeChild(joinTreePath(this.#effectiveRoot(config), `${recordPath}${format.extension}`), text);
         tx.markMutated();
         this.#invalidateIndexes();
         return { blob, path: recordPath };
     }
     async #deleteInTx(tx, target) {
         const config = await this.readConfig();
+        const format = this.#getFormat(config);
         const recordPath = typeof target === 'string' ? target : await this.pathForRecord(target);
-        const fullPath = joinTreePath(config.root, `${recordPath}.toml`);
+        const fullPath = joinTreePath(this.#effectiveRoot(config), `${recordPath}${format.extension}`);
         const existing = await this.#dataTree.getChild(fullPath);
         if (!existing) {
             throw new NotFoundError('record_not_found', `${this.#name}: no record at ${recordPath}`);
@@ -539,7 +973,7 @@ export class Sheet {
         // Per specs/behaviors/attachments.md the attachment dir is deleted in
         // the same operation.
         try {
-            await this.#dataTree.deleteChild(joinTreePath(config.root, recordPath));
+            await this.#dataTree.deleteChild(joinTreePath(this.#effectiveRoot(config), recordPath));
         }
         catch {
             // No attachment dir — that's fine.
@@ -570,7 +1004,11 @@ export class Sheet {
             return;
         state.uniqueMap.clear();
         state.multiMap.clear();
-        for await (const record of this.query()) {
+        // Index builds always use body-less reads. Indexing by body content is
+        // not a supported use case; consumers needing the body should call
+        // sheet.loadBody(record) after findByIndex returns.
+        // @see specs/behaviors/content-types.md#lazy-body-loading
+        for await (const record of this.query({}, { withBody: false })) {
             const rawKey = state.keyFn(record);
             if (rawKey === undefined || rawKey === null)
                 continue;
@@ -597,11 +1035,14 @@ export class Sheet {
         state.treeHashAtBuild = currentHash;
         state.built = true;
     }
-    async #readRecordFromBlob(blob, path) {
-        const text = await readBlobTomlCached(blob);
+    async #readRecordFromBlob(blob, path, config, opts = {}) {
+        const text = await readBlobTextCached(blob);
+        const format = this.#getFormat(config);
         let parsed;
         try {
-            parsed = parseToml(text);
+            parsed = opts.headerOnly
+                ? format.parseHeaderOnly(text, config.format)
+                : format.parse(text, config.format);
         }
         catch (err) {
             throw new ConfigError('config_invalid', `failed to parse record at ${path}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });