@withtruing/companion 0.13.2 → 0.14.0

package/dist/whole-read/sanitize.js

@@ -0,0 +1,266 @@
+import { validateNoSecretValues } from './redaction.js';
+const SAFE_KEY = /^[A-Za-z][A-Za-z0-9_-]{0,127}$/;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/;
+const ABSOLUTE_HOST_PATH = /(?:^|[\s"'(])(?:[A-Za-z]:[\\/]|\\\\|\/(?:home|Users|tmp|var\/tmp|private\/tmp)\/)/;
+const FORBIDDEN_FIELDS = new Set([
+    'prompt',
+    'rawprompt',
+    'stdout',
+    'stderr',
+    'rawoutput',
+    'rawmodeloutput',
+    'sourceexcerpt',
+]);
+const BUILD_FAILURE_CODES = new Set([
+    'usage_limit',
+    'provider_rate_limit',
+    'provider_auth',
+    'provider_unavailable',
+    'provider_request_rejected',
+    'billing_exhausted',
+    'capability_failure',
+    'model_declined',
+    'output_truncated',
+    'companion_offline',
+    'github_rate_limit',
+    'consent_invalidated',
+    'allowance_reached',
+    'snapshot_unavailable',
+    'source_acquisition_required',
+    'cleanup_pending',
+    'read_result_invalid',
+    'draft_attempt_invalid',
+    'draft_input_invalid',
+    'draft_note_invalid',
+    'check_attempt_invalid',
+    'check_input_invalid',
+    'check_claim_invalid',
+    'check_note_use_invalid',
+    'check_result_invalid',
+    'claim_check_input_invalid',
+    'claim_check_citation_invalid',
+    'claim_check_result_invalid',
+    'grouping_attempt_invalid',
+    'grouping_input_invalid',
+    'relationship_attempt_invalid',
+    'relationship_input_invalid',
+    'relationship_result_invalid',
+    'canonical_source_invalid',
+    'internal_error',
+]);
+const BUILD_FAILURE_SOURCES = new Set([
+    'claude_cli',
+    'codex',
+    'anthropic_api',
+    'github',
+    'server',
+    'companion',
+]);
+const DIAGNOSTIC_OPERATIONS = new Set([
+    'collection_page',
+    'github_archive',
+    'github_blob',
+    'github_tree',
+    'git_blob',
+    'git_tree',
+    'model_request',
+    'registry_lookup',
+]);
+const CLEANUP_ERROR_CODES = new Set([
+    'cleanup_delete_failed',
+    'cleanup_reader_cancel_failed',
+    'cleanup_path_outside_root',
+    'cleanup_unsafe_link',
+    'cleanup_marker_invalid',
+]);
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+const exactFields = (value, required, optional = []) => {
+    const fields = new Set([...required, ...optional]);
+    return required.every((field) => Object.hasOwn(value, field))
+        && Object.keys(value).every((field) => fields.has(field));
+};
+const isSafeId = (value) => typeof value === 'string' && SAFE_ID.test(value);
+const isCount = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+const isIsoTime = (value) => {
+    if (typeof value !== 'string')
+        return false;
+    const time = Date.parse(value);
+    return Number.isFinite(time) && new Date(time).toISOString() === value;
+};
+const containsHostPath = (value) => ABSOLUTE_HOST_PATH.test(value);
+function containsCodeQuote(value) {
+    const characters = Array.from(value);
+    if (characters.length <= 120)
+        return false;
+    const tokens = [];
+    for (let index = 0; index < characters.length; index += 1) {
+        const character = characters[index];
+        if (character === '=' && characters[index + 1] === '>') {
+            tokens.push({ start: index, end: index + 2 });
+            index += 1;
+        }
+        else if (character === '{' || character === '}' || character === ';'
+            || character === '(' || character === ')') {
+            tokens.push({ start: index, end: index + 1 });
+        }
+    }
+    for (let index = 0; index + 2 < tokens.length; index += 1) {
+        if (tokens[index + 2].end - tokens[index].start <= 40)
+            return true;
+    }
+    return false;
+}
+function inspectString(value) {
+    if (validateNoSecretValues(value).ok === false)
+        return 'secret_value_detected';
+    return containsCodeQuote(value) ? 'code_quote_detected' : null;
+}
+function cloneMetadata(value, allowCleanupPath, field, ancestors = new Set(), depth = 0) {
+    if (depth > 64)
+        return { ok: false, code: 'metadata_schema_invalid' };
+    if (value === null || typeof value === 'boolean')
+        return { ok: true, value };
+    if (typeof value === 'number') {
+        return Number.isFinite(value)
+            ? { ok: true, value }
+            : { ok: false, code: 'metadata_schema_invalid' };
+    }
+    if (typeof value === 'string') {
+        const pathField = field?.toLowerCase().endsWith('path') === true;
+        if (!allowCleanupPath && containsHostPath(value)) {
+            return { ok: false, code: 'cleanup_path_forbidden' };
+        }
+        if (pathField && allowCleanupPath) {
+            return validateNoSecretValues(value).ok
+                ? { ok: true, value }
+                : { ok: false, code: 'secret_value_detected' };
+        }
+        const unsafe = inspectString(value);
+        return unsafe ? { ok: false, code: unsafe } : { ok: true, value };
+    }
+    if (!value || typeof value !== 'object' || ancestors.has(value)) {
+        return { ok: false, code: 'metadata_schema_invalid' };
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        const result = [];
+        for (const item of value) {
+            const safe = cloneMetadata(item, allowCleanupPath, undefined, ancestors, depth + 1);
+            if (!safe.ok)
+                return safe;
+            result.push(safe.value);
+        }
+        ancestors.delete(value);
+        return { ok: true, value: result };
+    }
+    if (!isRecord(value))
+        return { ok: false, code: 'metadata_schema_invalid' };
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        const normalizedKey = key.toLowerCase().replace(/[_-]/g, '');
+        if (!SAFE_KEY.test(key) || FORBIDDEN_FIELDS.has(normalizedKey)) {
+            return { ok: false, code: 'metadata_schema_invalid' };
+        }
+        const safeKey = inspectString(key);
+        if (safeKey)
+            return { ok: false, code: safeKey };
+        const safe = cloneMetadata(item, allowCleanupPath, key, ancestors, depth + 1);
+        if (!safe.ok)
+            return safe;
+        result[key] = safe.value;
+    }
+    ancestors.delete(value);
+    return { ok: true, value: result };
+}
+function validBuildFailure(value) {
+    if (!isRecord(value) || !exactFields(value, ['code', 'source'], ['resetAt', 'retryAfterMs', 'category']))
+        return false;
+    if (typeof value.code !== 'string' || !BUILD_FAILURE_CODES.has(value.code)
+        || typeof value.source !== 'string' || !BUILD_FAILURE_SOURCES.has(value.source))
+        return false;
+    if (value.resetAt !== undefined && !isIsoTime(value.resetAt))
+        return false;
+    if (value.category !== undefined && value.category !== null
+        && (typeof value.category !== 'string' || !SAFE_ID.test(value.category)))
+        return false;
+    return value.retryAfterMs === undefined
+        || (typeof value.retryAfterMs === 'number' && Number.isFinite(value.retryAfterMs)
+            && value.retryAfterMs >= 0);
+}
+function validDiagnostic(value) {
+    if (!isRecord(value)
+        || !exactFields(value, ['operation'], ['objectId', 'count', 'retryAt', 'retryAfterMs']))
+        return false;
+    if (typeof value.operation !== 'string' || !DIAGNOSTIC_OPERATIONS.has(value.operation))
+        return false;
+    if (value.objectId !== undefined && !isSafeId(value.objectId))
+        return false;
+    if (value.count !== undefined && !isCount(value.count))
+        return false;
+    if (value.retryAt !== undefined && !isIsoTime(value.retryAt))
+        return false;
+    return value.retryAfterMs === undefined
+        || (typeof value.retryAfterMs === 'number' && Number.isFinite(value.retryAfterMs)
+            && value.retryAfterMs >= 0);
+}
+function validResultReference(value) {
+    if (!isRecord(value))
+        return false;
+    if (Object.keys(value).length === 0)
+        return true;
+    if (value.type !== 'sealed_build_collection') {
+        return ['collection', 'ref', 'publishedLane'].some((field) => exactFields(value, [field]) && isSafeId(value[field]));
+    }
+    return exactFields(value, ['type', 'protocolVersion', 'collectionId', 'kind', 'digest'])
+        && value.protocolVersion === 'whole-read-pages@1'
+        && isSafeId(value.collectionId)
+        && ['inventory', 'notes', 'groups', 'claims', 'progress'].includes(String(value.kind))
+        && typeof value.digest === 'string'
+        && /^sha256:[0-9a-f]{64}$/.test(value.digest);
+}
+function validCleanupRecord(value) {
+    if (!isRecord(value) || !exactFields(value, [
+        'workspaceId',
+        'buildId',
+        'attemptId',
+        'hostId',
+        'leaseExpiresAt',
+        'locationId',
+        'path',
+        'state',
+        'cleanupAttempts',
+        'errorCode',
+        'deletedAt',
+    ]))
+        return false;
+    return isSafeId(value.workspaceId)
+        && isSafeId(value.buildId)
+        && isSafeId(value.attemptId)
+        && isSafeId(value.hostId)
+        && isIsoTime(value.leaseExpiresAt)
+        && isSafeId(value.locationId)
+        && typeof value.path === 'string'
+        && value.path.length > 0
+        && value.path.length <= 4096
+        && !value.path.includes('\0')
+        && (value.state === 'deleted' || value.state === 'cleanup_pending')
+        && isCount(value.cleanupAttempts)
+        && (value.errorCode === null
+            || (typeof value.errorCode === 'string' && CLEANUP_ERROR_CODES.has(value.errorCode)))
+        && (value.deletedAt === null || isIsoTime(value.deletedAt));
+}
+/**
+ * Copies JSON metadata only after recursively checking every string. Unsafe records are rejected;
+ * source-like or secret-bearing values are never shortened into apparently valid metadata.
+ */
+export function sanitizeBuildMetadata(value, schema = 'metadata') {
+    const schemaValid = schema === 'metadata'
+        || (schema === 'build_failure' && validBuildFailure(value))
+        || (schema === 'diagnostic' && validDiagnostic(value))
+        || (schema === 'result_reference' && validResultReference(value))
+        || (schema === 'owner_scoped_cleanup' && validCleanupRecord(value));
+    if (!schemaValid)
+        return { ok: false, code: 'metadata_schema_invalid' };
+    return cloneMetadata(value, schema === 'owner_scoped_cleanup');
+}

package/dist/whole-read/secret-rules.js

@@ -0,0 +1,26 @@
+/** Closed, deliberately conservative secret-rules@1 matcher table. */
+export const SECRET_RULES_VERSION = 'secret-rules@1';
+export const SECRET_RULES = [
+    { id: 'private-key', priority: 100, matcher: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/g,
+        terminator: /-----END [A-Z0-9 ]*PRIVATE KEY-----/g, capture: 'private-key' },
+    // Anchor at the maximal scheme run so a failed URL cannot rescan a long run from every letter.
+    // The url capture starts at its first letter, preserving the previous match boundary exactly.
+    { id: 'url-credentials', priority: 95, matcher: /(?<![a-z0-9+.-])(?=[a-z0-9+.-]*[a-z])[a-z0-9+.-]+:\/\/[^\s/:@]+:[^\s/@]+@[^\s/]+[^\s]*/gi, capture: 'url' },
+    // The scanner checks each maximal JWT segment once; \b can also occur after every hyphen in a run.
+    { id: 'jwt', priority: 90, matcher: /[a-zA-Z0-9_-]+/g, capture: 'jwt' },
+    { id: 'aws-access-key', priority: 80, matcher: /\b(?:AKIA|ASIA|AIDA|AROA)[A-Z0-9]{16}\b/g, capture: 'whole' },
+    { id: 'aws-secret-key', priority: 80, matcher: /\baws_secret_access_key\s*[=:]\s*([A-Za-z0-9/+=]{40})\b/gi, capture: 'aws-secret' },
+    { id: 'gcp-api-key', priority: 80, matcher: /\bAIza[0-9A-Za-z_-]{35}\b/g, capture: 'whole' },
+    { id: 'azure-storage-connection-string', priority: 80, matcher: /\bDefaultEndpointsProtocol=https?;AccountName=[A-Za-z0-9-]+;AccountKey=[A-Za-z0-9+/=]+(?:;EndpointSuffix=[A-Za-z0-9.-]+)?\b/g, capture: 'whole' },
+    // The scanner parses each maximal query run once; the former expression could rescan it at every ?sv=.
+    { id: 'azure-sas-token', priority: 80, matcher: /[^\s#]+/g, capture: 'azure-sas' },
+    { id: 'github-token', priority: 80, matcher: /\b(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})\b/g, capture: 'whole' },
+    { id: 'gitlab-token', priority: 80, matcher: /\bglpat-[A-Za-z0-9_-]{20,255}\b/g, capture: 'whole' },
+    { id: 'slack-token', priority: 80, matcher: /\bxox[baprs]-[A-Za-z0-9-]{10,255}\b/g, capture: 'whole' },
+    { id: 'stripe-key', priority: 80, matcher: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,255}\b/g, capture: 'whole' },
+    { id: 'openai-token', priority: 80, matcher: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,255}\b/g, capture: 'whole' },
+    { id: 'anthropic-token', priority: 80, matcher: /\bsk-ant-[A-Za-z0-9_-]{20,255}\b/g, capture: 'whole' },
+    // Match each maximal assignment name once; the scanner applies the exact keyword/boundary and value rules.
+    { id: 'named-high-entropy-assignment', priority: 10, matcher: /(?<![A-Za-z0-9_.-])[A-Za-z0-9_.-]+\s*[=:]/g,
+        keywords: ['KEY', 'SECRET', 'TOKEN', 'PASSWORD'], capture: 'assignment' },
+];

package/dist/whole-read/structure.js

@@ -0,0 +1,300 @@
+import { structureDigest } from './identity.js';
+const COLORS = ['#2563eb', '#7c3aed', '#db2777', '#ea580c', '#ca8a04', '#16a34a', '#0891b2', '#4f46e5'];
+const METADATA_NAMES = new Set([
+    'package.json', 'package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock',
+    'bun.lock', 'bun.lockb', 'cargo.toml', 'cargo.lock', 'go.mod', 'go.sum', 'go.work',
+    'pyproject.toml', 'setup.py', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'gemfile',
+    'gemfile.lock', 'composer.json', 'composer.lock', 'pubspec.yaml', 'package.swift', 'mix.exs',
+    'readme', 'readme.md', 'readme.txt', 'license', 'license.md', 'notice', '.gitignore',
+    '.gitattributes', '.npmignore',
+]);
+const SOURCE_EXTENSIONS = new Set([
+    '.c', '.cc', '.cpp', '.cs', '.css', '.dart', '.ex', '.exs', '.go', '.h', '.hpp', '.html',
+    '.java', '.js', '.jsx', '.kt', '.kts', '.m', '.mm', '.php', '.py', '.rb', '.rs', '.scala',
+    '.scss', '.sh', '.sql', '.swift', '.ts', '.tsx', '.vue', '.xml', '.yaml', '.yml',
+]);
+const invalid = () => { throw new TypeError('structure_invalid'); };
+const pathParts = (path) => path.split('/').filter(Boolean);
+const directory = (path) => {
+    const parts = pathParts(path);
+    parts.pop();
+    return parts.join('/');
+};
+const baseName = (path) => pathParts(path).at(-1) ?? '';
+const isUnder = (path, root) => root === '' || path === root || path.startsWith(`${root}/`);
+const depth = (root) => root === '' ? 0 : pathParts(root).length;
+const entryKey = (entry) => `${entry.sourceId}\u0000${entry.pathBase64}`;
+const candidateKey = (sourceId, root) => `${sourceId}\u0000${root}`;
+const laneId = (sourceId, root) => `lane-${structureDigest({ root, sourceId }).slice('sha256:'.length, 'sha256:'.length + 24)}`;
+const proofFor = (entry) => ({
+    entryId: entry.id, sourceId: entry.sourceId, blobId: entry.blobId,
+    pathBase64: entry.pathBase64, pathDisplay: entry.pathDisplay,
+});
+function text(bytes) {
+    if (!bytes)
+        return undefined;
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function packageInfo(bytes) {
+    const source = text(bytes);
+    if (source === undefined)
+        return { workspace: false, uncertain: true };
+    try {
+        const parsed = JSON.parse(source);
+        return {
+            name: typeof parsed.name === 'string' && parsed.name.trim() ? parsed.name : undefined,
+            workspace: parsed.workspaces !== undefined,
+            uncertain: false,
+        };
+    }
+    catch {
+        return { workspace: false, uncertain: true };
+    }
+}
+function cargoInfo(bytes) {
+    const source = text(bytes);
+    if (source === undefined)
+        return { package: false, workspace: false, uncertain: true };
+    return {
+        package: /(?:^|\n)\s*\[package\]\s*(?:#.*)?(?:\n|$)/.test(source),
+        workspace: /(?:^|\n)\s*\[workspace\]\s*(?:#.*)?(?:\n|$)/.test(source),
+        uncertain: false,
+    };
+}
+function manifestKind(name) {
+    return name === 'go.mod' || name === 'pyproject.toml' || name === 'setup.py' || name === 'pom.xml'
+        || name === 'build.gradle' || name === 'build.gradle.kts' || name === 'gemfile'
+        || name === 'composer.json' || name === 'pubspec.yaml' || name === 'package.swift'
+        || name === 'mix.exs' || name.endsWith('.csproj');
+}
+function isKnownNonSource(entry) {
+    const name = baseName(entry.pathDisplay).toLowerCase();
+    return METADATA_NAMES.has(name) || name.endsWith('.csproj');
+}
+function sourceStatus(entry) {
+    if (entry.mode !== '100644' && entry.mode !== '100755')
+        return 'non-source';
+    if (isKnownNonSource(entry))
+        return 'non-source';
+    const name = baseName(entry.pathDisplay).toLowerCase();
+    const dot = name.lastIndexOf('.');
+    if (dot >= 0 && SOURCE_EXTENSIONS.has(name.slice(dot)))
+        return 'source';
+    return 'uncertain';
+}
+function defaultName(root) {
+    return root === '' ? 'Repository root' : root;
+}
+function canonicalRevision(inventoryRevision, lanes, assignments, merges) {
+    const value = {
+        inventoryRevision,
+        lanes: lanes.map(({ id, name, color, order }) => ({ id, name, color, order })),
+        assignments: [...assignments].sort((left, right) => left.entryId.localeCompare(right.entryId)),
+        merges: merges.map((merge) => ({ fromLaneIds: [...merge.fromLaneIds].sort(), intoLaneId: merge.intoLaneId })),
+    };
+    return { buildId: '', ...value, structureDigest: structureDigest(value) };
+}
+/**
+ * Mechanically derives lanes from an already-sealed inventory. Manifest contents are parsed as
+ * bytes only; no manifest is loaded, imported, or executed.
+ */
+export function deriveStructure(input) {
+    if (!Number.isSafeInteger(input.inventoryRevision) || input.inventoryRevision < 1)
+        invalid();
+    const entries = [...input.entries];
+    const seenEntries = new Set();
+    const seenIds = new Set();
+    for (const entry of entries) {
+        if (!entry.id || !entry.sourceId || !entry.pathBase64 || !entry.pathDisplay || !entry.blobId
+            || seenEntries.has(entryKey(entry)) || seenIds.has(entry.id))
+            invalid();
+        seenEntries.add(entryKey(entry));
+        seenIds.add(entry.id);
+    }
+    const candidates = new Map();
+    const add = (entry, name, workspaceAggregator = false, uncertain = false) => {
+        const root = directory(entry.pathDisplay);
+        const key = candidateKey(entry.sourceId, root);
+        const existing = candidates.get(key);
+        if (existing) {
+            existing.proofs.push(proofFor(entry));
+            existing.workspaceAggregator ||= workspaceAggregator;
+            existing.uncertain ||= uncertain;
+            return;
+        }
+        candidates.set(key, { sourceId: entry.sourceId, root, name, proofs: [proofFor(entry)], workspaceAggregator, uncertain });
+    };
+    for (const entry of entries) {
+        if (entry.mode !== '100644' && entry.mode !== '100755')
+            continue;
+        const name = baseName(entry.pathDisplay);
+        const lower = name.toLowerCase();
+        if (lower === 'package.json') {
+            const info = packageInfo(input.readCanonicalBytes(entry));
+            if (info.name)
+                add(entry, info.name, info.workspace);
+            else if (info.uncertain)
+                add(entry, defaultName(directory(entry.pathDisplay)), true, true);
+        }
+        else if (lower === 'cargo.toml') {
+            const info = cargoInfo(input.readCanonicalBytes(entry));
+            if (info.package || info.uncertain)
+                add(entry, defaultName(directory(entry.pathDisplay)), info.workspace && !info.package, info.uncertain);
+        }
+        else if (manifestKind(lower)) {
+            add(entry, defaultName(directory(entry.pathDisplay)));
+        }
+    }
+    const candidateList = [...candidates.values()];
+    const kept = candidateList.filter((candidate) => {
+        if (!candidate.workspaceAggregator || candidate.uncertain)
+            return true;
+        for (const entry of entries) {
+            if (entry.sourceId !== candidate.sourceId || !isUnder(entry.pathDisplay, candidate.root))
+                continue;
+            const deeper = candidateList.some((other) => other !== candidate && other.sourceId === candidate.sourceId
+                && depth(other.root) > depth(candidate.root) && isUnder(entry.pathDisplay, other.root));
+            if (!deeper && sourceStatus(entry) !== 'non-source')
+                return true;
+        }
+        return false;
+    }).sort((left, right) => left.sourceId.localeCompare(right.sourceId) || left.root.localeCompare(right.root));
+    const lanes = kept.map((candidate, index) => ({
+        id: laneId(candidate.sourceId, candidate.root), name: candidate.name,
+        color: COLORS[index % COLORS.length], order: index,
+        manifestProofs: [...candidate.proofs].sort((left, right) => left.pathBase64.localeCompare(right.pathBase64)),
+    }));
+    const laneByCandidate = new Map(kept.map((candidate, index) => [candidateKey(candidate.sourceId, candidate.root), lanes[index]]));
+    const assignments = [];
+    const rootEntries = [];
+    for (const entry of entries) {
+        const owner = kept.filter((candidate) => candidate.sourceId === entry.sourceId && isUnder(entry.pathDisplay, candidate.root))
+            .sort((left, right) => depth(right.root) - depth(left.root))[0];
+        const lane = owner ? laneByCandidate.get(candidateKey(owner.sourceId, owner.root)) : undefined;
+        if (lane)
+            assignments.push({ entryId: entry.id, laneId: lane.id });
+        else
+            rootEntries.push(entry);
+    }
+    if (rootEntries.length > 0) {
+        const rootLane = {
+            id: 'repository-root', name: 'Repository root', color: COLORS[lanes.length % COLORS.length],
+            order: lanes.length, manifestProofs: [],
+        };
+        lanes.push(rootLane);
+        assignments.push(...rootEntries.map((entry) => ({ entryId: entry.id, laneId: rootLane.id })));
+    }
+    const revision = canonicalRevision(input.inventoryRevision, lanes, assignments, []);
+    return { ...revision, lanes };
+}
+/** Includes declared generator inputs without implicitly selecting or publishing their lanes. */
+export function deriveSelectedLaneReadPlan(input) {
+    const laneIds = new Set(input.structure.lanes.map((lane) => lane.id));
+    const publishedLaneIds = [...input.selectedLaneIds];
+    if (publishedLaneIds.length === 0 || new Set(publishedLaneIds).size !== publishedLaneIds.length
+        || publishedLaneIds.some((laneId) => !laneIds.has(laneId)))
+        invalid();
+    const laneByEntry = new Map();
+    for (const assignment of input.structure.assignments) {
+        if (!assignment.entryId || laneByEntry.has(assignment.entryId) || !laneIds.has(assignment.laneId))
+            invalid();
+        laneByEntry.set(assignment.entryId, assignment.laneId);
+    }
+    const dependencyKeys = new Set();
+    for (const dependency of input.generatedSourceDependencies) {
+        const key = `${dependency.generatedEntryId}\0${dependency.sourceEntryId}`;
+        if (!laneByEntry.has(dependency.generatedEntryId) || !laneByEntry.has(dependency.sourceEntryId)
+            || dependency.generatedEntryId === dependency.sourceEntryId || dependencyKeys.has(key))
+            invalid();
+        dependencyKeys.add(key);
+    }
+    const selected = new Set(publishedLaneIds);
+    const included = new Set();
+    const requiredBy = new Map();
+    for (const [entryId, laneId] of laneByEntry) {
+        if (!selected.has(laneId))
+            continue;
+        included.add(entryId);
+        requiredBy.set(entryId, laneId);
+    }
+    const recorded = [];
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const dependency of input.generatedSourceDependencies) {
+            if (!included.has(dependency.generatedEntryId))
+                continue;
+            const sourceLaneId = laneByEntry.get(dependency.sourceEntryId);
+            const requiredByLaneId = requiredBy.get(dependency.generatedEntryId);
+            if (!recorded.some((value) => value.generatedEntryId === dependency.generatedEntryId
+                && value.sourceEntryId === dependency.sourceEntryId)) {
+                recorded.push({ ...dependency, sourceLaneId, requiredByLaneId });
+            }
+            if (!included.has(dependency.sourceEntryId)) {
+                included.add(dependency.sourceEntryId);
+                requiredBy.set(dependency.sourceEntryId, requiredByLaneId);
+                changed = true;
+            }
+        }
+    }
+    return {
+        publishedLaneIds,
+        entryIds: [...included].sort(),
+        generatedSourceDependencies: recorded.sort((left, right) => left.generatedEntryId.localeCompare(right.generatedEntryId) || left.sourceEntryId.localeCompare(right.sourceEntryId)),
+    };
+}
+export function reviseStructureRevision(current, edits) {
+    const lanes = current.lanes.map((lane) => ({ ...lane }));
+    const assignments = current.assignments.map((assignment) => ({ ...assignment }));
+    const merges = current.merges.map((merge) => ({ fromLaneIds: [...merge.fromLaneIds], intoLaneId: merge.intoLaneId }));
+    const requireLane = (id) => {
+        const lane = lanes.find((candidate) => candidate.id === id);
+        if (!lane)
+            throw new TypeError('structure_edit_invalid');
+        return lane;
+    };
+    for (const edit of edits) {
+        if (edit.kind === 'rename') {
+            if (!edit.name.trim())
+                throw new TypeError('structure_edit_invalid');
+            requireLane(edit.laneId).name = edit.name;
+        }
+        else if (edit.kind === 'recolor') {
+            if (!/^#[0-9a-f]{6}$/i.test(edit.color))
+                throw new TypeError('structure_edit_invalid');
+            requireLane(edit.laneId).color = edit.color;
+        }
+        else if (edit.kind === 'reorder') {
+            if (edit.laneIds.length !== lanes.length || new Set(edit.laneIds).size !== edit.laneIds.length
+                || edit.laneIds.some((id) => !lanes.some((lane) => lane.id === id)))
+                throw new TypeError('structure_edit_invalid');
+            edit.laneIds.forEach((id, index) => { requireLane(id).order = index; });
+        }
+        else if (edit.kind === 'merge') {
+            if (edit.fromLaneIds.length === 0 || new Set(edit.fromLaneIds).size !== edit.fromLaneIds.length
+                || edit.fromLaneIds.includes(edit.intoLaneId))
+                throw new TypeError('structure_edit_invalid');
+            const into = requireLane(edit.intoLaneId);
+            edit.fromLaneIds.forEach(requireLane);
+            for (const assignment of assignments) {
+                if (edit.fromLaneIds.includes(assignment.laneId))
+                    assignment.laneId = into.id;
+            }
+            for (const laneId of edit.fromLaneIds)
+                lanes.splice(lanes.findIndex((lane) => lane.id === laneId), 1);
+            merges.push({ fromLaneIds: [...edit.fromLaneIds], intoLaneId: into.id });
+        }
+        else {
+            throw new TypeError('structure_edit_invalid');
+        }
+    }
+    lanes.sort((left, right) => left.order - right.order || left.id.localeCompare(right.id));
+    lanes.forEach((lane, index) => { lane.order = index; });
+    const result = canonicalRevision(current.inventoryRevision, lanes, assignments, merges);
+    return { ...result, buildId: current.buildId };
+}

package/dist/whole-read/types.js

@@ -0,0 +1,2 @@
+export const WHOLE_READ_PAGE_PROTOCOL = 'whole-read-pages@1';
+export const INVENTORY_RULES_VERSION = 'inventory-rules@1';

package/dist/whole-read-claims.js

@@ -0,0 +1,12 @@
+/** Capabilities the companion advertises only when their whole-read runners exist. Kept apart from the
+ *  runner so the HTTP client (also imported by server tests) does not pull in process-spawning code. */
+export const WHOLE_READ_COMPANION_CAPABILITIES = [
+    'whole-read-inventory@1',
+    'whole-read-plan@1',
+    'whole-read-units@1',
+    'whole-read-grouping@1',
+    'whole-read-drafting@1',
+    'whole-read-checks@1',
+    'whole-read-prd@1',
+    'whole-read-relationships@1',
+];