gitsheets 0.22.4 → 1.0.3

package/dist/store.d.ts

@@ -0,0 +1,41 @@
+import type { RecordLike } from './path-template/index.js';
+import type { Repository } from './repository.js';
+import { Sheet } from './sheet.js';
+import type { TransactionOptions, TransactionResult } from './transaction.js';
+import type { StandardSchemaV1 } from './validation.js';
+/** Map of sheet name → Standard Schema validator. */
+export type ValidatorMap = Readonly<Record<string, StandardSchemaV1<unknown, RecordLike>>>;
+/** Extract a validator's output record type, or fall back to `RecordLike`. */
+export type InferRecord<V> = V extends StandardSchemaV1<unknown, infer Output> ? Output extends RecordLike ? Output : RecordLike : RecordLike;
+export interface OpenStoreOptions<V extends ValidatorMap = ValidatorMap> {
+    readonly validators?: V;
+}
+/**
+ * Typed view of a Store: every key in `V.validators` becomes a property
+ * typed as `Sheet<InferRecord<V[K]>>`. Plus `transact` for atomic bundles.
+ *
+ * Sheets present in `.gitsheets/` but absent from `validators` are not
+ * accessible via property access — they fall outside the typed surface.
+ * Use `Repository.openSheet(name)` for one-off un-typed access.
+ */
+export type Store<V extends ValidatorMap = ValidatorMap> = {
+    readonly [K in keyof V]: Sheet<InferRecord<V[K]>>;
+} & {
+    readonly transact: StoreTransactFn<V>;
+};
+/** tx object passed into Store.transact's handler. */
+export type StoreTx<V extends ValidatorMap = ValidatorMap> = {
+    readonly [K in keyof V]: Sheet<InferRecord<V[K]>>;
+};
+export type StoreTransactFn<V extends ValidatorMap = ValidatorMap> = <T>(opts: TransactionOptions, handler: (tx: StoreTx<V>) => Promise<T>) => Promise<TransactionResult<T>>;
+/**
+ * Open a typed Store over the repo. Discovers every `.gitsheets/<name>.toml`
+ * and attaches per-sheet validators from `opts.validators`. Returns an object
+ * whose properties are the validated sheets, plus a `transact` method.
+ *
+ * Throws `ConfigError(config_missing)` if `validators` names a sheet that has
+ * no `.gitsheets/<name>.toml`. Sheets present on disk but absent from
+ * `validators` are accessible via `Repository.openSheet(name)`.
+ */
+export declare function openStore<V extends ValidatorMap = ValidatorMap>(repo: Repository, opts?: OpenStoreOptions<V>): Promise<Store<V>>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAEV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,qDAAqD;AACrD,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;AAE3F,8EAA8E;AAC9E,MAAM,MAAM,WAAW,CAAC,CAAC,IACvB,CAAC,SAAS,gBAAgB,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,GAC7C,MAAM,SAAS,UAAU,GACvB,MAAM,GACN,UAAU,GACZ,UAAU,CAAC;AAEjB,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI;IACzD,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAClD,GAAG;IACF,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CACvC,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI;IAC3D,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,CAAC,CAAC,EACrE,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KACpC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnC;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EACnE,IAAI,EAAE,UAAU,EAChB,IAAI,GAAE,gBAAgB,CAAC,CAAC,CAAM,GAC7B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CA+CnB"}

package/dist/store.js

@@ -0,0 +1,49 @@
+// Store — typed wrapper over Repository.openSheets with per-sheet validators.
+// See specs/api/store.md.
+import { ConfigError } from './errors.js';
+/**
+ * Open a typed Store over the repo. Discovers every `.gitsheets/<name>.toml`
+ * and attaches per-sheet validators from `opts.validators`. Returns an object
+ * whose properties are the validated sheets, plus a `transact` method.
+ *
+ * Throws `ConfigError(config_missing)` if `validators` names a sheet that has
+ * no `.gitsheets/<name>.toml`. Sheets present on disk but absent from
+ * `validators` are accessible via `Repository.openSheet(name)`.
+ */
+export async function openStore(repo, opts = {}) {
+    const sheetsBase = await repo.openSheets();
+    const declared = new Set(Object.keys(sheetsBase));
+    // Verify the validator map only names sheets that exist.
+    if (opts.validators) {
+        for (const name of Object.keys(opts.validators)) {
+            if (!declared.has(name)) {
+                throw new ConfigError('config_missing', `Store opens with validators.${name}, but .gitsheets/${name}.toml is not declared`);
+            }
+        }
+    }
+    // Re-open each sheet with its validator (the validator changes per-sheet
+    // behavior — easier to re-open than mutate the discovery result).
+    const sheets = {};
+    for (const name of declared) {
+        const validator = opts.validators?.[name];
+        if (validator !== undefined) {
+            sheets[name] = await repo.openSheet(name, { validator });
+        }
+        else {
+            sheets[name] = sheetsBase[name];
+        }
+    }
+    const transact = (txOpts, handler) => {
+        const innerHandler = async (rawTx) => {
+            const txObj = {};
+            for (const name of declared) {
+                const validator = opts.validators?.[name];
+                txObj[name] = rawTx.sheet(name, validator !== undefined ? { validator } : undefined);
+            }
+            return handler(txObj);
+        };
+        return repo.transact(txOpts, innerHandler);
+    };
+    return Object.assign(Object.create(null), sheets, { transact });
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0BAA0B;AAE1B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAkD1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAgB,EAChB,OAA4B,EAAE;IAE9B,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAElD,yDAAyD;IACzD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAChD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,WAAW,CACnB,gBAAgB,EAChB,+BAA+B,IAAI,oBAAoB,IAAI,uBAAuB,CACnF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,kEAAkE;IAClE,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAC3D,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,IAAI,CAAE,CAAC;QACnC,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAuB,CACnC,MAA0B,EAC1B,OAAuC,EACR,EAAE;QACjC,MAAM,YAAY,GAA0B,KAAK,EAAE,KAAK,EAAE,EAAE;YAC1D,MAAM,KAAK,GAA0B,EAAE,CAAC;YACxC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;gBAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC;gBAC1C,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CACvB,IAAI,EACJ,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CACpD,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC,KAA8B,CAAC,CAAC;QACjD,CAAC,CAAC;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAa,CAAC;AAC9E,CAAC"}

package/dist/toml.d.ts

@@ -0,0 +1,11 @@
+export type RecordLike = Record<string, unknown>;
+/**
+ * Serialize a record to canonical TOML — deep-sorted keys for byte-stable output.
+ *
+ * Array fields are NOT sorted here; sheet-level normalization rules
+ * (`[gitsheet.fields.<name>.sort]`) handle that before this is called.
+ */
+export declare function stringifyRecord(record: RecordLike): string;
+export declare function parseToml(content: string): RecordLike;
+export declare function parseConfigToml(content: string, sourcePath: string): RecordLike;
+//# sourceMappingURL=toml.d.ts.map

package/dist/toml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toml.d.ts","sourceRoot":"","sources":["../src/toml.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAUjD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAG1D;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAErD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAU/E"}

package/dist/toml.js

@@ -0,0 +1,28 @@
+// TOML serialization helpers with canonical key sorting.
+// See specs/behaviors/normalization.md for the byte-stable normalization rules.
+import * as TOML from '@iarna/toml';
+import sortKeys from 'sort-keys';
+import { ConfigError } from './errors.js';
+const toml = TOML;
+/**
+ * Serialize a record to canonical TOML — deep-sorted keys for byte-stable output.
+ *
+ * Array fields are NOT sorted here; sheet-level normalization rules
+ * (`[gitsheet.fields.<name>.sort]`) handle that before this is called.
+ */
+export function stringifyRecord(record) {
+    const sorted = sortKeys(record, { deep: true });
+    return toml.stringify(sorted);
+}
+export function parseToml(content) {
+    return toml.parse(content);
+}
+export function parseConfigToml(content, sourcePath) {
+    try {
+        return parseToml(content);
+    }
+    catch (err) {
+        throw new ConfigError('config_invalid', `failed to parse TOML at ${sourcePath}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}
+//# sourceMappingURL=toml.js.map

package/dist/toml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toml.js","sourceRoot":"","sources":["../src/toml.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,gFAAgF;AAEhF,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,OAAO,QAAQ,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAU1C,MAAM,IAAI,GAAG,IAA6B,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAkB;IAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAA4B,CAAC;IAC3E,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,UAAkB;IACjE,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CACnB,gBAAgB,EAChB,2BAA2B,UAAU,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAC5F,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/transaction.d.ts

@@ -0,0 +1,96 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Repo as HologitRepo, TreeObject, Workspace } from 'hologit';
+import { RefError } from './errors.js';
+import type { RecordLike } from './path-template/index.js';
+import type { Sheet } from './sheet.js';
+import type { StandardSchemaV1 } from './validation.js';
+export interface Author {
+    readonly name: string;
+    readonly email: string;
+}
+export interface TransactionOptions {
+    /** Ref name or commit hash to parent the commit on; defaults to current HEAD. */
+    readonly parent?: string;
+    /** Ref name to update on commit; default: parent if it's a branch, null if a hash. */
+    readonly branch?: string;
+    /** Commit author; defaults to git config user.name/email. */
+    readonly author?: Author;
+    /** Commit committer; defaults to author. */
+    readonly committer?: Author;
+    /** Commit subject + body. First line is the subject. */
+    readonly message: string;
+    /** Git-style trailers appended per `git interpret-trailers`. */
+    readonly trailers?: Readonly<Record<string, string>>;
+}
+export interface TransactionResult<T> {
+    readonly value: T;
+    readonly commitHash: string | null;
+    readonly treeHash: string | null;
+    readonly ref: string | null;
+    readonly parentCommitHash: string | null;
+}
+export type TransactionHandler<T> = (tx: Transaction) => Promise<T>;
+export declare const transactionContext: AsyncLocalStorage<Transaction>;
+/**
+ * In-process mutex serializing transactions on a single Repository.
+ * Concurrent callers from independent async contexts queue; nested
+ * repo.transact attempts (same async context) throw before acquiring.
+ */
+export declare class Mutex {
+    #private;
+    acquire(): Promise<() => void>;
+}
+export declare class Transaction {
+    #private;
+    /**
+     * @internal — Transactions are created by Repository.transact (or
+     * Store.transact). Consumers do not construct Transaction directly; the
+     * constructor is exported only so the type is available for typing
+     * handler parameters.
+     */
+    constructor(opts: {
+        hologitRepo: HologitRepo;
+        workspace: Workspace;
+        parentCommitHash: string | null;
+        parentRef: string | null;
+        branchRef: string | null;
+        author: Author;
+        committer: Author;
+        message: string;
+        trailers: Readonly<Record<string, string>>;
+        sheetFactory: <T extends RecordLike = RecordLike>(name: string, workspace: Workspace, tree: TreeObject, validator?: StandardSchemaV1<unknown, T>) => Sheet<T>;
+    });
+    get tree(): TreeObject;
+    get parentCommitHash(): string | null;
+    get parentRef(): string | null;
+    get branchRef(): string | null;
+    /** Marker used by Sheet to record that a mutation happened in this tx. */
+    markMutated(): void;
+    /**
+     * Returns a Sheet whose writes route through this transaction's private tree.
+     * `opts.validator` (optional) attaches a Standard Schema validator — used by
+     * Store.transact to thread per-sheet validators through to tx scope.
+     */
+    sheet<T extends RecordLike = RecordLike>(name: string, opts?: {
+        validator?: StandardSchemaV1<unknown, T>;
+    }): Sheet<T>;
+    /**
+     * Finalize the transaction. Returns the commit hash + tree hash, or nulls if
+     * no mutations occurred. Throws TransactionError(parent_moved) on optimistic
+     * concurrency conflict. After finalize the transaction is closed.
+     */
+    finalize<T>(value: T): Promise<TransactionResult<T>>;
+    /** Called by Repository on handler throw. Marks the transaction closed. */
+    discard(): void;
+    static normalizeOptions(opts: TransactionOptions): {
+        parent: string | undefined;
+        branch: string | undefined;
+        author: Author | undefined;
+        committer: Author | undefined;
+        message: string;
+        trailers: Readonly<Record<string, string>>;
+    };
+}
+export declare function resolveAuthor(gitDir: string, explicit: Author | undefined): Promise<Author>;
+export declare function refNotFound(ref: string): RefError;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"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"}

package/dist/transaction.js

@@ -0,0 +1,227 @@
+// Transaction — scopes a set of sheet mutations to a single commit.
+// See specs/api/transaction.md + specs/behaviors/transactions.md.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { RefError, TransactionError } from './errors.js';
+const exec = promisify(execFile);
+// Active transaction context — used to detect nested repo.transact attempts.
+export const transactionContext = new AsyncLocalStorage();
+const HTTP_HEADER_KEY_RE = /^[A-Z][a-z0-9]*(-[A-Z][a-z0-9]*)*$|^[A-Z][a-z]+$/;
+const TRAILER_VALUE_RE = /[\r\n]/;
+function validateTrailers(trailers) {
+    if (!trailers)
+        return;
+    for (const [key, value] of Object.entries(trailers)) {
+        if (!HTTP_HEADER_KEY_RE.test(key)) {
+            throw new TransactionError('commit_failed', `trailer key ${JSON.stringify(key)} does not match HTTP-header style (e.g., "Subject-Id", "Action")`);
+        }
+        if (typeof value !== 'string' || TRAILER_VALUE_RE.test(value)) {
+            throw new TransactionError('commit_failed', `trailer ${JSON.stringify(key)} has invalid value (must be string with no newlines): ${JSON.stringify(value)}`);
+        }
+    }
+}
+function formatCommitMessage(subject, trailers) {
+    // The `subject` arg is the full message string — it may already contain a body.
+    const body = subject.trimEnd();
+    if (!trailers || Object.keys(trailers).length === 0) {
+        return body + '\n';
+    }
+    const lines = Object.entries(trailers).map(([k, v]) => `${k}: ${v}`).join('\n');
+    return `${body}\n\n${lines}\n`;
+}
+/**
+ * In-process mutex serializing transactions on a single Repository.
+ * Concurrent callers from independent async contexts queue; nested
+ * repo.transact attempts (same async context) throw before acquiring.
+ */
+export class Mutex {
+    #locked = false;
+    #queue = [];
+    async acquire() {
+        if (!this.#locked) {
+            this.#locked = true;
+            return () => this.#release();
+        }
+        return new Promise((resolve) => {
+            this.#queue.push(() => resolve(() => this.#release()));
+        });
+    }
+    #release() {
+        const next = this.#queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this.#locked = false;
+        }
+    }
+}
+export class Transaction {
+    #hologitRepo;
+    #workspace;
+    #parentCommitHash;
+    #parentRef;
+    #branchRef;
+    #author;
+    #committer;
+    #message;
+    #trailers;
+    /** Function the Repository injects so Transaction.sheet() can build Sheet instances. */
+    #sheetFactory;
+    #closed = false;
+    #anyMutation = false;
+    /**
+     * @internal — Transactions are created by Repository.transact (or
+     * Store.transact). Consumers do not construct Transaction directly; the
+     * constructor is exported only so the type is available for typing
+     * handler parameters.
+     */
+    constructor(opts) {
+        this.#hologitRepo = opts.hologitRepo;
+        this.#workspace = opts.workspace;
+        this.#parentCommitHash = opts.parentCommitHash;
+        this.#parentRef = opts.parentRef;
+        this.#branchRef = opts.branchRef;
+        this.#author = opts.author;
+        this.#committer = opts.committer;
+        this.#message = opts.message;
+        this.#trailers = opts.trailers;
+        this.#sheetFactory = opts.sheetFactory;
+    }
+    get tree() {
+        return this.#workspace.root;
+    }
+    get parentCommitHash() {
+        return this.#parentCommitHash;
+    }
+    get parentRef() {
+        return this.#parentRef;
+    }
+    get branchRef() {
+        return this.#branchRef;
+    }
+    /** Marker used by Sheet to record that a mutation happened in this tx. */
+    markMutated() {
+        this.#anyMutation = true;
+    }
+    /**
+     * Returns a Sheet whose writes route through this transaction's private tree.
+     * `opts.validator` (optional) attaches a Standard Schema validator — used by
+     * Store.transact to thread per-sheet validators through to tx scope.
+     */
+    sheet(name, opts) {
+        if (this.#closed) {
+            throw new TransactionError('transaction_closed', 'transaction is already closed — obtain a fresh Transaction via repo.transact');
+        }
+        return this.#sheetFactory(name, this.#workspace, this.#workspace.root, opts?.validator);
+    }
+    /**
+     * Finalize the transaction. Returns the commit hash + tree hash, or nulls if
+     * no mutations occurred. Throws TransactionError(parent_moved) on optimistic
+     * concurrency conflict. After finalize the transaction is closed.
+     */
+    async finalize(value) {
+        this.#closed = true;
+        if (!this.#anyMutation) {
+            return {
+                value,
+                commitHash: null,
+                treeHash: null,
+                ref: null,
+                parentCommitHash: this.#parentCommitHash,
+            };
+        }
+        // Optimistic concurrency: re-check the parent ref hasn't moved.
+        if (this.#parentRef !== null) {
+            const current = await this.#hologitRepo.resolveRef(this.#parentRef);
+            if (current !== this.#parentCommitHash) {
+                throw new TransactionError('parent_moved', `parent ref ${this.#parentRef} moved during transaction (expected ${this.#parentCommitHash ?? 'null'}, found ${current ?? 'null'})`);
+            }
+        }
+        const gitDir = this.#hologitRepo.gitDir;
+        const treeHash = await this.#workspace.root.write();
+        const message = formatCommitMessage(this.#message, this.#trailers);
+        let commitHash;
+        try {
+            const args = ['commit-tree', treeHash, '-m', message];
+            if (this.#parentCommitHash) {
+                args.push('-p', this.#parentCommitHash);
+            }
+            const env = {
+                ...process.env,
+                GIT_AUTHOR_NAME: this.#author.name,
+                GIT_AUTHOR_EMAIL: this.#author.email,
+                GIT_COMMITTER_NAME: this.#committer.name,
+                GIT_COMMITTER_EMAIL: this.#committer.email,
+            };
+            const { stdout } = await exec('git', args, { cwd: gitDir, env });
+            commitHash = stdout.trim();
+        }
+        catch (err) {
+            throw new TransactionError('commit_failed', `git commit-tree failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        if (this.#branchRef !== null) {
+            try {
+                const args = ['update-ref', this.#branchRef, commitHash];
+                if (this.#parentCommitHash) {
+                    args.push(this.#parentCommitHash);
+                }
+                await exec('git', args, { cwd: gitDir });
+            }
+            catch (err) {
+                throw new TransactionError('commit_failed', `git update-ref ${this.#branchRef} failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+        }
+        return {
+            value,
+            commitHash,
+            treeHash,
+            ref: this.#branchRef,
+            parentCommitHash: this.#parentCommitHash,
+        };
+    }
+    /** Called by Repository on handler throw. Marks the transaction closed. */
+    discard() {
+        this.#closed = true;
+    }
+    static normalizeOptions(opts) {
+        validateTrailers(opts.trailers);
+        return {
+            parent: opts.parent,
+            branch: opts.branch,
+            author: opts.author,
+            committer: opts.committer ?? opts.author,
+            message: opts.message,
+            trailers: opts.trailers ?? {},
+        };
+    }
+}
+// --- Author resolution from git config ---
+let anonymousWarned = false;
+export async function resolveAuthor(gitDir, explicit) {
+    if (explicit)
+        return explicit;
+    try {
+        const [name, email] = await Promise.all([
+            exec('git', ['config', 'user.name'], { cwd: gitDir }).then((r) => r.stdout.trim()),
+            exec('git', ['config', 'user.email'], { cwd: gitDir }).then((r) => r.stdout.trim()),
+        ]);
+        if (name && email) {
+            return { name, email };
+        }
+    }
+    catch {
+        // fall through to anonymous default
+    }
+    if (!anonymousWarned) {
+        anonymousWarned = true;
+        process.stderr.write('gitsheets: no commit author configured (set git config user.name + user.email, or pass opts.author); falling back to Anonymous <anonymous@gitsheets.local>\n');
+    }
+    return { name: 'Anonymous', email: 'anonymous@gitsheets.local' };
+}
+// --- RefError helpers ---
+export function refNotFound(ref) {
+    return new RefError('ref_not_found', `ref not found: ${ref}`);
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts

@@ -0,0 +1,37 @@
+import { type ValidateFunction } from 'ajv';
+export type JSONSchema = Record<string, unknown>;
+export interface StandardSchemaPathSegment {
+    readonly key: string | number;
+}
+export interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<string | number | StandardSchemaPathSegment>;
+}
+export interface StandardSchemaSuccess<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+}
+export interface StandardSchemaFailure {
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+}
+export type StandardSchemaResult<Output> = StandardSchemaSuccess<Output> | StandardSchemaFailure;
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    };
+    /** unused — only here so consumers' generic type can flow Input/Output. */
+    readonly __types__?: {
+        input: Input;
+        output: Output;
+    };
+}
+export declare function compileSchema(schema: JSONSchema, sourcePath: string): ValidateFunction;
+export declare function validateRecord(opts: {
+    record: Record<string, unknown>;
+    schema: JSONSchema | null;
+    schemaSourcePath?: string;
+    validator?: StandardSchemaV1 | undefined;
+}): Promise<Record<string, unknown>>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAAO,KAAK,gBAAgB,EAAoB,MAAM,KAAK,CAAC;AAOnE,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAKjD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AACD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,yBAAyB,CAAC,CAAC;CAC5E;AACD,MAAM,WAAW,qBAAqB,CAAC,MAAM;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AACD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;CACrD;AACD,MAAM,MAAM,oBAAoB,CAAC,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,GAAG,qBAAqB,CAAC;AACjG,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,KACX,oBAAoB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;KAC3E,CAAC;IACF,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD;AAiBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAgBtF;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAC1C,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAoCnC"}

package/dist/validation.js

@@ -0,0 +1,105 @@
+// Validation pipeline — JSON Schema via ajv, then optional Standard Schema.
+// See specs/behaviors/validation.md.
+// ajv v8 named-exports Ajv as a class; addFormats is a default-exported plugin
+// in a CJS package — NodeNext gives us the namespace, so we pull `.default`.
+import { Ajv } from 'ajv';
+import * as addFormatsNs from 'ajv-formats';
+const addFormats = addFormatsNs.default;
+import { ConfigError, ValidationError } from './errors.js';
+// --- ajv setup ---
+// Compiled validators are cached per schema-identity (object reference) so a
+// Sheet's `Sheet.readConfig` returning the same schema object hits the cache.
+const COMPILED_CACHE = new WeakMap();
+let sharedAjv = null;
+function getAjv() {
+    if (!sharedAjv) {
+        sharedAjv = new Ajv({ strict: true, allErrors: true, $data: false });
+        addFormats(sharedAjv);
+    }
+    return sharedAjv;
+}
+export function compileSchema(schema, sourcePath) {
+    const cached = COMPILED_CACHE.get(schema);
+    if (cached)
+        return cached;
+    const ajv = getAjv();
+    let compiled;
+    try {
+        compiled = ajv.compile(schema);
+    }
+    catch (err) {
+        throw new ConfigError('config_invalid', `${sourcePath}: [gitsheet.schema] failed to compile: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    COMPILED_CACHE.set(schema, compiled);
+    return compiled;
+}
+// --- Public validate ---
+export async function validateRecord(opts) {
+    const issues = [];
+    let value = opts.record;
+    if (opts.schema) {
+        const compiled = compileSchema(opts.schema, opts.schemaSourcePath ?? '<schema>');
+        const ok = compiled(value);
+        if (!ok) {
+            for (const err of compiled.errors ?? []) {
+                issues.push(ajvErrorToIssue(err));
+            }
+        }
+    }
+    if (issues.length > 0) {
+        throw new ValidationError('validation_failed', 'record failed JSON Schema validation', {
+            issues,
+        });
+    }
+    if (opts.validator) {
+        const result = await opts.validator['~standard'].validate(value);
+        if (isFailure(result)) {
+            for (const issue of result.issues) {
+                issues.push(standardIssueToIssue(issue));
+            }
+            throw new ValidationError('validation_failed', 'record failed Standard Schema validation', { issues });
+        }
+        value = result.value;
+    }
+    return value;
+}
+function ajvErrorToIssue(err) {
+    const path = err.instancePath
+        ? err.instancePath.split('/').slice(1).map(unescapeJsonPointer)
+        : [];
+    const issue = {
+        path,
+        message: err.message ?? 'validation failed',
+        source: 'json-schema',
+    };
+    if (err.schemaPath !== undefined) {
+        Object.assign(issue, { schemaPath: err.schemaPath });
+    }
+    if (err.keyword !== undefined) {
+        Object.assign(issue, { code: err.keyword });
+    }
+    return issue;
+}
+function unescapeJsonPointer(segment) {
+    return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+function standardIssueToIssue(issue) {
+    const path = [];
+    for (const seg of issue.path ?? []) {
+        if (typeof seg === 'string' || typeof seg === 'number') {
+            path.push(String(seg));
+        }
+        else if (seg && typeof seg === 'object' && 'key' in seg) {
+            path.push(String(seg.key));
+        }
+    }
+    return {
+        path,
+        message: issue.message,
+        source: 'standard-schema',
+    };
+}
+function isFailure(result) {
+    return 'issues' in result && Array.isArray(result.issues);
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}