@withtruing/companion 0.0.0-stage → 0.13.0

package/dist/shipment.js

@@ -0,0 +1,115 @@
+/**
+ * The analyse_shipment task kind's own local-git work — reading a commit the server only knows
+ * by sha/title/message (see server/drift.ts's own comment on why the diff never crosses the
+ * wire to this package: the server doesn't fetch it at all for a local connection, same
+ * structural discipline every other dispatch-guarded function keeps). Shared by both backends
+ * (api-key-caller.ts, claude-cli-caller.ts) since neither can skip this step — even the CLI
+ * backend has no Bash/git tool available to it (`--restricted --tools "Read,Grep,Glob"`, see
+ * claude-cli-caller.ts), so "read this commit's diff" has to happen here, in this package's own
+ * trusted code, not inside the model's own tool-use loop the way file exploration does for
+ * every other task kind.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { managedFetchEnvironment, reportBackgroundFetch } from './managed-repo.js';
+const execFileAsync = promisify(execFile);
+/** Copied verbatim from server/drift.ts's own looksTrivial (path-pattern only) — see that
+ *  file's comment for why this one travels with the companion while looksIrrelevant (vocabulary-
+ *  based, scored against the graph's own structured spec data) does not: the dispatch only
+ *  sends rendered prose text (spec.stableText), not a structured Graph object, so there's
+ *  nothing for a local vocabulary-overlap check to run against. This one needs only the diff's
+ *  own changed-paths, which the companion reads directly — a real, if partial, way to keep goal
+ *  4 (reduce AI calls) alive on this path: a lockfile-only or CI-only commit still costs zero AI
+ *  spend even though the fuller server-side filter doesn't run out here. */
+const TRIVIAL_PATH_PATTERNS = [
+    /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|Gemfile\.lock|poetry\.lock|Cargo\.lock)$/,
+    /^\.github\/workflows\//,
+    /^\.(eslintrc|prettierrc|editorconfig)/i,
+    /^(dist|build|coverage|node_modules)\//,
+];
+function looksTrivial(changedPaths) {
+    if (!changedPaths.length)
+        return true;
+    return changedPaths.every((p) => TRIVIAL_PATH_PATTERNS.some((re) => re.test(p)));
+}
+/** Confirms the commit exists in the local checkout, attempting one `git fetch` first if it
+ *  doesn't — using whatever git credentials/remotes are already configured locally (the
+ *  customer's own, e.g. an SSH key or credential helper). A watched managed copy instead asks
+ *  the Console for short-lived GitHub access. A webhook can fire before a customer's local
+ *  checkout has pulled the commit it's about; this is the one real recovery attempt before
+ *  giving up (see the plan's own edge-case table: "posts reason:'sha_not_local' rather than
+ *  silently analysing the wrong tree state"). */
+async function ensureCommitLocal(repoPath, sha) {
+    const hasCommit = async () => {
+        try {
+            await execFileAsync('git', ['cat-file', '-e', `${sha}^{commit}`], { cwd: repoPath, windowsHide: true });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (await hasCommit())
+        return true;
+    try {
+        await execFileAsync('git', ['fetch'], { cwd: repoPath, timeout: 60_000, env: await managedFetchEnvironment(repoPath), windowsHide: true });
+        reportBackgroundFetch(repoPath, { ok: true });
+    }
+    catch (error) {
+        const stderr = error.stderr;
+        reportBackgroundFetch(repoPath, { ok: false, stderr: typeof stderr === 'string' ? stderr : String(error) });
+        // Best-effort — network trouble, no remote configured, etc. hasCommit() below is the real
+        // verdict either way; a failed fetch just means it stays whatever it already was.
+    }
+    return hasCommit();
+}
+/** `git show <sha>` rather than `git diff <sha>~1 <sha>` — the latter fails outright on a root
+ *  commit (no parent to diff against), which is a real case a webhook-triggered check could
+ *  plausibly hit for a freshly-initialized repo; `git show` handles it correctly (diffs against
+ *  an empty tree). Accepts the minor redundancy of `git show`'s own commit-metadata header
+ *  duplicating what the server already sent in spec.volatileText (title/message) rather than
+ *  trade away that robustness for a marginally cleaner prompt.
+ *  `git show --name-only --pretty=format:` suppresses the header for the paths-only call, so
+ *  changedPaths is exactly the file list, nothing else. No MAX_FILE_BYTES-style read cap here —
+ *  unlike a whole file, a single commit's diff is essentially never pathologically large; the
+ *  caller (api-key-caller.ts / claude-cli-caller.ts) still degrades gracefully past
+ *  MAX_LOCAL_DIFF_CHARS the same way the server's own diff-size handling already does. */
+async function readCommitDiff(repoPath, sha) {
+    const [{ stdout: diffText }, { stdout: pathsOut }] = await Promise.all([
+        execFileAsync('git', ['show', sha], { cwd: repoPath, maxBuffer: 64 * 1024 * 1024, windowsHide: true }),
+        execFileAsync('git', ['show', '--name-only', '--pretty=format:', sha], { cwd: repoPath, maxBuffer: 8 * 1024 * 1024, windowsHide: true }),
+    ]);
+    const changedPaths = pathsOut
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return { diffText, changedPaths };
+}
+/** The one shared entry point both backends call before ever spending an AI call — ensure the
+ *  commit is actually here, read its real diff, and apply the same cheap deterministic filter
+ *  the server runs for a server-execution connection (see poller.ts's own comment on why it
+ *  can't run server-side for a local one). */
+export async function prepareShipmentAnalysis(repoPath, sha) {
+    if (!(await ensureCommitLocal(repoPath, sha)))
+        return { outcome: 'sha_not_local' };
+    const { diffText, changedPaths } = await readCommitDiff(repoPath, sha);
+    if (looksTrivial(changedPaths))
+        return { outcome: 'trivial' };
+    return { outcome: 'proceed', diffText, changedPaths };
+}
+/** Diffs above this are too expensive/noisy to embed verbatim — mirrors server/drift.ts's own
+ *  MAX_DIFF_CHARS, just a much higher ceiling: local reads aren't rate-limited or GitHub-API-
+ *  metered the way the server's own diff fetch is (goal 1), so this is a sanity backstop against
+ *  a pathological single commit (a vendored/generated file committed whole), not a real-world
+ *  common-case constraint the way the server's 40,000-char cap is. */
+const MAX_LOCAL_DIFF_CHARS = 300_000;
+/** Embeds a locally-read diff into spec.volatileText, degrading the same way
+ *  server/drift.ts's own sizeNote does for an oversized diff — changed-files-only, not silently
+ *  truncated mid-patch. Shared by both backends so the size-aware wording only needs writing
+ *  once. */
+export function appendDiffToVolatile(spec, diffText, changedPaths) {
+    const diffSection = diffText.length <= MAX_LOCAL_DIFF_CHARS
+        ? `# The diff\n\n${diffText}`
+        : `# The diff\n\n(${diffText.length} characters — too large to include in full; going on the changed files list only)\n\nChanged files:\n${changedPaths.join('\n')}`;
+    return { ...spec, volatileText: `${spec.volatileText}\n\n${diffSection}` };
+}

package/dist/strict-schema.js

@@ -0,0 +1,187 @@
+const RESTRICTED_KEYWORDS = [
+    'allOf',
+    'oneOf',
+    'not',
+    'if',
+    'then',
+    'else',
+];
+function isSchema(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function cloneSchema(schema) {
+    return structuredClone(schema);
+}
+function propertyPath(path, property) {
+    return `${path}.properties[${JSON.stringify(property)}]`;
+}
+function isNullable(schema) {
+    const type = schema.type;
+    if (type === 'null' || (Array.isArray(type) && type.includes('null')))
+        return true;
+    if (Array.isArray(schema.enum) && schema.enum.includes(null))
+        return true;
+    if (Array.isArray(schema.anyOf)) {
+        return schema.anyOf.some((alternative) => isSchema(alternative) && isNullable(alternative));
+    }
+    return false;
+}
+function makeNullable(schema) {
+    const type = schema.type;
+    const objectOrArray = type === 'object' || type === 'array' || 'properties' in schema || 'items' in schema;
+    if (objectOrArray) {
+        return { anyOf: [schema, { type: 'null' }] };
+    }
+    if (typeof type === 'string') {
+        schema.type = [type, 'null'];
+    }
+    else if (Array.isArray(type)) {
+        schema.type = [...type, 'null'];
+    }
+    else if (!Array.isArray(schema.enum)) {
+        return { anyOf: [schema, { type: 'null' }] };
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.includes(null)) {
+        schema.enum = [...schema.enum, null];
+    }
+    return schema;
+}
+function transformSchema(schema, schemaPath, valuePath, context) {
+    for (const keyword of RESTRICTED_KEYWORDS) {
+        if (!(keyword in schema))
+            continue;
+        if (!context.enforcedAfter.has(keyword)) {
+            throw new Error(`Codex rejects JSON Schema keyword ${keyword} at ${schemaPath}; ` +
+                `it may only be removed when the caller lists ${keyword} in enforcedAfter and re-checks it after the reply.`);
+        }
+        delete schema[keyword];
+        context.record.removedKeywords.push({ path: schemaPath, keyword });
+    }
+    if (Array.isArray(schema.anyOf)) {
+        schema.anyOf = schema.anyOf.map((alternative, index) => isSchema(alternative)
+            ? transformSchema(alternative, `${schemaPath}.anyOf[${index}]`, valuePath, context)
+            : alternative);
+    }
+    const objectSchema = schema.type === 'object' || isSchema(schema.properties);
+    if (objectSchema) {
+        if (!('additionalProperties' in schema)) {
+            schema.additionalProperties = false;
+            context.record.additionalPropertiesFalseAdded.push(schemaPath);
+        }
+        else if (schema.additionalProperties !== false) {
+            schema.additionalProperties = false;
+            context.record.additionalPropertiesChangedToFalse.push(schemaPath);
+        }
+        const properties = isSchema(schema.properties) ? schema.properties : {};
+        const originallyRequired = new Set(Array.isArray(schema.required)
+            ? schema.required.filter((entry) => typeof entry === 'string')
+            : []);
+        const propertyNames = Object.keys(properties);
+        schema.required = propertyNames;
+        const transformedProperties = {};
+        for (const property of propertyNames) {
+            const propertySchema = properties[property];
+            if (!isSchema(propertySchema)) {
+                transformedProperties[property] = propertySchema;
+                continue;
+            }
+            const childSchemaPath = propertyPath(schemaPath, property);
+            const childValuePath = [...valuePath, property];
+            let transformed = transformSchema(propertySchema, childSchemaPath, childValuePath, context);
+            if (!originallyRequired.has(property)) {
+                context.record.requiredPropertiesAdded.push(childSchemaPath);
+                if (!isNullable(transformed)) {
+                    transformed = makeNullable(transformed);
+                    context.record.introducedNullableProperties.push({
+                        schemaPath: childSchemaPath,
+                        valuePath: childValuePath,
+                    });
+                }
+            }
+            transformedProperties[property] = transformed;
+        }
+        schema.properties = transformedProperties;
+    }
+    if (isSchema(schema.items)) {
+        schema.items = transformSchema(schema.items, `${schemaPath}.items`, [...valuePath, { arrayItem: true }], context);
+    }
+    else if (Array.isArray(schema.items)) {
+        schema.items = schema.items.map((item, index) => isSchema(item)
+            ? transformSchema(item, `${schemaPath}.items[${index}]`, [...valuePath, { arrayItem: true }], context)
+            : item);
+    }
+    for (const keyword of ['$defs', 'definitions', 'dependentSchemas']) {
+        const schemas = schema[keyword];
+        if (!isSchema(schemas))
+            continue;
+        const transformed = {};
+        for (const [name, child] of Object.entries(schemas)) {
+            transformed[name] = isSchema(child)
+                ? transformSchema(child, `${schemaPath}.${keyword}[${JSON.stringify(name)}]`, valuePath, context)
+                : child;
+        }
+        schema[keyword] = transformed;
+    }
+    for (const keyword of ['contains', 'propertyNames']) {
+        if (isSchema(schema[keyword])) {
+            schema[keyword] = transformSchema(schema[keyword], `${schemaPath}.${keyword}`, [...valuePath, ...(keyword === 'contains' ? [{ arrayItem: true }] : [])], context);
+        }
+    }
+    if (Array.isArray(schema.prefixItems)) {
+        schema.prefixItems = schema.prefixItems.map((item, index) => isSchema(item)
+            ? transformSchema(item, `${schemaPath}.prefixItems[${index}]`, [...valuePath, { arrayItem: true }], context)
+            : item);
+    }
+    return schema;
+}
+/** Convert a conventional object-result schema to Codex/OpenAI strict structured-output form.
+ * Restricted conditional/composition keywords are never weakened silently: callers must name
+ * each rule that their own post-response validation will enforce. */
+export function toCodexStrictSchema(input, options = {}) {
+    if (!isSchema(input) || input.type !== 'object' || 'anyOf' in input) {
+        throw new Error('Codex structured output requires a single object schema at the root; root anyOf and non-object roots are not supported.');
+    }
+    const record = {
+        requiredPropertiesAdded: [],
+        introducedNullableProperties: [],
+        additionalPropertiesFalseAdded: [],
+        additionalPropertiesChangedToFalse: [],
+        removedKeywords: [],
+    };
+    return {
+        schema: transformSchema(cloneSchema(input), '$', [], {
+            enforcedAfter: new Set(options.enforcedAfter ?? []),
+            record,
+        }),
+        record,
+    };
+}
+function stripAtPath(value, path, index = 0) {
+    if (value === null || typeof value !== 'object' || index >= path.length)
+        return;
+    const segment = path[index];
+    if (typeof segment !== 'string') {
+        if (!Array.isArray(value))
+            return;
+        for (const item of value)
+            stripAtPath(item, path, index + 1);
+        return;
+    }
+    if (Array.isArray(value))
+        return;
+    const object = value;
+    if (index === path.length - 1) {
+        if (object[segment] === null)
+            delete object[segment];
+        return;
+    }
+    stripAtPath(object[segment], path, index + 1);
+}
+/** Restore the absent-property shape used by the Claude path. Only nullability introduced by
+ * this transform is stripped; null accepted by the original schema remains intact. */
+export function stripIntroducedNulls(value, record) {
+    for (const introduced of record.introducedNullableProperties) {
+        stripAtPath(value, introduced.valuePath);
+    }
+    return value;
+}

package/dist/surface-mapper.js

@@ -0,0 +1,357 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { promisify } from 'node:util';
+import { hasLinkedPathComponent } from './investigation-reader.js';
+import { DEFAULT_MAPPER_SETTINGS, enumerateTrackedFiles, expandImports, isSupportedMapperVersion, MappingFailure, trackedNamedPathStatus, } from './import-resolver.js';
+import { repositoryMissingReason, spawnFailureCode } from './local-scan.js';
+import { createSandbox } from './sandbox.js';
+export const SURFACE_SEED_PROMPT_VERSION = 'map_module_seeds@1';
+export const SURFACE_SEED_MODEL = 'claude-sonnet-5-5';
+const execFileAsync = promisify(execFile);
+const MODEL_ROLES = [
+    'implementation',
+    'schema_or_migration',
+    'ui',
+    'registration',
+    'contract',
+    'config',
+];
+const MODEL_ROLE_SET = new Set(MODEL_ROLES);
+const compareDiagnostic = (a, b) => a.code.localeCompare(b.code) || a.path.localeCompare(b.path) || a.detail.localeCompare(b.detail);
+function failureDetail(errorOrReason) {
+    if (typeof errorOrReason === 'string')
+        return errorOrReason;
+    if (errorOrReason && typeof errorOrReason === 'object') {
+        const candidate = errorOrReason;
+        if (typeof candidate.reason === 'string')
+            return candidate.reason;
+        if (typeof candidate.message === 'string')
+            return candidate.message;
+    }
+    return String(errorOrReason);
+}
+function hasUnavailableSpawnCode(error, seen = new Set()) {
+    if (!error || typeof error !== 'object' || seen.has(error))
+        return false;
+    seen.add(error);
+    const candidate = error;
+    if (candidate.code === 'ENOENT' || candidate.code === 'EACCES')
+        return true;
+    if (hasUnavailableSpawnCode(candidate.cause, seen))
+        return true;
+    return Array.isArray(candidate.errors)
+        && candidate.errors.some((nested) => hasUnavailableSpawnCode(nested, seen));
+}
+function repositoryPathIsMissing(repoPath) {
+    try {
+        return !statSync(repoPath).isDirectory();
+    }
+    catch (error) {
+        const code = spawnFailureCode(error);
+        return code === 'ENOENT' || code === 'ENOTDIR';
+    }
+}
+/** Central authority for deciding whether failure to obtain an immutable repository sandbox can
+ *  consume the retry budget or is a genuinely missing commit. */
+export function classifySandboxFailure(errorOrReason, repoPath) {
+    if (repoPath && repositoryPathIsMissing(repoPath)) {
+        return { kind: 'transient', code: 'repository_unavailable', detail: repositoryMissingReason(repoPath) };
+    }
+    const detail = failureDetail(errorOrReason);
+    const spawnUnavailable = hasUnavailableSpawnCode(errorOrReason) || /spawn git(?:\.exe)?\b/i.test(detail);
+    const repositoryInvalid = /not a git repository|doesn't look like a git repository|cannot change to|no such file or directory/i.test(detail);
+    const unavailable = errorOrReason && typeof errorOrReason === 'object'
+        ? errorOrReason
+        : undefined;
+    const fetchAttempted = unavailable?.fetchOk === true || unavailable?.fetchOk === false
+        || /after fetch (?:succeeded|failed)/i.test(detail);
+    const unresolvedCommit = /commit [0-9a-f]+ could not be resolved/i.test(detail);
+    if (!spawnUnavailable && !repositoryInvalid && fetchAttempted && unresolvedCommit) {
+        return { kind: 'stable', code: 'commit_unavailable', detail };
+    }
+    return { kind: 'transient', code: 'repository_unavailable', detail };
+}
+const seedSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['seeds', 'roles'],
+    properties: {
+        seeds: {
+            type: 'array', minItems: 1, maxItems: 12,
+            items: {
+                type: 'object', additionalProperties: false, required: ['path', 'role', 'reason'],
+                properties: {
+                    path: { type: 'string' },
+                    role: { enum: [...MODEL_ROLES] },
+                    reason: { type: 'string' },
+                },
+            },
+        },
+        roles: {
+            type: 'array', minItems: MODEL_ROLES.length, maxItems: MODEL_ROLES.length,
+            items: {
+                type: 'object', additionalProperties: false, required: ['role', 'status', 'note'],
+                properties: {
+                    role: { enum: [...MODEL_ROLES] },
+                    status: { enum: ['seeded', 'none_identified'] },
+                    note: { type: 'string' },
+                },
+            },
+        },
+    },
+};
+function safeRepoPath(path) {
+    return path.length > 0
+        && !path.startsWith('/')
+        && !path.includes('\\')
+        && !/^[A-Za-z]:/.test(path)
+        && !path.split('/').some((segment) => !segment || segment === '.' || segment === '..');
+}
+function parseNameStatus(output) {
+    if (output === '')
+        return [];
+    if (!output.endsWith('\0'))
+        return null;
+    const fields = output.slice(0, -1).split('\0');
+    const changes = [];
+    for (let index = 0; index < fields.length;) {
+        const rawStatus = fields[index++];
+        const scored = /^([RC])([0-9]{1,3})$/.exec(rawStatus);
+        const status = scored?.[1] ?? rawStatus;
+        if (!['A', 'D', 'M', 'R', 'C', 'T'].includes(status)
+            || (scored && Number(scored[2]) > 100))
+            return null;
+        if (status === 'R' || status === 'C') {
+            const fromPath = fields[index++];
+            const path = fields[index++];
+            if (!fromPath || !path || !safeRepoPath(fromPath) || !safeRepoPath(path))
+                return null;
+            changes.push({ status, fromPath, path });
+        }
+        else {
+            const path = fields[index++];
+            if (!path || !safeRepoPath(path))
+                return null;
+            changes.push({ status: status, path });
+        }
+    }
+    return changes.sort((left, right) => left.path.localeCompare(right.path)
+        || left.status.localeCompare(right.status));
+}
+/** Reads the exact tree change offered by the server. A failed or malformed diff simply declines
+ * reuse; a fresh model seed stage remains available. */
+export async function readReuseChangeSet(sandboxPath, candidateCommit, headCommit) {
+    try {
+        const { stdout } = await execFileAsync('git', ['--literal-pathspecs', 'diff', '--no-color', '--name-status', '-z', '-M', candidateCommit, headCommit, '--'], { cwd: sandboxPath, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+        return parseNameStatus(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function validateModelReply(raw) {
+    if (!isRecord(raw) || !Array.isArray(raw.seeds) || !Array.isArray(raw.roles)
+        || raw.seeds.length < 1 || raw.seeds.length > 12 || raw.roles.length !== MODEL_ROLES.length) {
+        throw new MappingFailure('transient', 'seed_model_invalid', 'Seed model returned the wrong shape');
+    }
+    const seeds = raw.seeds.map((value) => {
+        if (!isRecord(value) || typeof value.path !== 'string' || !MODEL_ROLE_SET.has(String(value.role))
+            || typeof value.reason !== 'string' || !value.reason.trim()) {
+            throw new MappingFailure('transient', 'seed_model_invalid', 'Seed model returned a malformed seed');
+        }
+        return { path: value.path, role: value.role, reason: value.reason };
+    });
+    const roles = raw.roles.map((value) => {
+        if (!isRecord(value) || !MODEL_ROLE_SET.has(String(value.role))
+            || (value.status !== 'seeded' && value.status !== 'none_identified')
+            || typeof value.note !== 'string') {
+            throw new MappingFailure('transient', 'seed_model_invalid', 'Seed model returned malformed role accounting');
+        }
+        return {
+            role: value.role,
+            status: value.status,
+            note: value.note,
+        };
+    });
+    if (new Set(roles.map((entry) => entry.role)).size !== MODEL_ROLES.length
+        || MODEL_ROLES.some((role) => !roles.some((entry) => entry.role === role))) {
+        throw new MappingFailure('transient', 'seed_model_invalid', 'Seed model must account for every role exactly once');
+    }
+    return { seeds, roles };
+}
+function seedPrompt(claim, trackedPaths) {
+    return `# Module\n\n${JSON.stringify({
+        title: claim.seedInput.module.title,
+        specText: claim.seedInput.module.specText,
+    }, null, 2)}\n\n# Statements\n\n${JSON.stringify(claim.seedInput.statements.map((statement) => statement.text), null, 2)}\n\n# Tracked repository paths\n\n${trackedPaths.join('\n')}\n\n# Task\n\nChoose 1–12 tracked files most likely to implement this module. Account for every required role. A none_identified role records uncertainty; it is not evidence that the role is absent.`;
+}
+export async function mapSurfaceSnapshot(input) {
+    const { claim, sandboxPath, tree } = input;
+    if (!isSupportedMapperVersion(claim.mapperVersion)) {
+        throw new MappingFailure('stable', 'mapper_version_unsupported', `Unsupported mapper version ${String(claim.mapperVersion)}`);
+    }
+    const diagnostics = [];
+    const namedPaths = [];
+    const namedSeeds = [];
+    for (const path of [...claim.seedInput.namedPaths].sort((left, right) => left.localeCompare(right))) {
+        let status = trackedNamedPathStatus(tree, path);
+        if (status !== 'unverifiable' && await hasLinkedPathComponent(sandboxPath, path))
+            status = 'unverifiable';
+        namedPaths.push({ path, present: status === 'present' });
+        if (status === 'present')
+            namedSeeds.push({ path, role: 'named', source: 'named' });
+        else if (status === 'missing')
+            diagnostics.push({
+                code: 'named_path_missing', path, detail: 'absent from complete tracked-file enumeration',
+            });
+        else
+            diagnostics.push({
+                code: 'named_path_unverifiable', path, detail: 'not a safe tracked regular file',
+            });
+    }
+    const regularPaths = [...tree.entries.values()]
+        .filter((entry) => (entry.mode === '100644' || entry.mode === '100755') && entry.type === 'blob')
+        .map((entry) => entry.path)
+        .sort((left, right) => left.localeCompare(right));
+    const regularSet = new Set(regularPaths);
+    let promptVersion;
+    let backend;
+    let model;
+    let modelSeeds;
+    let roles;
+    if (input.reuse) {
+        ({ promptVersion, backend, model, modelSeeds, roles } = input.reuse.candidate.modelJudgement);
+        modelSeeds = modelSeeds.map((seed) => ({ ...seed }));
+        roles = roles.map((role) => ({ ...role }));
+    }
+    else {
+        let raw;
+        try {
+            raw = await input.callModel({
+                model: SURFACE_SEED_MODEL,
+                effort: 'medium',
+                maxTokens: 4_096,
+                system: 'Select plausible module seed files only from the supplied tracked path list. Return strict JSON matching the schema.',
+                prompt: seedPrompt(claim, regularPaths),
+                schema: seedSchema,
+            });
+        }
+        catch (error) {
+            if (error instanceof MappingFailure)
+                throw error;
+            throw new MappingFailure('transient', 'seed_model_failed', error instanceof Error ? error.message : String(error));
+        }
+        const reply = validateModelReply(raw);
+        promptVersion = SURFACE_SEED_PROMPT_VERSION;
+        backend = input.execution.backend;
+        model = input.execution.model;
+        modelSeeds = reply.seeds.map((seed) => ({ ...seed, valid: false }));
+        roles = reply.roles.sort((left, right) => left.role.localeCompare(right.role));
+    }
+    const validModelSeeds = [];
+    for (const seed of modelSeeds) {
+        const validAtCommit = regularSet.has(seed.path) && !(await hasLinkedPathComponent(sandboxPath, seed.path));
+        if (!input.reuse)
+            seed.valid = validAtCommit;
+        const valid = seed.valid && validAtCommit;
+        if (valid)
+            validModelSeeds.push({ path: seed.path, role: seed.role, source: 'model' });
+        else
+            diagnostics.push({ code: 'model_seed_invalid', path: seed.path, detail: seed.reason });
+    }
+    const seedByPath = new Map();
+    for (const seed of namedSeeds)
+        seedByPath.set(seed.path, seed);
+    for (const seed of validModelSeeds)
+        if (!seedByPath.has(seed.path))
+            seedByPath.set(seed.path, seed);
+    const seeds = [...seedByPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+    if (seeds.length === 0)
+        throw new MappingFailure('stable', 'no_seeds', 'No present named path or valid model seed');
+    const expanded = await expandImports({
+        sandboxPath,
+        commit: claim.commit,
+        tree,
+        seeds,
+        settings: claim.mapperSettings,
+        mapperVersion: claim.mapperVersion,
+    });
+    const expansion = diagnostics.some((diagnostic) => diagnostic.code === 'named_path_unverifiable')
+        ? { ...expanded, status: 'incomplete' }
+        : expanded;
+    return {
+        format: 'auto-surface-manifest@1',
+        generationId: claim.generationId,
+        workspaceId: claim.workspaceId,
+        moduleId: claim.moduleId,
+        connectionId: claim.connectionId,
+        commit: claim.commit,
+        inputDigest: claim.inputDigest,
+        seedStage: {
+            promptVersion,
+            backend,
+            model,
+            namedPaths,
+            modelSeeds: input.reuse
+                ? modelSeeds
+                : modelSeeds.sort((a, b) => a.path.localeCompare(b.path) || a.role.localeCompare(b.role)),
+            roles,
+            seeds,
+            diagnostics: diagnostics.sort(compareDiagnostic),
+            ...(input.reuse
+                ? { reusedFrom: input.reuse.candidate.generationId, changeSet: input.reuse.changeSet }
+                : {}),
+        },
+        expansion,
+    };
+}
+export async function runSurfaceMapping(input) {
+    let sandbox;
+    try {
+        sandbox = await createSandbox(input.repoPath, input.claim.commit);
+    }
+    catch (error) {
+        const failure = classifySandboxFailure(error, input.repoPath);
+        throw new MappingFailure(failure.kind, failure.code, failure.detail);
+    }
+    if (sandbox.obtainedBy === 'unavailable') {
+        const failure = classifySandboxFailure(sandbox, input.repoPath);
+        throw new MappingFailure(failure.kind, failure.code, failure.detail);
+    }
+    try {
+        const tree = await enumerateTrackedFiles(sandbox.path, input.claim.commit);
+        const candidate = input.claim.reuseCandidate;
+        const changeSet = candidate
+            ? await readReuseChangeSet(sandbox.path, candidate.commit, input.claim.commit)
+            : null;
+        const expansionFiles = new Set(candidate?.expansionFiles ?? []);
+        const reuse = candidate && changeSet
+            && changeSet.every((change) => change.status === 'M' && expansionFiles.has(change.path))
+            ? { candidate, changeSet }
+            : undefined;
+        return await mapSurfaceSnapshot({ ...input, sandboxPath: sandbox.path, tree, ...(reuse ? { reuse } : {}) });
+    }
+    finally {
+        await sandbox.cleanup();
+    }
+}
+export function canonicalManifestJson(manifest) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return value.map(canonical);
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.keys(value).sort()
+                .map((key) => [key, canonical(value[key])]));
+        }
+        return value;
+    };
+    return JSON.stringify(canonical(manifest));
+}
+export function manifestHash(manifest) {
+    return `sha256:${createHash('sha256').update(canonicalManifestJson(manifest)).digest('hex')}`;
+}
+export { DEFAULT_MAPPER_SETTINGS, MappingFailure };