@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/dist/lib/platform/pr-summary.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { enumerateArtifacts } from '../task/artifacts.js';
 import { parseTaskFrontmatter } from '../task/frontmatter.js';
+import { renderHumanOverrideAudit } from '../task/human-override.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { resolvePlatformContext } from './context.js';
 import { createGitHubClient } from './github-client.js';
@@ -10,8 +11,9 @@ import { platformResult } from './types.js';
 function summaryMarker(taskId) {
     return `<!-- sync-pr:${taskId}:summary -->`;
 }
-function buildPullRequestSummary(taskId, body, headSha) {
-    return normalizeCommentContent(`${summaryMarker(taskId)}\n<!-- last-commit: ${headSha} -->\n\n${body.replace(/\s+$/, '')}\n`);
+function buildPullRequestSummary(taskId, body, headSha, humanOverrideAudit = '') {
+    const sections = [body.replace(/\s+$/, ''), humanOverrideAudit.trim()].filter(Boolean).join('\n\n');
+    return normalizeCommentContent(`${summaryMarker(taskId)}\n<!-- last-commit: ${headSha} -->\n\n${sections}\n`);
 }
 function reconcileSummaryComment(comments, taskId, desired) {
     const marker = summaryMarker(taskId);
@@ -67,7 +69,7 @@ function syncPullRequestSummary(taskRef, options) {
     catch (error) {
         return platformResult('failed', { platform: context.platform, capabilities: context.capabilities, error: { code: 'GIT_HEAD_UNRESOLVED', message: error instanceof Error ? error.message : String(error), retryable: false } });
     }
-    const desired = buildPullRequestSummary(resolved.taskId, options.body, headSha);
+    const desired = buildPullRequestSummary(resolved.taskId, options.body, headSha, renderHumanOverrideAudit(fs.readFileSync(resolved.taskMdPath, 'utf8')));
     const listed = listRemoteComments(client, context.platform.repository, prNumber, resolved.repoRoot);
     if (!listed.ok)
         return platformResult(listed.error.retryable ? 'blocked' : 'failed', { platform: context.platform, capabilities: context.capabilities, resource: { kind: 'pull-request', number: prNumber }, error: listed.error });

package/dist/lib/process-data/checkpoint.js

@@ -0,0 +1,319 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { verifySnapshot } from './store.js';
+function repositoryKey(repository) {
+    return crypto.createHash('sha256').update(repository).digest('hex').slice(0, 32);
+}
+function checkpointPaths(root, repository) {
+    const directory = path.join(root, 'checkpoints', 'github');
+    const base = path.join(directory, repositoryKey(repository));
+    return { directory, checkpoint: `${base}.json`, lock: `${base}.lock` };
+}
+function processStartToken(pid) {
+    if (process.platform === 'linux') {
+        try {
+            const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+            const closing = stat.lastIndexOf(')');
+            const fields = stat.slice(closing + 2).split(' ');
+            return fields[19] ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return pid === process.pid ? `self:${process.pid}` : null;
+}
+function fsyncDirectory(directory) {
+    if (process.platform === 'win32')
+        return;
+    const fd = fs.openSync(directory, 'r');
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function ensurePrivateDirectory(directory) {
+    const missing = [];
+    let current = path.resolve(directory);
+    while (!fs.existsSync(current)) {
+        missing.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            throw new Error(`cannot create directory tree: ${directory}`);
+        current = parent;
+    }
+    for (const target of missing.reverse()) {
+        fs.mkdirSync(target, { mode: 0o700 });
+        if (process.platform !== 'win32')
+            fs.chmodSync(target, 0o700);
+        fsyncDirectory(path.dirname(target));
+    }
+}
+function writeTemporary(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    const fd = fs.openSync(temporary, 'wx', 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(value)}\n`);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return temporary;
+}
+function validCheckpoint(value, repository) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const checkpoint = value;
+    return checkpoint.schema === 'github-checkpoint/v1'
+        && checkpoint.repository === repository
+        && Boolean(checkpoint.snapshotId)
+        && Boolean(checkpoint.watermark)
+        && Boolean(checkpoint.committedAt)
+        && /^[a-f0-9]{64}$/.test(checkpoint.manifestSha256);
+}
+function checkpointMatchesSnapshot(root, value) {
+    const verified = verifySnapshot(root, value.snapshotId);
+    return verified.ok
+        && verified.manifest?.schema === 'raw-manifest/v2'
+        && verified.manifest.snapshotId === value.snapshotId
+        && verified.manifest.repository === value.repository
+        && verified.manifest.manifestSha256 === value.manifestSha256
+        && verified.manifest.watermark === value.watermark;
+}
+function checkpointState(value) {
+    return { snapshotId: value?.snapshotId ?? null, manifestSha256: value?.manifestSha256 ?? null };
+}
+function readGitHubCheckpoint(root, repository) {
+    const target = checkpointPaths(root, repository).checkpoint;
+    if (!fs.existsSync(target))
+        return { ok: true, value: null };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(target, 'utf8'));
+        const value = {
+            schema: parsed.schema,
+            repository: parsed.repository,
+            snapshotId: parsed.snapshotId,
+            watermark: parsed.watermark,
+            manifestSha256: parsed.manifestSha256,
+            committedAt: parsed.committedAt
+        };
+        if (!validCheckpoint(value, repository)) {
+            return { ok: false, error: { code: 'CHECKPOINT_INVALID', message: 'GitHub checkpoint schema or identity is invalid' } };
+        }
+        return { ok: true, value };
+    }
+    catch {
+        return { ok: false, error: { code: 'CHECKPOINT_INVALID', message: 'GitHub checkpoint is not valid JSON' } };
+    }
+}
+function quarantine(lockPath) {
+    const target = `${lockPath}.orphaned-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+    fs.renameSync(lockPath, target);
+    return target;
+}
+function acquireGitHubCheckpoint(root, repository) {
+    const paths = checkpointPaths(root, repository);
+    ensurePrivateDirectory(paths.directory);
+    const recovery = { recovered: false, quarantined: [] };
+    const owner = {
+        schema: 'checkpoint-owner/v1',
+        ownerId: crypto.randomUUID(),
+        pid: process.pid,
+        host: os.hostname(),
+        processStartToken: processStartToken(process.pid) ?? '',
+        createdAt: new Date().toISOString()
+    };
+    if (!owner.processStartToken) {
+        return { ok: false, error: { code: 'CHECKPOINT_TOPOLOGY_UNSUPPORTED', message: 'Process liveness cannot be verified on this host' } };
+    }
+    let recoveredOwnerId = null;
+    if (fs.existsSync(paths.lock)) {
+        let previous;
+        try {
+            previous = JSON.parse(fs.readFileSync(paths.lock, 'utf8'));
+        }
+        catch {
+            return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint lock is unreadable' } };
+        }
+        if (previous.host !== owner.host || !previous.ownerId || !previous.processStartToken) {
+            return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint lock owner topology is unknown' } };
+        }
+        const currentToken = processStartToken(previous.pid);
+        if (currentToken && currentToken === previous.processStartToken) {
+            return { ok: false, error: { code: 'CHECKPOINT_BUSY', message: 'Checkpoint is held by a live process' } };
+        }
+        if (process.platform !== 'linux') {
+            return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint owner liveness cannot be proven on this host' } };
+        }
+        try {
+            recoveredOwnerId = previous.ownerId;
+            recovery.quarantined.push(quarantine(paths.lock));
+            recovery.recovered = true;
+        }
+        catch {
+            return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Unable to quarantine an orphaned checkpoint lock' } };
+        }
+    }
+    try {
+        const fd = fs.openSync(paths.lock, 'wx', 0o600);
+        try {
+            fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fsyncDirectory(paths.directory);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return { ok: false, error: { code: 'CHECKPOINT_BUSY', message: 'Checkpoint lock was acquired by another process' } };
+        }
+        return { ok: false, error: { code: 'CHECKPOINT_LOCK_FAILED', message: String(error) } };
+    }
+    const releaseOwnedLock = () => {
+        try {
+            fs.unlinkSync(paths.lock);
+            fsyncDirectory(paths.directory);
+        }
+        catch {
+            // Preserve the original recovery error; a remaining lock will fail closed next time.
+        }
+    };
+    const beforeResult = readGitHubCheckpoint(root, repository);
+    if (!beforeResult.ok) {
+        releaseOwnedLock();
+        return beforeResult;
+    }
+    let checkpointBefore = beforeResult.value;
+    const temporaryCandidates = fs.readdirSync(paths.directory)
+        .filter((entry) => entry.startsWith(path.basename(paths.checkpoint) + '.') && entry.endsWith('.tmp'))
+        .map((entry) => path.join(paths.directory, entry));
+    if (temporaryCandidates.length > 1) {
+        releaseOwnedLock();
+        return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Multiple checkpoint recovery candidates exist' } };
+    }
+    if (temporaryCandidates.length === 1) {
+        const candidate = temporaryCandidates[0];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+            const isCandidate = parsed && typeof parsed === 'object' && 'candidateSchema' in parsed
+                && parsed.candidateSchema === 'github-checkpoint-candidate/v1';
+            if (isCandidate) {
+                const candidateValue = parsed;
+                const value = candidateValue;
+                const expected = checkpointState(checkpointBefore);
+                const candidateExpected = candidateValue.expectedOld;
+                if (!recoveredOwnerId || candidateValue.ownerId !== recoveredOwnerId) {
+                    recovery.quarantined.push(quarantine(candidate));
+                    releaseOwnedLock();
+                    return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint candidate owner proof does not match the recovered lock owner' } };
+                }
+                if (!validCheckpoint(value, repository)
+                    || candidateExpected?.snapshotId !== expected.snapshotId
+                    || candidateExpected?.manifestSha256 !== expected.manifestSha256) {
+                    releaseOwnedLock();
+                    return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint candidate does not match the current head' } };
+                }
+                if (!checkpointMatchesSnapshot(root, value)) {
+                    recovery.quarantined.push(quarantine(candidate));
+                    releaseOwnedLock();
+                    return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint candidate snapshot failed full verification' } };
+                }
+                if (process.platform === 'win32' && checkpointBefore) {
+                    releaseOwnedLock();
+                    return { ok: false, error: { code: 'CHECKPOINT_TOPOLOGY_UNSUPPORTED', message: 'Checkpoint replacement durability cannot be proven on this host' } };
+                }
+                fs.renameSync(candidate, paths.checkpoint);
+                recovery.recovered = true;
+                fsyncDirectory(paths.directory);
+                const recovered = readGitHubCheckpoint(root, repository);
+                if (!recovered.ok) {
+                    releaseOwnedLock();
+                    return recovered;
+                }
+                checkpointBefore = recovered.value;
+            }
+            else {
+                recovery.quarantined.push(quarantine(candidate));
+                releaseOwnedLock();
+                return { ok: false, error: { code: 'CHECKPOINT_RECOVERY_REQUIRED', message: 'Checkpoint candidate lacks owner proof' } };
+            }
+        }
+        catch {
+            recovery.quarantined.push(quarantine(candidate));
+        }
+    }
+    return { ok: true, value: { paths, repository, owner, recovery, expectedOld: checkpointBefore } };
+}
+function commitGitHubCheckpoint(lease, value) {
+    try {
+        const current = JSON.parse(fs.readFileSync(lease.paths.lock, 'utf8'));
+        if (current.ownerId !== lease.owner.ownerId) {
+            return { ok: false, error: { code: 'CHECKPOINT_OWNER_MISMATCH', message: 'Checkpoint lock ownership changed' } };
+        }
+        if (value.repository !== lease.repository || !validCheckpoint(value, lease.repository)) {
+            return { ok: false, error: { code: 'CHECKPOINT_INVALID', message: 'Checkpoint value is invalid' } };
+        }
+        const root = path.dirname(path.dirname(lease.paths.directory));
+        if (!checkpointMatchesSnapshot(root, value)) {
+            return { ok: false, error: { code: 'CHECKPOINT_INVALID', message: 'Checkpoint snapshot does not match a verified v2 manifest' } };
+        }
+        const currentCheckpoint = readGitHubCheckpoint(root, lease.repository);
+        if (!currentCheckpoint.ok)
+            return currentCheckpoint;
+        if (checkpointState(currentCheckpoint.value).snapshotId !== checkpointState(lease.expectedOld).snapshotId
+            || checkpointState(currentCheckpoint.value).manifestSha256 !== checkpointState(lease.expectedOld).manifestSha256) {
+            return { ok: false, error: { code: 'CHECKPOINT_CONFLICT', message: 'Checkpoint head changed before commit' } };
+        }
+        const candidate = {
+            ...value,
+            candidateSchema: 'github-checkpoint-candidate/v1',
+            ownerId: lease.owner.ownerId,
+            expectedOld: checkpointState(lease.expectedOld)
+        };
+        const temporary = writeTemporary(lease.paths.checkpoint, candidate);
+        const rechecked = readGitHubCheckpoint(root, lease.repository);
+        if (!rechecked.ok) {
+            fs.unlinkSync(temporary);
+            return rechecked;
+        }
+        if (checkpointState(rechecked.value).snapshotId !== checkpointState(lease.expectedOld).snapshotId
+            || checkpointState(rechecked.value).manifestSha256 !== checkpointState(lease.expectedOld).manifestSha256) {
+            fs.unlinkSync(temporary);
+            return { ok: false, error: { code: 'CHECKPOINT_CONFLICT', message: 'Checkpoint head changed during commit' } };
+        }
+        if (process.platform === 'win32' && fs.existsSync(lease.paths.checkpoint)) {
+            fs.unlinkSync(temporary);
+            return { ok: false, error: { code: 'CHECKPOINT_TOPOLOGY_UNSUPPORTED', message: 'Checkpoint replacement durability cannot be proven on this host' } };
+        }
+        fs.renameSync(temporary, lease.paths.checkpoint);
+        if (process.platform !== 'win32')
+            fs.chmodSync(lease.paths.checkpoint, 0o600);
+        fsyncDirectory(lease.paths.directory);
+        return { ok: true, value: undefined };
+    }
+    catch (error) {
+        return { ok: false, error: { code: 'CHECKPOINT_COMMIT_FAILED', message: String(error) } };
+    }
+}
+function releaseGitHubCheckpoint(lease) {
+    try {
+        const current = JSON.parse(fs.readFileSync(lease.paths.lock, 'utf8'));
+        if (current.ownerId === lease.owner.ownerId) {
+            fs.unlinkSync(lease.paths.lock);
+            fsyncDirectory(lease.paths.directory);
+        }
+    }
+    catch {
+        // The next invocation will fail closed and report recovery if the lock remains.
+    }
+}
+export { acquireGitHubCheckpoint, checkpointPaths, commitGitHubCheckpoint, processStartToken, readGitHubCheckpoint, releaseGitHubCheckpoint };
+//# sourceMappingURL=checkpoint.js.map

package/dist/lib/process-data/index.js

@@ -1,20 +1,22 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
 import { detectRepoRoot } from '../task/resolve-ref.js';
-import { normalizeObjects } from './normalize.js';
-import { reconcileRecords } from './reconcile.js';
+import { acquireGitHubCheckpoint, commitGitHubCheckpoint, readGitHubCheckpoint, releaseGitHubCheckpoint } from './checkpoint.js';
+import { materializeJson, materializeSnapshot } from './materialize.js';
+import { normalizeResources } from './normalize.js';
+import { reconcileRecords, reconcileResourceRecords } from './reconcile.js';
 import { readAppliedOverlays, repairSnapshot } from './repair.js';
-import { collectGitHubObjects, collectLocalObjects } from './sources.js';
-import { canonicalJsonBytes, createObjectStore, publishSnapshot, verifySnapshot } from './store.js';
+import { collectGitHubBoundary, resolveGitHubRepository } from './sources.js';
+import { canonicalJsonBytes, createObjectStore, findSnapshot, publishSnapshotV2, verifySnapshot } from './store.js';
+import { createGitHubClient } from '../platform/github-client.js';
 const USAGE = `Usage: ai data <command> [options]
 
 Commands:
-  capture [--source all|local|github] [--root <dir>] [--include-excerpts]
+  capture [--source github] [--root <dir>] [--full-reconcile]
   verify <snapshot-id> [--root <dir>]
   audit <snapshot-id> [--root <dir>] [--format json|text]
   repair <snapshot-id> [--root <dir>] [--apply]
-  export <snapshot-id> [--root <dir>] [--repairs none|applied] [--output <file|->]
+  export <snapshot-id> [--root <dir>] [--repairs none|applied] [--as-of <ISO>] [--output <file|->]
 `;
 function parseArgs(args, valueOptions, booleanOptions) {
     const positionals = [];
@@ -61,14 +63,6 @@ function dataRoot(repoRoot, requested) {
     }
     return resolved;
 }
-function repositoryIdentity(repoRoot) {
-    try {
-        return execFileSync('git', ['config', '--get', 'remote.origin.url'], { cwd: repoRoot, encoding: 'utf8' }).trim() || path.basename(repoRoot);
-    }
-    catch {
-        return path.basename(repoRoot);
-    }
-}
 function writeJson(value) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
 }
@@ -77,61 +71,127 @@ function optionString(parsed, name) {
     return typeof value === 'string' ? value : undefined;
 }
 function capture(args) {
-    const parsed = parseArgs(args, new Set(['--source', '--root']), new Set(['--include-excerpts']));
+    const parsed = parseArgs(args, new Set(['--source', '--root']), new Set(['--full-reconcile', '--include-excerpts']));
     if (parsed.positionals.length > 0)
         throw new Error('capture does not accept positional arguments');
-    const scope = optionString(parsed, '--source') ?? 'all';
-    if (!['all', 'local', 'github'].includes(scope))
-        throw new Error('--source must be all, local, or github');
+    const scope = optionString(parsed, '--source') ?? 'github';
+    if (scope !== 'github')
+        throw new Error('new process-data capture only supports --source github; local data is already normalized and --source all is retired');
+    if (parsed.options.has('--include-excerpts'))
+        throw new Error('--include-excerpts is not supported for GitHub-only capture');
     const repoRoot = detectRepoRoot();
     const root = dataRoot(repoRoot, optionString(parsed, '--root'));
-    const observedFrom = new Date().toISOString();
-    const objects = [];
-    const endpoints = [];
-    let repository = repositoryIdentity(repoRoot);
-    if (scope === 'all' || scope === 'local') {
-        const local = collectLocalObjects(repoRoot, { includeExcerpts: parsed.options.has('--include-excerpts') });
-        if (!local.ok) {
-            writeJson({ ok: false, error: local.error });
+    const client = createGitHubClient();
+    const repositoryResult = resolveGitHubRepository(repoRoot, client);
+    if (!repositoryResult.ok) {
+        writeJson({ ok: false, error: repositoryResult.error });
+        return 2;
+    }
+    const repository = repositoryResult.value;
+    const leaseResult = acquireGitHubCheckpoint(root, repository);
+    if (!leaseResult.ok) {
+        writeJson({ ok: false, error: leaseResult.error });
+        return 2;
+    }
+    const lease = leaseResult.value;
+    try {
+        const checkpointResult = readGitHubCheckpoint(root, repository);
+        if (!checkpointResult.ok) {
+            writeJson({ ok: false, error: checkpointResult.error });
             return 2;
         }
-        objects.push(...local.value);
-    }
-    if (scope === 'all' || scope === 'github') {
-        const github = collectGitHubObjects(repoRoot);
+        const checkpoint = checkpointResult.value;
+        const full = parsed.options.has('--full-reconcile');
+        const observedFrom = new Date().toISOString();
+        const github = collectGitHubBoundary(repoRoot, {
+            client,
+            fromInclusive: full ? null : checkpoint?.watermark ?? null,
+            reconciliation: full ? 'full' : 'incremental'
+        });
         if (!github.ok) {
             writeJson({ ok: false, error: github.error });
             return 2;
         }
-        objects.push(...github.value.objects);
-        endpoints.push(...github.value.endpoints);
-        repository = github.value.repository;
-    }
-    const store = createObjectStore(root);
-    for (const object of objects) {
-        if (object.content !== undefined && object.disposition?.state === 'included') {
-            const stored = store.put(Buffer.from(object.content, 'utf8'));
-            if (stored.sha256 !== object.sha256)
-                throw new Error(`source hash mismatch: ${object.sourceIdentity}`);
+        const store = createObjectStore(root);
+        for (const object of github.value.objects) {
+            if (object.content !== undefined && object.disposition?.state === 'included') {
+                const stored = store.put(Buffer.from(object.content, 'utf8'));
+                if (stored.sha256 !== object.sha256)
+                    throw new Error(`source hash mismatch: ${object.sourceIdentity}`);
+            }
+        }
+        let parent = [];
+        if (checkpoint) {
+            const parentPath = findSnapshot(root, checkpoint.snapshotId);
+            if (!parentPath)
+                throw new Error(`checkpoint head snapshot is missing: ${checkpoint.snapshotId}`);
+            const materialized = materializeSnapshot(root, checkpoint.snapshotId);
+            if (!materialized.manifest || materialized.manifest.manifestSha256 !== checkpoint.manifestSha256 || materialized.manifest.watermark !== checkpoint.watermark) {
+                throw new Error('checkpoint does not match its verified snapshot head');
+            }
+            parent = materialized.records;
         }
+        const current = normalizeResources(github.value.objects);
+        const reconciliation = reconcileResourceRecords(current, {
+            parent,
+            full,
+            deferred: github.value.deferred,
+            unavailable: github.value.unavailable
+        });
+        const quality = reconcileRecords(reconciliation.records, 'github');
+        const fromInclusive = checkpoint?.watermark ?? null;
+        const hasStrictSinceEndpoint = github.value.endpoints.some((endpoint) => endpoint.queryMode === 'strict-since');
+        const queryAfter = !full && fromInclusive && hasStrictSinceEndpoint
+            ? new Date(new Date(fromInclusive).getTime() - 1000).toISOString()
+            : null;
+        const responseDates = github.value.responseDates;
+        const published = publishSnapshotV2(root, {
+            scope: 'github',
+            repository,
+            observedFrom,
+            observedTo: github.value.watermark,
+            objects: github.value.objects.map(({ content: _content, ...object }) => object),
+            endpoints: github.value.endpoints,
+            excerptsEnabled: false,
+            records: reconciliation.records,
+            quality: quality.findings,
+            repairs: quality.repairs,
+            snapshotKind: checkpoint ? 'delta' : 'base',
+            parentSnapshotId: checkpoint?.snapshotId ?? null,
+            checkpointBefore: checkpoint?.snapshotId ?? null,
+            watermark: github.value.watermark,
+            window: { fromInclusive, queryAfter, toExclusive: github.value.watermark, precision: 'second' },
+            observation: {
+                cutoffSource: 'github-response-date',
+                preflightDate: github.value.preflightDate,
+                responseDates
+            },
+            coverage: { mode: 'boundary-reread-with-full-reconcile', absoluteCompleteness: false },
+            reconciliation: full ? 'full' : 'incremental',
+            operations: reconciliation.operations
+        });
+        const verified = verifySnapshot(root, published.snapshotId);
+        if (!verified.ok || !verified.manifest || verified.manifest.schema !== 'raw-manifest/v2') {
+            throw new Error(`published snapshot failed verification: ${verified.errors.join('; ')}`);
+        }
+        const committed = commitGitHubCheckpoint(lease, {
+            schema: 'github-checkpoint/v1',
+            repository,
+            snapshotId: published.snapshotId,
+            watermark: github.value.watermark,
+            manifestSha256: verified.manifest.manifestSha256,
+            committedAt: new Date().toISOString()
+        });
+        if (!committed.ok) {
+            writeJson({ ok: false, error: committed.error });
+            return 2;
+        }
+        writeJson({ ok: true, snapshotId: published.snapshotId, scope, snapshotKind: checkpoint ? 'delta' : 'base', reconciliation: full ? 'full' : 'incremental', created: published.created, objects: github.value.objects.length, records: reconciliation.records.length, watermark: github.value.watermark, deferred: github.value.deferred.length });
+        return 0;
+    }
+    finally {
+        releaseGitHubCheckpoint(lease);
     }
-    const records = normalizeObjects(objects);
-    const reconciliation = reconcileRecords(records, scope);
-    const observedTo = new Date().toISOString();
-    const published = publishSnapshot(root, {
-        scope: scope,
-        repository,
-        observedFrom,
-        observedTo,
-        objects: objects.map(({ content: _content, ...object }) => object),
-        endpoints,
-        excerptsEnabled: parsed.options.has('--include-excerpts'),
-        records,
-        quality: reconciliation.findings,
-        repairs: reconciliation.repairs
-    });
-    writeJson({ ok: true, snapshotId: published.snapshotId, scope, created: published.created, objects: objects.length, records: records.length });
-    return 0;
 }
 function verify(args) {
     const parsed = parseArgs(args, new Set(['--root']), new Set());
@@ -182,7 +242,7 @@ function repair(args) {
     return 0;
 }
 function exportSnapshot(args) {
-    const parsed = parseArgs(args, new Set(['--root', '--repairs', '--output']), new Set());
+    const parsed = parseArgs(args, new Set(['--root', '--repairs', '--output', '--as-of']), new Set());
     if (parsed.positionals.length !== 1)
         throw new Error('export requires one snapshot id');
     const repairMode = optionString(parsed, '--repairs') ?? 'none';
@@ -196,7 +256,15 @@ function exportSnapshot(args) {
         writeJson(verified);
         return 1;
     }
-    let content = fs.readFileSync(path.join(verified.snapshotPath, 'normalized.jsonl'), 'utf8');
+    let content;
+    if (verified.manifest?.schema === 'raw-manifest/v2') {
+        content = materializeJson(root, parsed.positionals[0], { asOf: optionString(parsed, '--as-of') });
+    }
+    else {
+        if (optionString(parsed, '--as-of'))
+            throw new Error('--as-of is only supported for v2 GitHub snapshots');
+        content = fs.readFileSync(path.join(verified.snapshotPath, 'normalized.jsonl'), 'utf8');
+    }
     if (repairMode === 'applied')
         content += readAppliedOverlays(root, parsed.positionals[0]);
     if (output === '-')