dsh-plugin-coding-delegate 0.0.0-stage → 0.2.2

package/dist/emission.d.ts

@@ -0,0 +1,70 @@
+export interface FileEmissionResult {
+    path: string;
+    relativeName: string;
+    lines: number;
+    bytes: number;
+    /** How the change arrived: a whole file, or a delta against the file already there. */
+    mode?: 'write' | 'patch';
+    /** Search/replace blocks applied, when the emission was a patch. */
+    hunks?: number;
+}
+/** A delta block: the bytes to find, and what to put there instead. */
+export interface SearchReplaceBlock {
+    search: string;
+    replace: string;
+}
+/** Called once by the composition root, which holds both halves of the delta machinery. */
+export declare function configurePatchEngine(engine: {
+    parse: (body: string) => SearchReplaceBlock[] | null;
+    apply: (content: string, blocks: SearchReplaceBlock[]) => {
+        ok: boolean;
+        content?: string;
+        reason?: string;
+    };
+}): void;
+/**
+ * The containment decision for one delegated write. `baseDir` is the session workspace
+ * and `allowedRoots` is the operator's explicit extension list. Both sides are
+ * canonicalised, so a symlink inside the workspace cannot be used to escape it.
+ */
+export declare function evaluateEmissionPath(resolvedPath: string, baseDir: string, allowedRoots?: string[]): {
+    allowed: boolean;
+    reason?: string;
+};
+/**
+ * The scope decision for one delegated write: is this path one the unit declared?
+ *
+ * `targetFiles` used to be entirely passive — it became prompt text and it chose a fallback path when a
+ * fenced block named no file of its own — so a unit told to change one file could rewrite another, and
+ * nothing refused it, reported it, or noticed. That is the precondition for two units disagreeing, and it
+ * lands strictly before any project-level check could see it.
+ *
+ * A declared directory covers its subtree, because `isPathWithin` counts a path as within itself or
+ * beneath it. That makes `src`, `src/` and an exact file name all usable declarations, with one rule.
+ *
+ * An empty or absent declaration constrains nothing. A unit that declared no targets has not exceeded
+ * them, and refusing everything for an empty list would break every caller that never set the field.
+ */
+export declare function evaluateUnitScope(resolvedPath: string, declaredTargets: string[] | string | undefined, baseDir: string): {
+    allowed: boolean;
+    reason?: string;
+};
+/**
+ * Parse the model's final content into file emissions and write them to disk.
+ *
+ * The model may emit either whole files (fenced code blocks with a file path in the
+ * header) or search/replace patch blocks. This function handles both, writes the
+ * resulting files under the workspace root, and returns a per-file summary plus any
+ * errors encountered.
+ *
+ * `content` is the raw model output. `workspaceRoot` is the directory all emissions
+ * are anchored to. `parseSearchReplaceBlocks` and `applySearchReplaceBlocks` are the
+ * delta machinery, injected so this module does not import the composition root back.
+ */
+export declare function extractAndEmitFiles(content: string, targetFilesHint?: string[] | string, baseDir?: string, allowedRoots?: string[], protectedPaths?: string[], options?: {
+    enforceUnitScope?: boolean;
+}): {
+    filesWritten: FileEmissionResult[];
+    errors: string[];
+    cleanContent: string;
+};

package/dist/emission.js

@@ -0,0 +1,310 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configurePatchEngine = configurePatchEngine;
+exports.evaluateEmissionPath = evaluateEmissionPath;
+exports.evaluateUnitScope = evaluateUnitScope;
+exports.extractAndEmitFiles = extractAndEmitFiles;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const paths_1 = require("./paths");
+/**
+ * The delta machinery lives in `delegation.ts`, which imports this module rather than the other way
+ * round, so this module cannot import it. It is configured from the composition root instead.
+ *
+ * Both seams are closed by default: an unconfigured emission treats every fenced body as a whole file,
+ * which is the pre-delta behaviour, and `applyPatch` refuses instead of guessing.
+ */
+let parsePatchBody = () => null;
+let applyPatch = () => ({
+    ok: false,
+    reason: 'the search/replace engine is not configured, so no patch can be applied',
+});
+/** Called once by the composition root, which holds both halves of the delta machinery. */
+function configurePatchEngine(engine) {
+    parsePatchBody = engine.parse;
+    applyPatch = engine.apply;
+}
+/**
+ * The containment decision for one delegated write. `baseDir` is the session workspace
+ * and `allowedRoots` is the operator's explicit extension list. Both sides are
+ * canonicalised, so a symlink inside the workspace cannot be used to escape it.
+ */
+function evaluateEmissionPath(resolvedPath, baseDir, allowedRoots = []) {
+    const canonical = (0, paths_1.canonicalisePath)(resolvedPath);
+    const roots = [baseDir, ...allowedRoots].filter((root) => typeof root === 'string' && root.trim().length > 0);
+    for (const root of roots) {
+        if ((0, paths_1.isPathWithin)((0, paths_1.canonicalisePath)(root), canonical))
+            return { allowed: true };
+    }
+    return {
+        allowed: false,
+        reason: `Refused to write '${resolvedPath}': it resolves to '${canonical}', which is outside the session ` +
+            `workspace '${path.resolve(baseDir)}'` +
+            (allowedRoots.length > 0 ? ` and every configured emitAllowlist root` : '') +
+            `. A delegated worker may only write inside its workspace; add the directory to emitAllowlist to permit it.`,
+    };
+}
+/** The declared targets, in the shapes the tool accepts, with blanks dropped. */
+function normaliseTargets(targetFilesHint) {
+    if (Array.isArray(targetFilesHint)) {
+        return targetFilesHint.map((t) => String(t ?? '')).filter((t) => t.trim().length > 0);
+    }
+    if (typeof targetFilesHint === 'string' && targetFilesHint.trim())
+        return [targetFilesHint.trim()];
+    return [];
+}
+/**
+ * The scope decision for one delegated write: is this path one the unit declared?
+ *
+ * `targetFiles` used to be entirely passive — it became prompt text and it chose a fallback path when a
+ * fenced block named no file of its own — so a unit told to change one file could rewrite another, and
+ * nothing refused it, reported it, or noticed. That is the precondition for two units disagreeing, and it
+ * lands strictly before any project-level check could see it.
+ *
+ * A declared directory covers its subtree, because `isPathWithin` counts a path as within itself or
+ * beneath it. That makes `src`, `src/` and an exact file name all usable declarations, with one rule.
+ *
+ * An empty or absent declaration constrains nothing. A unit that declared no targets has not exceeded
+ * them, and refusing everything for an empty list would break every caller that never set the field.
+ */
+function evaluateUnitScope(resolvedPath, declaredTargets, baseDir) {
+    const declared = normaliseTargets(declaredTargets);
+    if (declared.length === 0)
+        return { allowed: true };
+    const canonical = (0, paths_1.canonicalisePath)(resolvedPath);
+    for (const target of declared) {
+        const resolvedTarget = path.isAbsolute(target) ? target : path.resolve(baseDir, target);
+        if ((0, paths_1.isPathWithin)((0, paths_1.canonicalisePath)(resolvedTarget), canonical))
+            return { allowed: true };
+    }
+    return {
+        allowed: false,
+        reason: `Refused to write '${resolvedPath}': this unit declared its targets, and that path is not one of ` +
+            `them (${declared.join(', ')}). A unit that writes outside what it declared is how two units come ` +
+            `to disagree. Re-delegate with the file declared if the change is intended, or set unitScope: ` +
+            `'off' to allow writes anywhere in the workspace.`,
+    };
+}
+/**
+ * Parse the model's final content into file emissions and write them to disk.
+ *
+ * The model may emit either whole files (fenced code blocks with a file path in the
+ * header) or search/replace patch blocks. This function handles both, writes the
+ * resulting files under the workspace root, and returns a per-file summary plus any
+ * errors encountered.
+ *
+ * `content` is the raw model output. `workspaceRoot` is the directory all emissions
+ * are anchored to. `parseSearchReplaceBlocks` and `applySearchReplaceBlocks` are the
+ * delta machinery, injected so this module does not import the composition root back.
+ */
+function extractAndEmitFiles(content, targetFilesHint, baseDir = process.cwd(), allowedRoots = [], protectedPaths = [], options = {}) {
+    if (!content)
+        return { filesWritten: [], errors: [], cleanContent: '' };
+    // Declared targets are a boundary unless a caller says otherwise. `false` restores the behaviour before
+    // that boundary existed, which is what `unitScope: 'off'` is for; anything else, including absent, means
+    // enforce.
+    const enforceUnitScope = options.enforceUnitScope !== false;
+    const filesWritten = [];
+    const emissionErrors = [];
+    const seenPaths = new Set();
+    function emitFile(filePath, fileCode) {
+        if (!filePath || !fileCode)
+            return;
+        const cleanPath = filePath.trim().replace(/^["']|["']$/g, '');
+        const resolvedPath = path.isAbsolute(cleanPath) ? cleanPath : path.resolve(baseDir, cleanPath);
+        // Containment first: the worker's fence header and the caller's targetFiles hints
+        // both choose this path, so it is untrusted input. Absolute paths and `..` segments
+        // used to escape the workspace silently; they are now refused and reported.
+        const containment = evaluateEmissionPath(resolvedPath, baseDir, allowedRoots);
+        if (!containment.allowed) {
+            emissionErrors.push(String(containment.reason));
+            console.warn(`[EMIT_FILE_BLOCKED] ${containment.reason}`);
+            return;
+        }
+        // Contract files belong to the architect. This is checked before anything is written, and it
+        // covers every emission route -- the fenced header, the `// FILE:` marker, and the fallback --
+        // because they all funnel through here.
+        const protectedHit = protectedPaths.find((p) => (0, paths_1.canonicalisePath)(String(p)) === (0, paths_1.canonicalisePath)(resolvedPath));
+        if (protectedHit) {
+            emissionErrors.push(`Refused to write ${resolvedPath}: it is a contract file declared by the architect, and the ` +
+                `executor may not modify the test that judges it.`);
+            console.warn(`[EMIT_FILE_BLOCKED] contract file: ${resolvedPath}`);
+            return;
+        }
+        // Scope third, and after the contract check deliberately: a contract file has to be refused for being
+        // a contract rather than for being undeclared, or the reason the operator reads would name the wrong
+        // rule.
+        if (enforceUnitScope) {
+            const scope = evaluateUnitScope(resolvedPath, targetFilesHint, baseDir);
+            if (!scope.allowed) {
+                emissionErrors.push(String(scope.reason));
+                console.warn(`[EMIT_FILE_SCOPE_BLOCKED] ${scope.reason}`);
+                return;
+            }
+        }
+        if (seenPaths.has(resolvedPath))
+            return;
+        seenPaths.add(resolvedPath);
+        // A search/replace body is a delta against an existing file rather than a replacement for it. The
+        // header syntax is shared, so the body decides the mode. An empty list means the body started a
+        // patch and never finished it, which is refused rather than written over a real file.
+        const patchBlocks = parsePatchBody(fileCode);
+        if (!patchBlocks && fs.existsSync(resolvedPath)) {
+            // This is an edit boundary, not a heuristic. A whole-file emission creates rather than modifies, and the
+            // worker has no repository read, so it cannot have seen this file unless the architect injected it; a file
+            // it has not seen can only be replaced blindly. That is how the contract-first experiment's mutation step
+            // returned a rewritten 86-line module in place of a 129-line one and the write landed, reported as nothing
+            // more than a failing contract. The size heuristic that used to guard this compared byte counts, and a
+            // substitution that keeps most of the bytes passes that regardless of how much of the file actually changed.
+            // A patch is not a restriction on what can be expressed, since the whole file can still be replaced with
+            // its entire content as the search text, only on what can be done silently.
+            emissionErrors.push('Refused to overwrite ' + resolvedPath + ': ' +
+                'the file already exists and a whole-file emission may create a file but not modify one; ' +
+                'the worker cannot see the file unless its content was injected, so the architect should re-delegate ' +
+                'with the content as context and have the worker emit a search/replace patch instead');
+            console.warn('[EMIT_FILE_BLOCKED] existing file, whole-file emission: ' + resolvedPath);
+            return;
+        }
+        if (patchBlocks) {
+            if (!fs.existsSync(resolvedPath)) {
+                emissionErrors.push(`Refused to patch ${resolvedPath}: it does not exist, and a search/replace block edits a ` +
+                    `file rather than creating one.`);
+                return;
+            }
+            let original;
+            try {
+                original = fs.readFileSync(resolvedPath, 'utf8');
+            }
+            catch (err) {
+                emissionErrors.push(`Failed to read ${resolvedPath} for patching: ${err?.message || String(err)}`);
+                return;
+            }
+            const applied = applyPatch(original, patchBlocks);
+            if (!applied.ok) {
+                emissionErrors.push(`Refused to patch ${resolvedPath}: ${applied.reason}`);
+                console.warn(`[EMIT_PATCH_BLOCKED] ${resolvedPath}: ${applied.reason}`);
+                return;
+            }
+            fileCode = applied.content;
+        }
+        try {
+            const parentDir = path.dirname(resolvedPath);
+            fs.mkdirSync(parentDir, { recursive: true });
+            fs.writeFileSync(resolvedPath, fileCode, 'utf8');
+            const lines = fileCode.split('\n').length;
+            const bytes = Buffer.byteLength(fileCode, 'utf8');
+            const relativeName = path.relative(baseDir, resolvedPath) || cleanPath;
+            filesWritten.push({
+                path: resolvedPath,
+                relativeName,
+                lines,
+                bytes,
+                mode: patchBlocks ? 'patch' : 'write',
+                ...(patchBlocks ? { hunks: patchBlocks.length } : {}),
+            });
+        }
+        catch (err) {
+            const message = 'Failed to write ' + resolvedPath + ': ' + (err?.message || String(err));
+            emissionErrors.push(message);
+            console.warn('[EMIT_FILE_ERROR] ' + message);
+        }
+    }
+    const FENCE = '\x60\x60\x60';
+    // The closing fence is matched only where a fence can legally close: nothing follows it on its line,
+    // and nothing but whitespace precedes it. A non-greedy scan to the next bare run of backticks stops
+    // at the first one *anywhere*, so a body that itself contains a fence -- a patch quoting one, or a
+    // markdown example inside a source file -- had its tail silently dropped and was then refused as a
+    // malformed patch. The comment is kept fence-free so this line stays patchable by a confined agent.
+    // The fallback at the bottom is for output that named no file of its own. It must not run when a file
+    // WAS named and then refused: writing that content at the declared hint instead would put bytes meant
+    // for one path at another, and it would walk straight around a containment, contract or scope refusal
+    // by simply retrying somewhere the check happens to allow.
+    let namedTargetSeen = false;
+    const fileAttrRegex = new RegExp(FENCE + '[a-zA-Z0-9_-]*\\s+(?:file|filename)=["\']?([^"\'\\s\\n>]+)["\']?\\s*\\n([\\s\\S]*?)[ \\t]*' + FENCE + '[ \\t]*(?:\\r?\\n|$)', 'gi');
+    let match;
+    while ((match = fileAttrRegex.exec(content)) !== null) {
+        namedTargetSeen = true;
+        emitFile(match[1], match[2]);
+    }
+    const fileMarkerRegex = new RegExp(FENCE + '[a-zA-Z0-9_-]*\\n(?://\\s*FILE:\\s*|#\\s*FILE:\\s*|/\\*\\s*FILE:\\s*|\\[FILE:\\s*)([^\\s\\n\\*\\]]+)(?:\\s*\\*/|\\])?\\n([\\s\\S]*?)' + FENCE, 'gi');
+    while ((match = fileMarkerRegex.exec(content)) !== null) {
+        namedTargetSeen = true;
+        emitFile(match[1], match[2]);
+    }
+    if (!namedTargetSeen && filesWritten.length === 0 && targetFilesHint) {
+        const hints = Array.isArray(targetFilesHint)
+            ? targetFilesHint
+            : typeof targetFilesHint === 'string'
+                ? [targetFilesHint]
+                : [];
+        const allCodeBlocks = [];
+        const FENCE = '\x60\x60\x60';
+        const genericCodeBlockRegex = new RegExp(FENCE + '[a-zA-Z0-9_-]*\\n([\\s\\S]*?)' + FENCE, 'gi');
+        let cbMatch;
+        while ((cbMatch = genericCodeBlockRegex.exec(content)) !== null) {
+            if (cbMatch[1].trim()) {
+                allCodeBlocks.push(cbMatch[1]);
+            }
+        }
+        if (allCodeBlocks.length > 0) {
+            for (let i = 0; i < hints.length; i++) {
+                const hintPath = hints[i];
+                const code = allCodeBlocks[i] || allCodeBlocks[0];
+                if (hintPath && code) {
+                    emitFile(hintPath, code);
+                }
+            }
+        }
+        else if (content.trim() && hints.length > 0) {
+            // Only write unreferenced output when it actually looks like source code.
+            // A worker that cannot read the target file may answer with prose or a
+            // tool-call transcript; writing that over a real file destroys it.
+            const body = content.trim();
+            const toolCall = '<' + 'tool_call|<function=|<' + '/tool_call>';
+            const proseOpen = "\\s*(?:I'll|I will|I've|Here(?:'s| is)|Sure|Certainly|Let me|First,|To do this)";
+            const looksLikeProse = new RegExp(toolCall, 'i').test(body) || new RegExp('^' + proseOpen, 'im').test(body);
+            const codeStart = '^(?://|#|<!--|/\\*|import\\s|export\\s|const\\s|let\\s|var\\s|function\\s|class\\s|interface\\s|type\\s|def\\s|package\\s|using\\s|public\\s|private\\s|<!DOCTYPE|<[a-zA-Z])';
+            const looksLikeCode = new RegExp(codeStart, 'm').test(body);
+            if (looksLikeProse || !looksLikeCode) {
+                emissionErrors.push('Refused to write ' + hints[0] + ': worker output has no fenced code block and does not look like source code.');
+            }
+            else {
+                emitFile(hints[0], body);
+            }
+        }
+    }
+    return { filesWritten, errors: emissionErrors, cleanContent: content };
+}

package/dist/guard.d.ts

@@ -0,0 +1,162 @@
+import type { DelegatedRecord } from './contracts';
+/** Shell tools can write files as a side effect; detection is best-effort. */
+export declare const SHELL_TOOLS: Set<string>;
+/**
+ * Tools that read a file's contents into the caller's context. Exported because `describeSourceRead`
+ * asks the same question — is this tool a read? — and two lists would drift.
+ */
+export declare const READ_TOOLS: Set<string>;
+/**
+ * Search tools return file content, so the read gate has to treat them as reads. This is the read
+ * gate's copy of the vocabulary `READ_ONLY_INSPECTORS` already carries for the write guard: a tool
+ * which reads files in one guard and is invisible in the other is how rule 3 was bypassed — an agent
+ * was refused by the read guard and read the same files with search.
+ */
+export declare const SEARCH_TOOLS: Set<string>;
+export interface GuardVerdict {
+    kind: 'deny' | 'ask';
+    target: string;
+    reason: string;
+}
+/**
+ * The file a tool call names, from whichever argument shape that tool uses. Exported because `apply`
+ * passes it to `describeSourceRead`, which asks the same question about the same call.
+ */
+export declare function extractWriteTarget(args: any): string | undefined;
+/**
+ * Does this command line carry a write signal? A redirection counts only when it is a
+ * real one: an `=>` in inline program text and a `2>&1` must not turn a read-only
+ * command into an approval prompt.
+ */
+export declare function hasCommandWriteSignal(command: string): boolean;
+/**
+ * Delete-capable constructs, checked against BOTH a command line and a script body.
+ * Destroying a source file is at least as consequential as overwriting it, and the first
+ * version of this guard left deletion entirely ungated. API-level removals are included
+ * because inline program text (`python -c "os.remove(...)"`) never names a verb the
+ * command line displays. Word-anchored for the same reason as the write list: unanchored,
+ * `rm` matches inside unrelated paths and `Move-Item` matches inside `Remove-Item`.
+ */
+export declare const DELETE_PRIMITIVES: RegExp;
+/** Does this command line or script body carry a delete signal? */
+export declare function hasCommandDeleteSignal(text: string): boolean;
+/**
+ * Normalise one shell token to a bare program name.
+ *
+ * The extension strip has to match everywhere a program is recognised, or an alias is half-known: the
+ * prefilter compared raw lowercased tokens while `commandReadsContent` and `isReadArgument` both
+ * stripped `.exe`/`.cmd`/`.bat`/`.ps1`, so `gc.ps1` was rejected by the first and accepted by the
+ * others. One normaliser, one answer.
+ */
+export declare function shellCommandName(token: string): string;
+/**
+ * Does this command READ FILE CONTENT, rather than list, test or compare?
+ *
+ * `CONTENT_READERS` and only `CONTENT_READERS`. An earlier attempt took the union with
+ * `READ_ONLY_INSPECTORS` here and `control-bypass.test.cjs` failed on the very next run: that set
+ * exists to answer "is this token read as data rather than invoked", which is a *different* question,
+ * and it carries `ls`, `get-childitem`, `test-path`, `stat` and friends. Treating those as byte
+ * readers is the false positive the two-set split was introduced to remove.
+ *
+ * Note what this predicate is NOT responsible for. A metadata command passes the prefilter and then
+ * correctly reports "does not read content" here, so it is allowed -- which is why the prefilter
+ * cannot use this set as its membership test without also un-gating nothing. See the read gate.
+ */
+export declare function commandReadsContent(command: string): boolean;
+/**
+ * The longest source-extension reference in a string.
+ *
+ * The guard previously took the FIRST match, so a command whose prose happened to contain
+ * something extension-shaped — an explanation mentioning `(.ts)` — reported that fragment as
+ * the target instead of the real path.
+ */
+export declare function longestCodeReference(text: string): string | undefined;
+export type DelegateReadPolicy = 'ask' | 'allow' | 'deny';
+/**
+ * What happens when an agent reads a file a delegated worker wrote.
+ *
+ * The guard cannot yet tell the architect from a lead, so it gates any agent reading delegated code.
+ * `ask` is the right default: pulling that code back into the architect's context defeats the point of
+ * having delegated it, but reviewing a line is sometimes exactly what an operator wants.
+ *
+ * `allow` is an escape hatch for a lead tier that has to read the code it writes contracts about. It is
+ * an honest weakening of rule 3 rather than a fix, so the reason says which rule it costs — the config
+ * entry documents its own price instead of quietly being a bypass.
+ */
+export declare function evaluateDelegatedReadPolicy(policy?: DelegateReadPolicy): {
+    kind: 'allow' | 'ask' | 'deny';
+    reason: string;
+};
+export interface SettledVerdict {
+    allowed: boolean;
+    reason: string;
+}
+/**
+ * Is this delegated file settled -- written by a unit that passed, with its content unchanged since?
+ *
+ * `succeeded` alone is not the test, because a verdict describes CONTENT. A file that passed and was then
+ * edited is not the version anything verified, so the hash is compared too, and a file that cannot be
+ * hashed fails closed rather than open. Pure and exported so the rule is testable without a registry.
+ */
+export declare function evaluateSettledFile(record: DelegatedRecord | undefined, currentHash: string | null): SettledVerdict;
+/**
+ * Where the TYPE SKELETON for a source file lives, relative to a declarations root.
+ *
+ * This is the mapping that lets a read be served as declarations instead of implementation. It is a pure
+ * string transform on purpose: the caller decides whether the result exists, because a mapping function
+ * that silently invents a path is worse than one that returns the path it computed and lets the caller
+ * refuse.
+ *
+ * Returns null for anything that is not a TypeScript or JavaScript source file, so a caller can treat null
+ * as "this read is out of scope" rather than as a failure.
+ *
+ * The transform mirrors what `tsc --declaration --emitDeclarationOnly` emits for a `rootDir` of the source
+ * directory: the tree below the root is preserved and only the extension changes.
+ */
+export declare function declarationPathFor(sourcePath: string, declarationRoot?: string): string | null;
+/**
+ * Is a declaration STALE relative to the source it is supposed to describe?
+ *
+ * The egress control redirects a source read to `<root>/x.d.ts`. Until this existed it verified only that
+ * the file EXISTED, never that it still described the source — so editing an interface and skipping the
+ * build served the architect yesterday's signature, and nothing anywhere would have said so. That is the
+ * same shape as every false green this repository has caught: healthy under test, because a test suite
+ * always runs against a freshly built tree, and wrong exactly when a human is working.
+ *
+ * Returns a reason when stale, or null when the declaration is fresh OR when either timestamp cannot be
+ * read. An unreadable stat deliberately returns null rather than a reason: the caller's next step is to read
+ * the declaration, which has its own fail-closed path when that file is missing, and inventing a staleness
+ * verdict from a failed stat would report a cause it has not established.
+ *
+ * WHAT THIS IS NOT: a content digest. mtime is evidence that a rebuild happened after an edit, and a
+ * checkout, a `touch`, or clock skew can defeat it. It closes the common case -- an operator planning
+ * without running the build -- and it does not prove the declaration corresponds to the source. Binding
+ * those two cryptographically is a larger change than this gap warrants, and claiming it here would be the
+ * overstatement this file exists to avoid.
+ */
+export declare function staleDeclarationReason(sourcePath: string, declarationPath: string): string | null;
+/**
+ * Decide whether a tool call would author source code from the cloud context.
+ * Pure and exported so it can be unit-tested without a running server.
+ * Returns null when the call has nothing to do with code authoring.
+ */
+export declare function evaluateCodeWriteGuard(exec: any, config?: {
+    askPaths?: string[];
+    /** Injectable reader, so the script scan is testable without touching disk. */
+    readScript?: (script: string) => string | undefined;
+    /** How deep to follow script-invokes-script (default 2). */
+    scriptDepth?: number;
+    /** Paths a delegated worker wrote; reads of them are gated. Injectable for tests. */
+    delegatedPaths?: Iterable<string>;
+    /**
+     * How to find the record for a delegated file, by canonical path. Injectable so the settled rule can
+     * be exercised against synthetic verdicts; the default reads the index the delegation itself wrote.
+     */
+    delegatedRecordFor?: (canonicalPath: string) => DelegatedRecord | undefined;
+    /** ask | allow | deny for reading a delegated file back. Defaults to ask. */
+    delegateReadPolicy?: DelegateReadPolicy;
+    /** Paths the architect may author as the specification. Defaults to tests/. */
+    contractPaths?: string[];
+    /** allow | ask | deny for a write to a contract path. Defaults to ask. */
+    contractWriteMode?: 'allow' | 'ask' | 'deny';
+}): GuardVerdict | null;