@fro.bot/wiki-write-core 0.1.1 → 0.1.3

package/dist/gate-contract.js

@@ -1,4 +1,4 @@
 // Bump deliberately when an intentional consumer-visible gate contract break ships.
 export const GATE_CONTRACT_VERSION = 1;
 // Replaced with the deterministic source-tree hash by the package build.
-export const GATE_SOURCE_TREE_HASH = '9d17212cc85afbc7cb228fdce2cb436caa29ec2b0ba7c2f3e06b0db0de3b16be';
+export const GATE_SOURCE_TREE_HASH = '4c87f6366faeed604a910d0da221bd2d4a9661e9b83ec230c9345829bc0406f2';

package/dist/gate-contract.json

@@ -1 +1 @@
-{"version":1,"sourceTreeHash":"9d17212cc85afbc7cb228fdce2cb436caa29ec2b0ba7c2f3e06b0db0de3b16be"}
+{"version":1,"sourceTreeHash":"4c87f6366faeed604a910d0da221bd2d4a9661e9b83ec230c9345829bc0406f2"}

package/dist/wiki-ingest.d.ts

@@ -31,6 +31,16 @@ export interface BuildWikiIngestChangesParams {
     trackedMetadataAvailable?: boolean;
     /** System-owned correction state used for post-regeneration survival verification. */
     corrections?: CorrectionsFile;
+    /**
+     * Log entries an agent appended to its own `knowledge/log.md`, derived by the caller. Appended to
+     * the existing log, before this ingest's own summary entry.
+     */
+    agentLogEntries?: string;
+    /**
+     * Pages an agent deleted in a handoff, already removed from `existingFiles`. They join the result's
+     * `deletedPaths`, and a call with only deletions needs no page updates.
+     */
+    handoffDeletedPaths?: readonly string[];
 }
 export interface BuildWikiIngestChangesResult {
     files: Record<string, string>;
@@ -38,9 +48,9 @@ export interface BuildWikiIngestChangesResult {
     findings: readonly WikiLintFinding[];
 }
 export interface WikiIngestWarning {
-    code: 'duplicate-repo-identity' | 'repos-metadata-unavailable';
+    code: 'duplicate-repo-identity' | 'repos-metadata-unavailable' | 'agent-log-entries-dropped';
     node_ids?: string[];
-    reason?: 'read-failed' | 'parse-failed';
+    reason?: 'read-failed' | 'parse-failed' | 'not-append-only';
     slugs?: string[];
 }
 export interface TrackedRepoNodeIdsResult {
@@ -55,11 +65,36 @@ export interface CommitWikiChangesParams {
     message: string;
     files: Record<string, string>;
     deletedPaths?: readonly string[];
+    /**
+     * The data-branch commit `files` and `deletedPaths` were derived from: the base of the write guard.
+     * Every attempt, the first included, compares each write-set path on the head it reads with the same
+     * path in this commit's tree and fails closed if any differs.
+     * - A commit SHA: that commit's tree is the base. It is resolved once and never re-read, so the base
+     *   stays fixed across retries.
+     * - Omitted: the head tree of the first successful read in this call is the base, so only changes
+     *   after that read are caught.
+     */
+    baseCommitSha?: string;
+    /**
+     * A second, per-path base for a write whose pages were edited by an agent job in an earlier job.
+     * `agentCommitSha` is the data commit that job synced; `paths` are the pages it changed or deleted
+     * (`knowledge/log.md` and `knowledge/index.md` are ignored here: the writer rebuilds both itself).
+     *
+     * Before any write, the commit must resolve and be an ancestor of the branch head, or the call fails
+     * with `HANDOFF_BASE_INVALID`. Every attempt then compares each path on the head it reads with the
+     * same path in that commit's tree, ahead of the `baseCommitSha` check, and fails with
+     * `HANDOFF_PAGE_CHANGED` if any differs: another writer edited or deleted the page since the agent
+     * read it.
+     */
+    handoff?: {
+        agentCommitSha: string;
+        paths: readonly string[];
+    };
     octokit?: OctokitClient;
     maxRetries?: number;
     /**
      * Idempotent data-branch bootstrap. Called before data-branch writes so wiki
-     * ingest recovers when GitHub deletes the `data` source ref after promotion.
+     * ingest recovers when the `data` branch is missing: it recreates the branch from `main`.
      */
     bootstrapDataBranch?: (params: DataBranchBootstrapParams) => Promise<DataBranchBootstrapResult>;
 }
@@ -72,13 +107,15 @@ export interface RunWikiIngestCliDependencies {
     readonly readCorrections?: typeof readCorrections;
     readonly commitWikiChanges?: typeof commitWikiChanges;
     readonly getChangedWikiPaths?: typeof getChangedWikiPaths;
+    /** Client for reading the agent's base commit; defaults to one built from `GITHUB_TOKEN`. */
+    readonly octokit?: OctokitClient;
 }
 /**
  * Narrow Octokit client type derived from the real `@octokit/rest` SDK.
  * See commit-metadata.ts for the rationale behind deriving rather than handwriting.
  */
 export type OctokitClient = Octokit;
-export type WikiIngestErrorCode = 'INVALID_PAYLOAD' | 'INVALID_PAGE_PATH' | 'INVALID_FRONTMATTER' | 'INVALID_WIKILINK' | 'CORRECTION_ERODED' | 'INVALID_RETRIES' | 'PROTECTED_BRANCH' | 'MISSING_TOKEN' | 'OCTOKIT_LOAD_FAILED' | 'CONFLICT_EXHAUSTED';
+export type WikiIngestErrorCode = 'INVALID_PAYLOAD' | 'INVALID_PAGE_PATH' | 'INVALID_FRONTMATTER' | 'INVALID_WIKILINK' | 'CORRECTION_ERODED' | 'INVALID_RETRIES' | 'PROTECTED_BRANCH' | 'MISSING_TOKEN' | 'OCTOKIT_LOAD_FAILED' | 'CONFLICT_EXHAUSTED' | 'HANDOFF_BASE_INVALID' | 'HANDOFF_PAGE_CHANGED';
 export declare class WikiIngestError extends Error {
     readonly code: WikiIngestErrorCode;
     readonly remediation: string;
@@ -90,7 +127,21 @@ export declare class WikiIngestError extends Error {
         findings?: readonly WikiLintFinding[];
     });
 }
+/** The two wiki files every writer shares. Writers rebuild both from their own sync; a handoff never supplies them. */
+export declare function isSharedWikiFile(path: string): boolean;
 export declare function buildWikiIngestChanges(params: BuildWikiIngestChangesParams): BuildWikiIngestChangesResult;
+/**
+ * Commits `params.files` (and removes `params.deletedPaths`) as one commit on the data branch.
+ *
+ * Every attempt is guarded: if any path in the write set (files and deletions) differs on the head read
+ * in that attempt from the tree the files were derived from (`baseCommitSha`, or the first head read
+ * when it is omitted), another writer changed it, so the write fails with `CONFLICT_EXHAUSTED` and
+ * nothing is written. A ref race (`updateRef` 409, or 422 not-a-fast-forward) re-reads the head and
+ * replays the same files on it, up to `maxRetries` attempts, under the same guard.
+ *
+ * With `handoff`, the handed-off paths are checked first on every attempt against the agent's data
+ * commit (`HANDOFF_PAGE_CHANGED`), so a page conflict is never reported as a ref race.
+ */
 export declare function commitWikiChanges(params: CommitWikiChangesParams): Promise<CommitWikiChangesResult>;
 export declare function validateWikilinks(files: Record<string, string>): void;
 /**
@@ -163,6 +214,12 @@ export declare function parsePorcelainPaths(stdout: string): string[];
  * the four category directories.
  */
 export declare function countWikiPages(paths: string[]): number;
+/**
+ * The log text an agent appended: what its `knowledge/log.md` adds after `knowledge/log.md` at the
+ * commit it started from. `undefined` when the agent changed anything before that point, or the base
+ * log is empty, so there is nothing safe to take. Both inputs are normalized first (LF, one final newline).
+ */
+export declare function deriveAgentLogEntries(baseLog: string, handoffLog: string): string | undefined;
 export declare function runWikiIngestCli(dependencies?: RunWikiIngestCliDependencies): Promise<void>;
 type ReadUtf8File = (path: string, encoding: 'utf8') => Promise<string>;
 export declare function loadTrackedRepoNodeIds(readFileImpl?: ReadUtf8File): Promise<TrackedRepoNodeIdsResult>;

package/dist/wiki-ingest.js

@@ -1,6 +1,7 @@
+import { Buffer } from 'node:buffer';
 import { execFile } from 'node:child_process';
 import { appendFile, readdir, readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
+import { basename, join } from 'node:path';
 import process from 'node:process';
 import { promisify } from 'node:util';
 import { parse, stringify } from 'yaml';
@@ -19,6 +20,8 @@ const WIKI_ROOT = 'knowledge/wiki';
 const INDEX_PATH = 'knowledge/index.md';
 const LOG_PATH = 'knowledge/log.md';
 const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const COMMIT_SHA_PATTERN = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u;
+const HANDOFF_BASE_REMEDIATION = 'The writer could not tie the handoff to the data commit the agent job synced. Re-run the workflow so the agent job runs again.';
 const execFileAsync = promisify(execFile);
 export class WikiIngestError extends Error {
     code;
@@ -32,8 +35,14 @@ export class WikiIngestError extends Error {
         this.findings = params.findings ?? [];
     }
 }
+/** The two wiki files every writer shares. Writers rebuild both from their own sync; a handoff never supplies them. */
+export function isSharedWikiFile(path) {
+    return path === INDEX_PATH || path === LOG_PATH;
+}
 export function buildWikiIngestChanges(params) {
-    if (params.pages.length === 0) {
+    if (params.pages.length === 0 &&
+        (params.handoffDeletedPaths ?? []).length === 0 &&
+        (params.agentLogEntries ?? '').trim() === '') {
         throw new WikiIngestError({
             code: 'INVALID_PAYLOAD',
             message: 'wiki ingest requires at least one page update',
@@ -51,6 +60,10 @@ export function buildWikiIngestChanges(params) {
         nextFiles[page.path] = normalized;
         files[page.path] = normalized;
     }
+    for (const path of params.handoffDeletedPaths ?? []) {
+        if (nextFiles[path] === undefined && !deletedPaths.includes(path))
+            deletedPaths.push(path);
+    }
     rewriteInboundWikilinks(nextFiles, migrations);
     for (const [path, content] of Object.entries(nextFiles)) {
         if (params.existingFiles[path] !== content && !deletedPaths.includes(path)) {
@@ -93,7 +106,7 @@ export function buildWikiIngestChanges(params) {
     }
     const parsedPages = collectWikiPages(nextFiles);
     const index = buildIndexDocument(nextFiles[INDEX_PATH], parsedPages);
-    const log = appendLogEntry(nextFiles[LOG_PATH], params);
+    const log = appendLogEntry(appendAgentLogEntries(nextFiles[LOG_PATH], params.agentLogEntries), params);
     files[INDEX_PATH] = index;
     files[LOG_PATH] = log;
     return { files, deletedPaths, findings: correctionFindings };
@@ -121,6 +134,18 @@ function collectWikiFrontmatter(files) {
     }
     return frontmatter;
 }
+/**
+ * Commits `params.files` (and removes `params.deletedPaths`) as one commit on the data branch.
+ *
+ * Every attempt is guarded: if any path in the write set (files and deletions) differs on the head read
+ * in that attempt from the tree the files were derived from (`baseCommitSha`, or the first head read
+ * when it is omitted), another writer changed it, so the write fails with `CONFLICT_EXHAUSTED` and
+ * nothing is written. A ref race (`updateRef` 409, or 422 not-a-fast-forward) re-reads the head and
+ * replays the same files on it, up to `maxRetries` attempts, under the same guard.
+ *
+ * With `handoff`, the handed-off paths are checked first on every attempt against the agent's data
+ * commit (`HANDOFF_PAGE_CHANGED`), so a page conflict is never reported as a ref race.
+ */
 export async function commitWikiChanges(params) {
     const owner = params.owner ?? DEFAULT_OWNER;
     const repo = params.repo ?? DEFAULT_REPO;
@@ -135,6 +160,12 @@ export async function commitWikiChanges(params) {
     }
     const octokit = params.octokit ?? (await createOctokitFromEnv());
     rejectProtectedWikiBranchName(branch);
+    // Resolved outside the retry loop's try, ahead of any bootstrap or write: an unusable agent commit is
+    // terminal, and the loop's 404 handler must not mistake it for a missing data branch.
+    const handoffBaseTreeSha = params.handoff === undefined
+        ? undefined
+        : await resolveHandoffBaseTree(octokit, owner, repo, branch, params.handoff.agentCommitSha);
+    const handoffPaths = (params.handoff?.paths ?? []).filter(path => !isSharedWikiFile(path));
     const shouldBootstrapDataBranch = branch === DEFAULT_BRANCH;
     const bootstrap = params.bootstrapDataBranch ?? defaultBootstrapDataBranch;
     const bootstrapDataBranch = async () => {
@@ -143,19 +174,52 @@ export async function commitWikiChanges(params) {
     if (shouldBootstrapDataBranch) {
         await bootstrapDataBranch();
     }
+    // The tree the write set was derived from, once resolved (see `CommitWikiChangesParams.baseCommitSha`).
+    let baseTreeSha;
     for (let attempt = 1; attempt <= maxRetries; attempt += 1) {
+        // Only an `updateRef` 422 is a ref race ("not a fast forward": the branch moved after this attempt
+        // read its tip). A 422 from createBlob, createTree or createCommit is a bad request and stays terminal.
+        let updatingRef = false;
         try {
             await assertWritableWikiBranch(octokit, owner, repo, branch);
             const head = await octokit.rest.git.getRef({ owner, repo, ref: `heads/${branch}` });
             const commit = await octokit.rest.git.getCommit({ owner, repo, commit_sha: head.data.object.sha });
+            // Resolved on the first attempt and reused: the base must not move while the write retries.
+            baseTreeSha ??=
+                params.baseCommitSha === undefined
+                    ? commit.data.tree.sha
+                    : await readCommitTreeSha(octokit, owner, repo, params.baseCommitSha);
+            const location = `${owner}/${repo}@${branch}`;
+            // Handed-off pages first, against the commit the agent read, so a page conflict surfaces as such
+            // even when the head also moved under the shared files.
+            if (handoffBaseTreeSha !== undefined && handoffPaths.length > 0 && commit.data.tree.sha !== handoffBaseTreeSha) {
+                await assertWriteSetUnchanged(octokit, owner, repo, {
+                    baseTreeSha: handoffBaseTreeSha,
+                    headTreeSha: commit.data.tree.sha,
+                    paths: handoffPaths,
+                    location,
+                    code: 'HANDOFF_PAGE_CHANGED',
+                });
+            }
+            const guardBaseTreeSha = baseTreeSha;
+            if (commit.data.tree.sha !== guardBaseTreeSha) {
+                await assertWriteSetUnchanged(octokit, owner, repo, {
+                    baseTreeSha: guardBaseTreeSha,
+                    headTreeSha: commit.data.tree.sha,
+                    paths: [...Object.keys(params.files), ...(params.deletedPaths ?? [])],
+                    location,
+                    code: 'CONFLICT_EXHAUSTED',
+                });
+            }
             const tree = [];
+            // Read before the first write: a deletion of a path that cannot be confirmed must not be skipped.
+            const presentPaths = params.deletedPaths === undefined || params.deletedPaths.length === 0
+                ? new Set()
+                : await getPresentPathsInTree(octokit, owner, repo, commit.data.tree.sha);
             for (const [path, content] of Object.entries(params.files)) {
                 const blob = await octokit.rest.git.createBlob({ owner, repo, content, encoding: 'utf-8' });
                 tree.push({ path, mode: '100644', type: 'blob', sha: blob.data.sha });
             }
-            const presentPaths = params.deletedPaths === undefined || params.deletedPaths.length === 0
-                ? new Set()
-                : await getPresentPathsInTree(octokit, owner, repo, commit.data.tree.sha);
             for (const path of params.deletedPaths ?? []) {
                 if (params.files[path] !== undefined || !presentPaths.has(path)) {
                     continue;
@@ -175,6 +239,7 @@ export async function commitWikiChanges(params) {
                 tree: createdTree.data.sha,
                 parents: [commit.data.sha],
             });
+            updatingRef = true;
             await octokit.rest.git.updateRef({
                 owner,
                 repo,
@@ -189,11 +254,12 @@ export async function commitWikiChanges(params) {
                 await bootstrapDataBranch();
                 continue;
             }
-            if (isConflictError(error) && attempt < maxRetries) {
+            const refRace = isConflictError(error) || (updatingRef && isApiErrorStatus(error, 422));
+            if (refRace && attempt < maxRetries) {
                 await delayConflictRetry(attempt);
                 continue;
             }
-            if (isConflictError(error)) {
+            if (refRace) {
                 throw new WikiIngestError({
                     code: 'CONFLICT_EXHAUSTED',
                     message: `wiki ingest exhausted ${maxRetries} attempt(s) updating ${owner}/${repo}@${branch}`,
@@ -226,13 +292,124 @@ async function assertWritableWikiBranch(octokit, owner, repo, branch) {
     });
 }
 async function getPresentPathsInTree(octokit, owner, repo, treeSha) {
+    const entries = await readTreeEntries(octokit, owner, repo, treeSha);
+    if (entries === undefined)
+        throw truncatedTreeRefusal('a deletion cannot be checked against a truncated tree');
+    return new Set(entries.keys());
+}
+/** A truncated tree listing cannot be trusted either way, so the write fails closed. */
+function truncatedTreeRefusal(reason) {
+    return new WikiIngestError({
+        code: 'CONFLICT_EXHAUSTED',
+        message: `wiki ingest refused: ${reason}`,
+        remediation: 'The data branch tree listing was truncated. Retry the workflow; if it persists, the tree has outgrown the recursive listing.',
+    });
+}
+async function readCommitTreeSha(octokit, owner, repo, sha) {
+    const commit = await octokit.rest.git.getCommit({ owner, repo, commit_sha: sha });
+    return commit.data.tree.sha;
+}
+/**
+ * Resolves the agent job's data commit to its tree, after checking it is a full commit SHA and an
+ * ancestor of (or equal to) the branch head. Compare's `behind_by` is 0 and its merge base is the
+ * commit itself exactly when that holds.
+ */
+async function resolveHandoffBaseTree(octokit, owner, repo, branch, agentCommitSha) {
+    if (!COMMIT_SHA_PATTERN.test(agentCommitSha)) {
+        throw handoffBaseInvalid('the agent job data commit is missing or is not a commit SHA');
+    }
+    try {
+        const head = await octokit.rest.git.getRef({ owner, repo, ref: `heads/${branch}` });
+        const comparison = await octokit.rest.repos.compareCommitsWithBasehead({
+            owner,
+            repo,
+            basehead: `${agentCommitSha}...${head.data.object.sha}`,
+        });
+        if (comparison.data.behind_by !== 0 || comparison.data.merge_base_commit.sha !== agentCommitSha) {
+            throw handoffBaseInvalid(`the agent job data commit is not an ancestor of ${owner}/${repo}@${branch}`);
+        }
+        return await readCommitTreeSha(octokit, owner, repo, agentCommitSha);
+    }
+    catch (error) {
+        if (error instanceof WikiIngestError)
+            throw error;
+        if (isApiErrorStatus(error, 404) || isApiErrorStatus(error, 422)) {
+            throw handoffBaseInvalid(`the agent job data commit does not resolve on ${owner}/${repo}@${branch}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Refuses, before any content is validated, a handoff whose pages another writer has changed since the
+ * agent job synced. Validating a stale page against the current wiki can fail for an unrelated reason
+ * (a link to a page the other writer deleted), which would hide the conflict. The commit repeats this
+ * check on every attempt, which still catches a change that lands after this one.
+ */
+async function assertHandoffPagesCurrent(octokit, owner, repo, branch, handoff) {
+    const baseTreeSha = await resolveHandoffBaseTree(octokit, owner, repo, branch, handoff.agentCommitSha);
+    const paths = handoff.paths.filter(path => !isSharedWikiFile(path));
+    if (paths.length === 0)
+        return;
+    const head = await octokit.rest.git.getRef({ owner, repo, ref: `heads/${branch}` });
+    const headTreeSha = await readCommitTreeSha(octokit, owner, repo, head.data.object.sha);
+    if (headTreeSha === baseTreeSha)
+        return;
+    await assertWriteSetUnchanged(octokit, owner, repo, {
+        baseTreeSha,
+        headTreeSha,
+        paths,
+        location: `${owner}/${repo}@${branch}`,
+        code: 'HANDOFF_PAGE_CHANGED',
+    });
+}
+/**
+ * Fail closed unless every path has the same tree entry (sha, mode, type; absence counts) on the new
+ * head as in the tree the files were derived from. A replay onto a head where another writer touched
+ * one of them would silently overwrite that writer's change. `code` names the refusal; a truncated
+ * tree read always refuses with `CONFLICT_EXHAUSTED`, because it says nothing about the pages.
+ */
+async function assertWriteSetUnchanged(octokit, owner, repo, params) {
+    const refuse = (code, reason) => {
+        throw new WikiIngestError({
+            code,
+            message: code === 'HANDOFF_PAGE_CHANGED'
+                ? `wiki ingest refused to write to ${params.location}: ${reason}`
+                : `wiki ingest did not replay onto ${params.location}: ${reason}`,
+            remediation: code === 'HANDOFF_PAGE_CHANGED'
+                ? 'Another writer changed a page after the agent job synced. Re-run the agent job so it starts from the current data branch.'
+                : 'Another writer updated the data branch concurrently. Retry the workflow so it rebuilds on the new head.',
+        });
+    };
+    const base = await readTreeEntries(octokit, owner, repo, params.baseTreeSha);
+    const head = await readTreeEntries(octokit, owner, repo, params.headTreeSha);
+    if (base === undefined || head === undefined)
+        return refuse('CONFLICT_EXHAUSTED', 'a tree read was truncated, so the write set cannot be verified');
+    if (params.paths.some(path => !sameTreeEntry(base.get(path), head.get(path)))) {
+        return refuse(params.code, params.code === 'HANDOFF_PAGE_CHANGED'
+            ? 'a handed-off page changed after the agent job synced'
+            : 'another writer changed a path in the write set');
+    }
+}
+function sameTreeEntry(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return left.mode === right.mode && left.type === right.type && left.sha === right.sha;
+}
+/** Path to its entry, for every non-directory entry. `undefined` when the read is truncated. */
+async function readTreeEntries(octokit, owner, repo, treeSha) {
     const response = await octokit.rest.git.getTree({ owner, repo, tree_sha: treeSha, recursive: 'true' });
     if (response.data.truncated === true)
-        return new Set();
+        return undefined;
     const tree = response.data.tree;
+    const entries = new Map();
     if (!Array.isArray(tree))
-        return new Set();
-    return new Set(tree.flatMap(entry => (isRecord(entry) && typeof entry.path === 'string' ? [entry.path] : [])));
+        return entries;
+    for (const entry of tree) {
+        if (!isRecord(entry) || typeof entry.path !== 'string' || entry.type === 'tree')
+            continue;
+        entries.set(entry.path, { mode: String(entry.mode), type: String(entry.type), sha: String(entry.sha) });
+    }
+    return entries;
 }
 async function createOctokitFromEnv() {
     const token = process.env.GITHUB_TOKEN;
@@ -462,6 +639,13 @@ function parseIndexEntryLines(index) {
     }
     return entries;
 }
+/** Appends raw log entries (already in log format) to `existingLog`, keeping its text byte-for-byte. */
+function appendAgentLogEntries(existingLog, entries) {
+    if (entries === undefined || entries.trim() === '')
+        return existingLog;
+    const base = existingLog === undefined || existingLog === '' ? LOG_HEADER : normalizeText(existingLog);
+    return normalizeText(`${base}${entries.startsWith('\n') ? entries : `\n${entries}`}`);
+}
 /**
  * Append one entry to `knowledge/log.md`, keeping the existing text byte-for-byte. The log is
  * append-only; callers must never rewrite history. Exported for the operator rename path.
@@ -794,8 +978,15 @@ function formatTimestamp(value) {
     const minute = `${value.getUTCMinutes()}`.padStart(2, '0');
     return `${year}-${month}-${day} ${hour}:${minute}`;
 }
+/**
+ * Read the existing wiki files from the working tree, and report the data-branch commit they were
+ * synced from: `WIKI_INGEST_DATA_TIP_SHA`, when the workflow exports the tip it synced `knowledge/` from.
+ * Without it there is no recorded base and the commit guards from its own first read.
+ */
 async function loadExistingWikiFiles() {
     const files = {};
+    const recordedTip = process.env.WIKI_INGEST_DATA_TIP_SHA;
+    const baseCommitSha = recordedTip === undefined || recordedTip === '' ? undefined : recordedTip;
     for (const path of [INDEX_PATH, LOG_PATH]) {
         try {
             files[path] = await readFile(path, 'utf8');
@@ -836,7 +1027,7 @@ async function loadExistingWikiFiles() {
             }
         }
     }
-    return files;
+    return { files, baseCommitSha };
 }
 async function loadWorkingTreeWikiFiles(paths) {
     const files = {};
@@ -857,7 +1048,7 @@ async function getChangedWikiPaths() {
         `${WIKI_ROOT}/entities`,
         `${WIKI_ROOT}/comparisons`,
     ]);
-    return parsePorcelainPaths(stdout).filter(path => path !== INDEX_PATH && path !== LOG_PATH && path.endsWith('.md'));
+    return parsePorcelainPaths(stdout).filter(path => !isSharedWikiFile(path) && path.endsWith('.md'));
 }
 /**
  * Parse paths from `git status --porcelain=v1` output.
@@ -953,12 +1144,120 @@ async function emitPagesChanged(n) {
         await appendFile(outputPath, `pages_changed=${n}\n`);
     }
 }
+function envValue(name) {
+    const value = process.env[name];
+    return value === undefined || value === '' ? undefined : value;
+}
+function handoffBaseInvalid(message) {
+    return new WikiIngestError({
+        code: 'HANDOFF_BASE_INVALID',
+        message: `wiki ingest refused: ${message}`,
+        remediation: HANDOFF_BASE_REMEDIATION,
+    });
+}
+/**
+ * LF line endings and exactly one final newline; an empty log stays empty. Unlike `normalizeText`, which
+ * only adds a missing final newline, this also converts CRLF and drops trailing blank lines.
+ */
+function toLfWithSingleFinalNewline(value) {
+    const trimmed = value.replaceAll('\r\n', '\n').trimEnd();
+    return trimmed === '' ? '' : `${trimmed}\n`;
+}
+/**
+ * The log text an agent appended: what its `knowledge/log.md` adds after `knowledge/log.md` at the
+ * commit it started from. `undefined` when the agent changed anything before that point, or the base
+ * log is empty, so there is nothing safe to take. Both inputs are normalized first (LF, one final newline).
+ */
+export function deriveAgentLogEntries(baseLog, handoffLog) {
+    const base = toLfWithSingleFinalNewline(baseLog);
+    const handoff = toLfWithSingleFinalNewline(handoffLog);
+    if (base === '' || !handoff.startsWith(base))
+        return undefined;
+    return handoff.slice(base.length);
+}
+async function readHandoffManifest(handoffDir) {
+    const raw = await readFile(join(handoffDir, 'manifest.json'), 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new WikiIngestError({
+            code: 'INVALID_PAYLOAD',
+            message: 'wiki handoff manifest.json is not valid JSON',
+            remediation: 'Rebuild the handoff artifact with scripts/wiki-handoff-build.ts.',
+        });
+    }
+    const isStringArray = (value) => Array.isArray(value) && value.every(entry => typeof entry === 'string');
+    if (!isRecord(parsed) || !isStringArray(parsed.changed) || !isStringArray(parsed.deleted)) {
+        throw new WikiIngestError({
+            code: 'INVALID_PAYLOAD',
+            message: 'wiki handoff manifest.json must hold string arrays "changed" and "deleted"',
+            remediation: 'Rebuild the handoff artifact with scripts/wiki-handoff-build.ts.',
+        });
+    }
+    return { changed: parsed.changed, deleted: parsed.deleted };
+}
+/** The text of `path` in the tree of `commitSha`, or `undefined` when the commit has no such file. */
+async function readFileAtCommit(octokit, owner, repo, commitSha, path) {
+    const entries = await readTreeEntries(octokit, owner, repo, await readCommitTreeSha(octokit, owner, repo, commitSha));
+    if (entries === undefined)
+        throw truncatedTreeRefusal(`${path} cannot be read from a truncated tree`);
+    const entry = entries.get(path);
+    if (entry === undefined || entry.type !== 'blob')
+        return undefined;
+    const blob = await octokit.rest.git.getBlob({ owner, repo, file_sha: entry.sha });
+    return Buffer.from(blob.data.content, 'base64').toString('utf8');
+}
+/**
+ * Reads the handoff the trusted job applied. `undefined` outside a handoff run (neither
+ * `WIKI_HANDOFF_DIR` nor `WIKI_HANDOFF_BASE_SHA` set). Inside one, the agent job's data commit must be a
+ * full commit SHA, the handed-off pages must be unchanged on the branch since that commit (checked here,
+ * ahead of any validation of their content), and the log entries the agent appended are derived against that commit's `log.md`.
+ */
+async function loadHandoff(dependencies, target) {
+    const handoffDir = envValue('WIKI_HANDOFF_DIR');
+    const agentCommitSha = envValue('WIKI_HANDOFF_BASE_SHA');
+    if (handoffDir === undefined && agentCommitSha === undefined)
+        return undefined;
+    if (handoffDir === undefined || agentCommitSha === undefined || !COMMIT_SHA_PATTERN.test(agentCommitSha)) {
+        throw handoffBaseInvalid('the agent job data commit is missing or is not a commit SHA');
+    }
+    const octokit = dependencies.octokit ?? (await createOctokitFromEnv());
+    const manifest = await readHandoffManifest(handoffDir);
+    const pagePaths = [...manifest.changed, ...manifest.deleted];
+    const deletedPagePaths = manifest.deleted.filter(path => !isSharedWikiFile(path));
+    await assertHandoffPagesCurrent(octokit, target.owner ?? DEFAULT_OWNER, target.repo ?? DEFAULT_REPO, target.branch ?? DEFAULT_BRANCH, { agentCommitSha, paths: pagePaths });
+    if (!manifest.changed.includes(LOG_PATH)) {
+        return { octokit, agentCommitSha, agentLogEntries: undefined, pagePaths, deletedPagePaths, warnings: [] };
+    }
+    const handoffLog = await readFile(join(handoffDir, 'files', LOG_PATH), 'utf8');
+    let baseLog;
+    try {
+        baseLog = await readFileAtCommit(octokit, target.owner ?? DEFAULT_OWNER, target.repo ?? DEFAULT_REPO, agentCommitSha, LOG_PATH);
+    }
+    catch (error) {
+        // Only a commit or file that does not exist is a bad base; any other failure is not about the base.
+        if (isApiErrorStatus(error, 404))
+            throw handoffBaseInvalid(`the agent job data commit does not resolve`);
+        throw error;
+    }
+    if (baseLog === undefined)
+        throw handoffBaseInvalid(`${LOG_PATH} does not exist at the agent job data commit`);
+    const agentLogEntries = deriveAgentLogEntries(baseLog, handoffLog);
+    const warnings = agentLogEntries === undefined ? [{ code: 'agent-log-entries-dropped', reason: 'not-append-only' }] : [];
+    return { octokit, agentCommitSha, agentLogEntries, pagePaths, deletedPagePaths, warnings };
+}
+function writeWarnings(warnings) {
+    for (const warning of warnings)
+        process.stderr.write(`wiki-ingest:warning:${JSON.stringify(warning)}\n`);
+}
 export async function runWikiIngestCli(dependencies = {}) {
     const payloadPath = process.argv[2] ?? process.env.WIKI_INGEST_INPUT;
     const readCorrectionsImpl = dependencies.readCorrections ?? readCorrections;
     const commitWikiChangesImpl = dependencies.commitWikiChanges ?? commitWikiChanges;
     const getChangedWikiPathsImpl = dependencies.getChangedWikiPaths ?? getChangedWikiPaths;
-    const existingFiles = await loadExistingWikiFiles();
+    const { files: existingFiles, baseCommitSha } = await loadExistingWikiFiles();
     let correctionRead;
     try {
         correctionRead = await readCorrectionsImpl();
@@ -984,9 +1283,12 @@ export async function runWikiIngestCli(dependencies = {}) {
     let message;
     let identityWarnings = [];
     let committedPagePaths;
+    let handoff;
     try {
         if (payloadPath !== undefined && payloadPath !== '') {
             const payload = parsePayload(await readFile(payloadPath, 'utf8'));
+            handoff = await loadHandoff(dependencies, payload);
+            writeWarnings(handoff?.warnings ?? []);
             const tracked = await loadTrackedRepoNodeIds();
             identityWarnings = tracked.warnings;
             built = buildWikiIngestChanges({
@@ -1001,6 +1303,8 @@ export async function runWikiIngestCli(dependencies = {}) {
                 fallbackNodeId: payload.node_id,
                 trackedMetadataAvailable: tracked.metadataAvailable,
                 corrections: correctionRead.corrections,
+                agentLogEntries: handoff?.agentLogEntries,
+                handoffDeletedPaths: handoff?.deletedPagePaths,
             });
             owner = payload.owner;
             repo = payload.repo;
@@ -1010,7 +1314,17 @@ export async function runWikiIngestCli(dependencies = {}) {
         }
         else {
             const changedPaths = await getChangedWikiPathsImpl();
-            if (changedPaths.length === 0) {
+            handoff = await loadHandoff(dependencies, {
+                owner: process.env.WIKI_OWNER,
+                repo: process.env.WIKI_REPO,
+                branch: process.env.WIKI_BRANCH,
+            });
+            writeWarnings(handoff?.warnings ?? []);
+            // `git status` drops deletions, so an agent's deleted pages come from the manifest. A handoff
+            // whose only change is appended log entries still commits the log and the rebuilt index.
+            if (changedPaths.length === 0 &&
+                (handoff?.deletedPagePaths ?? []).length === 0 &&
+                (handoff?.agentLogEntries ?? '').trim() === '') {
                 await emitPagesChanged(0);
                 process.stdout.write(`${JSON.stringify({ committed: false, attempts: 1, pagesChanged: 0 })}\n`);
                 return;
@@ -1032,6 +1346,8 @@ export async function runWikiIngestCli(dependencies = {}) {
                 targetNodeId: process.env.REPO_NODE_ID,
                 trackedMetadataAvailable: tracked.metadataAvailable,
                 corrections: correctionRead.corrections,
+                agentLogEntries: handoff?.agentLogEntries,
+                handoffDeletedPaths: handoff?.deletedPagePaths,
             });
             owner = process.env.WIKI_OWNER;
             repo = process.env.WIKI_REPO;
@@ -1050,9 +1366,7 @@ export async function runWikiIngestCli(dependencies = {}) {
         }
         throw error;
     }
-    for (const warning of identityWarnings) {
-        process.stderr.write(`wiki-ingest:warning:${JSON.stringify(warning)}\n`);
-    }
+    writeWarnings(identityWarnings);
     for (const finding of built.findings) {
         process.stderr.write(`wiki-ingest:finding:${JSON.stringify(finding)}\n`);
     }
@@ -1063,6 +1377,10 @@ export async function runWikiIngestCli(dependencies = {}) {
         message,
         files: built.files,
         deletedPaths: built.deletedPaths,
+        ...(baseCommitSha === undefined ? {} : { baseCommitSha }),
+        ...(handoff === undefined
+            ? {}
+            : { octokit: handoff.octokit, handoff: { agentCommitSha: handoff.agentCommitSha, paths: handoff.pagePaths } }),
     });
     const pagesChanged = countWikiPages(committedPagePaths);
     await emitPagesChanged(pagesChanged);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/wiki-write-core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Shared validation and commit primitives for Fro Bot wiki writes",
   "homepage": "https://github.com/fro-bot/.github/tree/main/packages/wiki-write-core#readme",
   "bugs": {