dorfl 0.14.2 → 0.15.0

package/dist/ci-handoff-lfs.d.ts

@@ -0,0 +1,146 @@
+/**
+ * **Git LFS objects in the CI handoff** (spec `ci-agent-job-without-write-token`,
+ * ADR `ci-agent-job-holds-no-write-token` decision 6, task
+ * `ci-split-handoff-lfs-objects`).
+ *
+ * The agent job commits LFS-tracked paths as pointers (its checkout runs
+ * `git lfs install --local`), with the objects under `.git/lfs/objects/`. It
+ * holds no write token, so it cannot upload them: the handoff carries them as
+ * `lfs/<oid>`, and the apply job pushes them to the arbiter's LFS store BEFORE
+ * any ref, so a ref never lands pointing at a missing object.
+ *
+ * Pointers are found by scanning the blobs the new commits add or change (a
+ * blob that parses as a pointer counts, whatever `.gitattributes` says), never
+ * by trusting `git lfs ls-files`. Accepted consequence: a legitimate text file
+ * that happens to parse as a pointer is treated as one, and its object must be
+ * present or the handoff is rejected.
+ *
+ *  - agent side: {@link writeLfsObjects} copies every referenced object from
+ *    the local store into `lfs/<oid>`, including one the agent copied from
+ *    elsewhere in the repository;
+ *  - apply side: {@link checkLfsObjects} runs the strict parser's verdicts
+ *    against the artifact's objects (present, a regular file, exactly `size`
+ *    bytes, hashing to `oid`, none unreferenced, within the size limit), and
+ *    {@link pushLfsObjects} stages the validated objects into the apply
+ *    checkout's own store (re-hashing every byte it copies) and pushes them with
+ *    `git lfs push --object-id <arbiter> <oids>` from that checkout of the
+ *    trusted base, so `.lfsconfig` and the endpoint come from `main` (the
+ *    bundle cannot change `.lfsconfig`: it is a protected path).
+ *
+ * Content addressing means a hostile object can only be itself: it cannot
+ * overwrite another object.
+ */
+/** git-lfs's blob size cutoff: a larger blob is never read as a pointer. */
+export declare const LFS_POINTER_MAX_BYTES = 1024;
+/** A parsed LFS pointer. */
+export interface LfsPointer {
+    /** The sha256 of the object, 64 lower-case hex. */
+    oid: string;
+    /** The object's size in bytes. */
+    size: number;
+}
+/**
+ * Parse a blob as a spec v1 LFS pointer, STRICTLY: at most
+ * {@link LFS_POINTER_MAX_BYTES} bytes, exactly
+ * `version https://git-lfs.github.com/spec/v1`, `oid sha256:<64 hex>`,
+ * `size <n>` (no leading zero, a safe integer), each ending in `\n`, in that
+ * order, nothing else. `undefined` when the blob is not such a pointer.
+ */
+export declare function parseLfsPointer(content: Buffer): LfsPointer | undefined;
+/**
+ * Whether git-lfs could read a blob as a pointer (see {@link POINTER_LIKE}). A
+ * blob that looks like one but does not parse strictly is a MALFORMED pointer,
+ * which the apply job rejects rather than treating as an ordinary file.
+ */
+export declare function looksLikeLfsPointer(content: Buffer): boolean;
+/** A regular-file blob a new commit adds or changes, with one path it has. */
+export interface ChangedBlob {
+    oid: string;
+    path: string;
+}
+/** A pointer found in the new commits, with a path that carries it. */
+export interface FoundPointer extends LfsPointer {
+    path: string;
+}
+/** What {@link scanLfsPointers} found. */
+export interface LfsScan {
+    pointers: FoundPointer[];
+    /** Paths of blobs that look like pointers but do not parse strictly. */
+    malformed: string[];
+}
+/** Whether a tree entry mode is a regular file (LFS applies to nothing else). */
+export declare function isRegularFileMode(mode: string): boolean;
+/**
+ * Scan `blobs` (read in `cwd`) for LFS pointers: every blob of at most
+ * {@link LFS_POINTER_MAX_BYTES} bytes is read, in one `cat-file --batch`.
+ */
+export declare function scanLfsPointers(params: {
+    cwd: string;
+    blobs: readonly ChangedBlob[];
+    env?: NodeJS.ProcessEnv;
+}): LfsScan;
+/**
+ * The regular-file blobs `commits` add or change against their first parent
+ * (a root commit against the empty tree). Deletions carry no blob.
+ */
+export declare function changedFileBlobs(cwd: string, commits: readonly string[], env?: NodeJS.ProcessEnv): ChangedBlob[];
+/**
+ * The repository's local LFS object directory: `<storage>/objects`, where the
+ * storage is `lfs.storage` (relative to the git directory) or `<git dir>/lfs`.
+ */
+export declare function localLfsObjectsDir(repo: string, env?: NodeJS.ProcessEnv): string;
+/** Where the store keeps `oid`: `<objects>/<oid[0:2]>/<oid[2:4]>/<oid>`. */
+export declare function lfsObjectPath(objectsDir: string, oid: string): string;
+/**
+ * Copy into `<dir>/lfs/<oid>` the object of every pointer the commits
+ * `<ref> ^<baseSha>` add or change, from `repo`'s local store. An object the
+ * store lacks is left out: the apply job then rejects the handoff naming it
+ * (that is also the fate of a text file that parses as a pointer). Refuses
+ * ({@link HandoffRejected} `size`) objects over the LFS limit together.
+ * Returns the oids left out.
+ */
+export declare function writeLfsObjects(params: {
+    dir: string;
+    repo: string;
+    ref: string;
+    baseSha: string;
+    env?: NodeJS.ProcessEnv;
+}): {
+    missing: string[];
+};
+/** An object file of the artifact (`lfs/<oid>`, already a named regular file). */
+export interface LfsArtifactObject {
+    oid: string;
+    path: string;
+    size: number;
+}
+/**
+ * Check the artifact's LFS objects against the pointers the new commits carry
+ * (decision 6). Rejects ({@link HandoffRejected}): a blob that looks like a
+ * pointer but does not parse strictly (`lfs-pointer`); two pointers giving one
+ * oid different sizes, or an object whose size or hash differs from its
+ * pointer (`lfs-mismatch`); a pointer whose object is not in `lfs/`
+ * (`lfs-missing`); an object no pointer references (`lfs-extra`); a pointer, or
+ * all of them together, over the LFS limit (`size`). Returns the referenced
+ * objects, sorted by oid.
+ */
+export declare function checkLfsObjects(scan: LfsScan, objects: readonly LfsArtifactObject[]): LfsArtifactObject[];
+/**
+ * Stage the validated objects into `cwd`'s own LFS store and push them to
+ * `arbiter` with `git lfs push --object-id`, BEFORE any ref is pushed. `cwd`
+ * is the apply job's checkout of the trusted base, so `.lfsconfig` and the
+ * endpoint come from `main`. Every byte staged is hashed again as it is copied
+ * (a file that changed since validation rejects, `lfs-mismatch`); an object
+ * the store already holds is not copied. The upload itself is the write seam
+ * `refWrite.pushLfsObjects`. Returns the push's status and stderr.
+ */
+export declare function pushLfsObjects(params: {
+    cwd: string;
+    arbiter: string;
+    objects: readonly LfsArtifactObject[];
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    status: number;
+    stderr: string;
+}>;
+//# sourceMappingURL=ci-handoff-lfs.d.ts.map

package/dist/ci-handoff-lfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-handoff-lfs.d.ts","sourceRoot":"","sources":["../src/ci-handoff-lfs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAyBH,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAsB1C,4BAA4B;AAC5B,MAAM,WAAW,UAAU;IAC1B,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACb;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC/C,IAAI,EAAE,MAAM,CAAC;CACb;AAED,0CAA0C;AAC1C,MAAM,WAAW,OAAO;IACvB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wEAAwE;IACxE,SAAS,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,OAAO,CAoDV;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,WAAW,EAAE,CAgCf;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,MAAM,EACZ,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,CAgBR;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAMD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAC,CAuCtB;AAMD,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAyCD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACnC,iBAAiB,EAAE,CAyErB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,CAY5C"}

package/dist/ci-handoff-lfs.js

@@ -0,0 +1,397 @@
+/**
+ * **Git LFS objects in the CI handoff** (spec `ci-agent-job-without-write-token`,
+ * ADR `ci-agent-job-holds-no-write-token` decision 6, task
+ * `ci-split-handoff-lfs-objects`).
+ *
+ * The agent job commits LFS-tracked paths as pointers (its checkout runs
+ * `git lfs install --local`), with the objects under `.git/lfs/objects/`. It
+ * holds no write token, so it cannot upload them: the handoff carries them as
+ * `lfs/<oid>`, and the apply job pushes them to the arbiter's LFS store BEFORE
+ * any ref, so a ref never lands pointing at a missing object.
+ *
+ * Pointers are found by scanning the blobs the new commits add or change (a
+ * blob that parses as a pointer counts, whatever `.gitattributes` says), never
+ * by trusting `git lfs ls-files`. Accepted consequence: a legitimate text file
+ * that happens to parse as a pointer is treated as one, and its object must be
+ * present or the handoff is rejected.
+ *
+ *  - agent side: {@link writeLfsObjects} copies every referenced object from
+ *    the local store into `lfs/<oid>`, including one the agent copied from
+ *    elsewhere in the repository;
+ *  - apply side: {@link checkLfsObjects} runs the strict parser's verdicts
+ *    against the artifact's objects (present, a regular file, exactly `size`
+ *    bytes, hashing to `oid`, none unreferenced, within the size limit), and
+ *    {@link pushLfsObjects} stages the validated objects into the apply
+ *    checkout's own store (re-hashing every byte it copies) and pushes them with
+ *    `git lfs push --object-id <arbiter> <oids>` from that checkout of the
+ *    trusted base, so `.lfsconfig` and the endpoint come from `main` (the
+ *    bundle cannot change `.lfsconfig`: it is a protected path).
+ *
+ * Content addressing means a hostile object can only be itself: it cannot
+ * overwrite another object.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, statSync, writeSync, } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { handoffByteLimits, rejectHandoff as reject, } from './ci-handoff-format.js';
+import { git, gitBytes, run } from './git.js';
+import { refWrite } from './ref-write.js';
+/** git-lfs's blob size cutoff: a larger blob is never read as a pointer. */
+export const LFS_POINTER_MAX_BYTES = 1024;
+/**
+ * The directory of the artifact that holds the objects (`lfs/<oid>`): the
+ * same name as `HANDOFF_LFS_DIR` in `ci-handoff.ts`, which imports this module.
+ */
+const LFS_ARTIFACT_DIR = 'lfs';
+/** The one pointer form accepted: spec v1, keys in order, nothing else. */
+const STRICT_POINTER = /^version https:\/\/git-lfs\.github\.com\/spec\/v1\noid sha256:([0-9a-f]{64})\nsize (0|[1-9][0-9]*)\n$/;
+/**
+ * What git-lfs itself could read as a pointer: a first key `version` naming an
+ * LFS spec (current or the legacy `hawser` one), after leading whitespace.
+ */
+const POINTER_LIKE = /^[ \t\r\n]*version https:\/\/(?:git-lfs|hawser)\.github\.com\/spec\//;
+const MODE_FILE = '100644';
+const MODE_EXEC = '100755';
+/**
+ * Parse a blob as a spec v1 LFS pointer, STRICTLY: at most
+ * {@link LFS_POINTER_MAX_BYTES} bytes, exactly
+ * `version https://git-lfs.github.com/spec/v1`, `oid sha256:<64 hex>`,
+ * `size <n>` (no leading zero, a safe integer), each ending in `\n`, in that
+ * order, nothing else. `undefined` when the blob is not such a pointer.
+ */
+export function parseLfsPointer(content) {
+    if (content.length > LFS_POINTER_MAX_BYTES)
+        return undefined;
+    const m = STRICT_POINTER.exec(content.toString('latin1'));
+    if (m === null)
+        return undefined;
+    const size = Number(m[2]);
+    if (!Number.isSafeInteger(size))
+        return undefined;
+    return { oid: m[1], size };
+}
+/**
+ * Whether git-lfs could read a blob as a pointer (see {@link POINTER_LIKE}). A
+ * blob that looks like one but does not parse strictly is a MALFORMED pointer,
+ * which the apply job rejects rather than treating as an ordinary file.
+ */
+export function looksLikeLfsPointer(content) {
+    if (content.length === 0 || content.length > LFS_POINTER_MAX_BYTES) {
+        return false;
+    }
+    return POINTER_LIKE.test(content.toString('latin1'));
+}
+/** Whether a tree entry mode is a regular file (LFS applies to nothing else). */
+export function isRegularFileMode(mode) {
+    return mode === MODE_FILE || mode === MODE_EXEC;
+}
+/**
+ * Scan `blobs` (read in `cwd`) for LFS pointers: every blob of at most
+ * {@link LFS_POINTER_MAX_BYTES} bytes is read, in one `cat-file --batch`.
+ */
+export function scanLfsPointers(params) {
+    const { cwd, env } = params;
+    const pathOf = new Map();
+    for (const b of params.blobs) {
+        if (!pathOf.has(b.oid))
+            pathOf.set(b.oid, b.path);
+    }
+    if (pathOf.size === 0)
+        return { pointers: [], malformed: [] };
+    const small = [];
+    const checks = git(['cat-file', '--batch-check=%(objectname) %(objecttype) %(objectsize)'], cwd, { env, input: [...pathOf.keys()].join('\n') + '\n' })
+        .trim()
+        .split('\n');
+    for (const line of checks) {
+        const [oid, type, size] = line.split(' ');
+        const n = Number(size);
+        if (type === 'blob' && n > 0 && n <= LFS_POINTER_MAX_BYTES)
+            small.push(oid);
+    }
+    if (small.length === 0)
+        return { pointers: [], malformed: [] };
+    const out = gitBytes(['cat-file', '--batch'], cwd, {
+        env,
+        input: small.join('\n') + '\n',
+    });
+    const pointers = [];
+    const malformed = [];
+    let at = 0;
+    for (let i = 0; i < small.length; i++) {
+        const eol = out.indexOf(0x0a, at);
+        if (eol === -1)
+            throw new Error('git cat-file --batch: truncated output');
+        const [oid, type, size] = out
+            .subarray(at, eol)
+            .toString('latin1')
+            .split(' ');
+        const n = Number(size);
+        if (type !== 'blob' || !Number.isSafeInteger(n)) {
+            throw new Error(`git cat-file --batch: unexpected header for ${oid}`);
+        }
+        const content = out.subarray(eol + 1, eol + 1 + n);
+        at = eol + 1 + n + 1;
+        const path = pathOf.get(oid) ?? oid;
+        const pointer = parseLfsPointer(content);
+        if (pointer !== undefined) {
+            pointers.push({ ...pointer, path });
+        }
+        else if (looksLikeLfsPointer(content)) {
+            malformed.push(path);
+        }
+    }
+    return { pointers, malformed };
+}
+/**
+ * The regular-file blobs `commits` add or change against their first parent
+ * (a root commit against the empty tree). Deletions carry no blob.
+ */
+export function changedFileBlobs(cwd, commits, env) {
+    if (commits.length === 0)
+        return [];
+    const out = git([
+        '-c',
+        'diff.renames=false',
+        'diff-tree',
+        '--stdin',
+        '--root',
+        '-r',
+        '-z',
+        '--raw',
+        '--no-renames',
+        '--no-commit-id',
+    ], cwd, { env, input: commits.join('\n') + '\n' });
+    const fields = out.split('\0');
+    const blobs = [];
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        const meta = fields[i];
+        if (!meta.startsWith(':')) {
+            // `--stdin` may echo a commit id line; skip it.
+            i -= 1;
+            continue;
+        }
+        const [, newMode, , newOid, status] = meta.slice(1).split(' ');
+        if (status === 'D' || !isRegularFileMode(newMode))
+            continue;
+        blobs.push({ oid: newOid, path: fields[i + 1] });
+    }
+    return blobs;
+}
+// ---------------------------------------------------------------------------
+// The local object store
+// ---------------------------------------------------------------------------
+/**
+ * The repository's local LFS object directory: `<storage>/objects`, where the
+ * storage is `lfs.storage` (relative to the git directory) or `<git dir>/lfs`.
+ */
+export function localLfsObjectsDir(repo, env) {
+    const common = git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repo, { env }).trim();
+    const custom = run('git', ['config', '--get', 'lfs.storage'], repo, {
+        env,
+    }).stdout.trim();
+    const storage = custom === ''
+        ? join(common, 'lfs')
+        : isAbsolute(custom)
+            ? custom
+            : resolve(common, custom);
+    return join(storage, 'objects');
+}
+/** Where the store keeps `oid`: `<objects>/<oid[0:2]>/<oid[2:4]>/<oid>`. */
+export function lfsObjectPath(objectsDir, oid) {
+    return join(objectsDir, oid.slice(0, 2), oid.slice(2, 4), oid);
+}
+// ---------------------------------------------------------------------------
+// Agent side
+// ---------------------------------------------------------------------------
+/**
+ * Copy into `<dir>/lfs/<oid>` the object of every pointer the commits
+ * `<ref> ^<baseSha>` add or change, from `repo`'s local store. An object the
+ * store lacks is left out: the apply job then rejects the handoff naming it
+ * (that is also the fate of a text file that parses as a pointer). Refuses
+ * ({@link HandoffRejected} `size`) objects over the LFS limit together.
+ * Returns the oids left out.
+ */
+export function writeLfsObjects(params) {
+    const { dir, repo, env } = params;
+    const commits = git(['rev-list', params.ref, `^${params.baseSha}`], repo, {
+        env,
+    })
+        .split('\n')
+        .filter((l) => l !== '');
+    const { pointers } = scanLfsPointers({
+        cwd: repo,
+        blobs: changedFileBlobs(repo, commits, env),
+        env,
+    });
+    const oids = [...new Set(pointers.map((p) => p.oid))].sort();
+    if (oids.length === 0)
+        return { missing: [] };
+    const store = localLfsObjectsDir(repo, env);
+    const present = [];
+    const missing = [];
+    let total = 0;
+    for (const oid of oids) {
+        const src = lfsObjectPath(store, oid);
+        if (!existsSync(src) || !statSync(src).isFile()) {
+            missing.push(oid);
+            continue;
+        }
+        total += statSync(src).size;
+        present.push(oid);
+    }
+    const limit = handoffByteLimits().lfsBytes;
+    if (total > limit) {
+        reject('size', `the LFS objects are over ${limit} bytes`);
+    }
+    if (present.length > 0) {
+        mkdirSync(join(dir, LFS_ARTIFACT_DIR), { recursive: true });
+        for (const oid of present) {
+            copyFileSync(lfsObjectPath(store, oid), join(dir, LFS_ARTIFACT_DIR, oid));
+        }
+    }
+    return { missing };
+}
+function q(path) {
+    return JSON.stringify(path.slice(0, 300));
+}
+/**
+ * Stream a regular file (refusing a symlink at open time) through sha256,
+ * reading at most `max + 1` bytes; optionally copy every byte read to `outFd`.
+ */
+function hashFile(path, max, outFd) {
+    let fd;
+    try {
+        fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch {
+        reject('symlink', `${q(path)} could not be opened as a regular file`);
+    }
+    try {
+        if (!fstatSync(fd).isFile()) {
+            reject('layout', `${q(path)} is not a regular file`);
+        }
+        const hash = createHash('sha256');
+        const buf = Buffer.alloc(1024 * 1024);
+        let size = 0;
+        while (size <= max) {
+            const n = readSync(fd, buf, 0, buf.length, null);
+            if (n === 0)
+                break;
+            hash.update(buf.subarray(0, n));
+            if (outFd !== undefined)
+                writeSync(outFd, buf, 0, n);
+            size += n;
+        }
+        return { sha256: hash.digest('hex'), size };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Check the artifact's LFS objects against the pointers the new commits carry
+ * (decision 6). Rejects ({@link HandoffRejected}): a blob that looks like a
+ * pointer but does not parse strictly (`lfs-pointer`); two pointers giving one
+ * oid different sizes, or an object whose size or hash differs from its
+ * pointer (`lfs-mismatch`); a pointer whose object is not in `lfs/`
+ * (`lfs-missing`); an object no pointer references (`lfs-extra`); a pointer, or
+ * all of them together, over the LFS limit (`size`). Returns the referenced
+ * objects, sorted by oid.
+ */
+export function checkLfsObjects(scan, objects) {
+    if (scan.malformed.length > 0) {
+        reject('lfs-pointer', `the file ${q(scan.malformed[0])} looks like a Git LFS pointer but is not a ` +
+            'strict spec v1 pointer (version, oid sha256:<64 hex>, size, in order, nothing else)');
+    }
+    const limit = handoffByteLimits().lfsBytes;
+    const want = new Map();
+    let total = 0;
+    for (const p of scan.pointers) {
+        if (p.size > limit) {
+            reject('size', `the LFS pointer ${q(p.path)} names a ${p.size}-byte object, over the ` +
+                `LFS limit of ${limit} bytes`);
+        }
+        const seen = want.get(p.oid);
+        if (seen !== undefined) {
+            if (seen.size !== p.size) {
+                reject('lfs-mismatch', `the LFS pointers ${q(seen.path)} and ${q(p.path)} give the object ` +
+                    `${p.oid} different sizes`);
+            }
+            continue;
+        }
+        want.set(p.oid, p);
+        total += p.size;
+    }
+    if (total > limit) {
+        reject('size', `the LFS objects are over ${limit} bytes`);
+    }
+    const byOid = new Map(objects.map((o) => [o.oid, o]));
+    for (const o of objects) {
+        if (!want.has(o.oid)) {
+            reject('lfs-extra', `lfs/${o.oid} is referenced by no LFS pointer of the new commits`);
+        }
+    }
+    const referenced = [];
+    for (const [oid, p] of [...want].sort(([a], [b]) => a.localeCompare(b))) {
+        const obj = byOid.get(oid);
+        if (obj === undefined) {
+            reject('lfs-missing', `the LFS object ${oid} of ${q(p.path)} is not in lfs/ (a text file ` +
+                'that parses as an LFS pointer counts as one)');
+        }
+        const got = hashFile(obj.path, p.size);
+        if (got.size !== p.size) {
+            reject('lfs-mismatch', `lfs/${oid} is ${got.size > p.size ? 'over ' : ''}${got.size} bytes, but ` +
+                `its pointer ${q(p.path)} says ${p.size} bytes`);
+        }
+        if (got.sha256 !== oid) {
+            reject('lfs-mismatch', `lfs/${oid} does not hash to its oid (its sha256 hash is ${got.sha256})`);
+        }
+        referenced.push(obj);
+    }
+    return referenced;
+}
+/**
+ * Stage the validated objects into `cwd`'s own LFS store and push them to
+ * `arbiter` with `git lfs push --object-id`, BEFORE any ref is pushed. `cwd`
+ * is the apply job's checkout of the trusted base, so `.lfsconfig` and the
+ * endpoint come from `main`. Every byte staged is hashed again as it is copied
+ * (a file that changed since validation rejects, `lfs-mismatch`); an object
+ * the store already holds is not copied. The upload itself is the write seam
+ * `refWrite.pushLfsObjects`. Returns the push's status and stderr.
+ */
+export async function pushLfsObjects(params) {
+    const { cwd, arbiter, objects, env } = params;
+    if (objects.length === 0)
+        return { status: 0, stderr: '' };
+    const store = localLfsObjectsDir(cwd, env);
+    for (const o of objects)
+        stageObject(store, o);
+    const r = await refWrite.pushLfsObjects({
+        arbiter,
+        oids: objects.map((o) => o.oid),
+        cwd,
+        env,
+    });
+    return { status: r.status, stderr: r.stderr };
+}
+function stageObject(store, o) {
+    const dest = lfsObjectPath(store, o.oid);
+    if (existsSync(dest))
+        return;
+    mkdirSync(dirname(dest), { recursive: true });
+    const tmp = `${dest}.dorfl-${process.pid}.tmp`;
+    const out = openSync(tmp, 'w', 0o644);
+    let got;
+    try {
+        got = hashFile(o.path, o.size, out);
+    }
+    finally {
+        closeSync(out);
+    }
+    if (got.size !== o.size || got.sha256 !== o.oid) {
+        rmSync(tmp, { force: true });
+        reject('lfs-mismatch', `lfs/${o.oid} changed after it was validated`);
+    }
+    renameSync(tmp, dest);
+}
+//# sourceMappingURL=ci-handoff-lfs.js.map

package/dist/ci-handoff-lfs.js.map

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

package/dist/ci-handoff.d.ts

@@ -0,0 +1,99 @@
+/**
+ * **The CI handoff artifact on disk**: the writer (agent job) and the safe
+ * reader (apply job). The record format and its intent table are
+ * `ci-handoff-format.ts`.
+ *
+ * The artifact directory holds exactly:
+ *
+ *   - `handoff.json`: the record;
+ *   - `work.bundle`: for code-carrying intents only, `git bundle create
+ *     work.bundle <work-branch> ^<baseSha>`, exactly one ref;
+ *   - `lfs/<oid>`: the object of every LFS pointer the bundle's new commits
+ *     add or change (`ci-handoff-lfs.ts`; the reader here checks only their
+ *     names and sizes, the apply validation checks them against the pointers).
+ *
+ * The reader treats the directory as HOSTILE (the agent controls everything in
+ * its job): it must sit under `$RUNNER_TEMP`, only those names are read, a
+ * symlink or any other entry rejects the whole handoff, files are opened with
+ * `O_NOFOLLOW`, and every size limit is checked before anything is parsed. The
+ * bundle header is parsed here without running git on hostile bytes; the
+ * bundle's CONTENT (history, protected paths) is task
+ * `ci-split-apply-rejects-hostile-bundle`.
+ */
+import { type HandoffRecord, type HandoffRung, type HandoffTrust, type IntentRow } from './ci-handoff-format.js';
+/** The record file of the artifact. */
+export declare const HANDOFF_JSON = "handoff.json";
+/** The git bundle of the work branch (code-carrying intents only). */
+export declare const HANDOFF_BUNDLE = "work.bundle";
+/** The directory of LFS objects, one file per oid. */
+export declare const HANDOFF_LFS_DIR = "lfs";
+/** What a bundle header says: its one ref, the ref's tip and the prerequisites. */
+export interface BundleHeader {
+    ref: string;
+    tip: string;
+    prerequisites: string[];
+}
+/**
+ * Parse the header of a git bundle (v2, or v3 with only `@object-format`)
+ * without running git, and require exactly one ref.
+ */
+export declare function parseBundleHeader(head: Buffer): BundleHeader;
+/** What {@link writeHandoff} needs to also write `work.bundle`. */
+export interface HandoffBundleSource {
+    /** The repository (the agent job's checkout). */
+    repo: string;
+    /** The work branch name; the bundle's one ref is `refs/heads/<workBranch>`. */
+    workBranch: string;
+    /** The trusted base: the bundle holds `<workBranch> ^<baseSha>`. */
+    baseSha: string;
+}
+/**
+ * Write the handoff into `dir` (created, and required to be empty): validate
+ * the record exactly as the reader will, then write `handoff.json` and, for a
+ * code-carrying intent, `work.bundle` with exactly one ref, and `lfs/<oid>` for
+ * the object of every LFS pointer its new commits add or change (from the
+ * local store; one the store lacks is left out and returned in `lfsMissing`,
+ * and the apply job then rejects the handoff naming it). The record's item is
+ * written in its canonical form.
+ */
+export declare function writeHandoff(params: {
+    dir: string;
+    rung: HandoffRung;
+    record: HandoffRecord;
+    bundle?: HandoffBundleSource;
+}): {
+    lfsMissing: string[];
+};
+/** An LFS object file of the artifact (checked against pointers elsewhere). */
+export interface HandoffLfsObject {
+    oid: string;
+    path: string;
+    size: number;
+}
+/** A read, validated handoff. */
+export interface ReadHandoff {
+    record: HandoffRecord;
+    /** The intent table row the record was validated against. */
+    row: IntentRow;
+    /** `work.bundle` with its parsed header, when the artifact carries one. */
+    bundle?: {
+        path: string;
+        size: number;
+    } & BundleHeader;
+    lfsObjects: HandoffLfsObject[];
+}
+/**
+ * Read and validate the handoff the agent job uploaded. `dir` is where the
+ * artifact was downloaded: a real directory strictly inside `runnerTemp`
+ * (`$RUNNER_TEMP`). Rejects ({@link HandoffRejected}) a symlink anywhere, any
+ * entry but `handoff.json`, `work.bundle` and `lfs/<64-hex oid>`, any size over
+ * the byte limits (`handoffByteLimits`), a record that fails `validateHandoffRecord`, a bundle
+ * the intent forbids or lacks, `lfs/` without a bundle, and a bundle whose
+ * header is malformed or carries other than one ref.
+ */
+export declare function readHandoff(params: {
+    dir: string;
+    runnerTemp: string;
+    trust: HandoffTrust;
+}): ReadHandoff;
+//# sourceMappingURL=ci-handoff.d.ts.map