ast-mcp-server 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-08-05
+
+### Added
+
+- Bounded JSON-safe project status contracts and the read-only `ast_get_project_status` tool.
+- Session freshness metadata with separate source, config, and canonical fingerprints.
+- Serialized operation-queue accounting and status integration without changing reviewed mutation semantics.
+
+### Changed
+
+- Source synchronization verifies stability across refresh, snapshot, refresh, and verification before reporting fresh state.
+- Phase 1 keeps the symbol index disabled while exposing explicit stale/degraded recovery state.
+
+### Security
+
+- Status projections redact identities, absolute paths, credentials, and multi-token `Authorization` values at both transition and projection boundaries.
+- Noncanonical external fingerprints are converted to bounded opaque SHA-256 digests before projection.
+
+## [0.5.0] - 2026-08-03
+
+### Added
+
+- Relevance-ranked symbol search with `selectors`, `summary`, and backward-compatible `full` detail profiles.
+- Progressive semantic references with location-only defaults and opt-in bounded source context.
+- `ast_scaffold_class`, a strict prepare-only class scaffold that generates explicit throwing method placeholders and uses the existing preview/apply protocol.
+- Hash-bound absent-file plans with atomic no-clobber creation, conservative rollback, persisted replay, and idempotent receipt recovery.
+- A checked result-shaping workflow benchmark covering ranking, selector chaining, multi-file references, JSON/TOON payloads, call counts, evidence preservation, and complete tool metadata.
+
+### Changed
+
+- Symbol search now defaults to ranked `summary` records with a 20-result page. Use `detail: "full", limit: 100` for the v0.4.0 result profile.
+- Reference search now defaults to `locations` without source lines. Use `detail: "context"` for the v0.4.0 record profile.
+- MCP and batch client identity now derives from the shipped package version instead of a separately maintained literal.
+
+### Security
+
+- Scaffold inputs are strict and bounded; identifiers, duplicates, raw TypeScript fragments, paths, parent directories, and target absence are validated before plan creation.
+- File creation uses same-directory exclusive staging plus an atomic hard-link commit and never falls back to overwrite-capable rename.
+- Existing rename/body-replacement plan hashes and persisted modification plans remain compatible.
+
 ## [0.4.0] - 2026-08-03
 
 ### Added
@@ -44,5 +84,7 @@ Initial public release.
 - Apply rejects stale workspaces, changed configs/sources, mismatched plan hashes, unsafe plan files, conflicting MCP registrations, and conflicting skill content.
 - Inputs, outputs, operation stores, subprocesses, batch fan-out, plan lifetime, and filesystem access are bounded.
 
+[0.5.1]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.5.1
+[0.5.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.5.0
 [0.4.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.4.0
 [0.3.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.3.0

package/README.md

@@ -39,7 +39,7 @@ Reads can start with a compact outline and fetch exact source only when needed.
 
 AST-aware editing is not a proof that a change is semantically correct. The safety comes from combining structural selection with diagnostics, exact previews, reviewed hashes, freshness checks, and fail-closed apply semantics.
 
-The included batch benchmark records a 50% reduction in model round-trips and a 95.21% reduction in serialized context for its search-to-source scenario. The format benchmark records an `o200k_base` estimate of 25.72% fewer model-facing tokens for a 100-row symbol search and 26.56% across the eligible collection corpus. These are reproducible scenario measurements, not universal token, billing, cache, or latency claims.
+The included batch benchmark records a 50% reduction in model round-trips and a 94.67% reduction in serialized context for its search-to-source scenario. The result-shaping corpus records a 68.80% reduction in aggregate model-facing TOON tokens while preserving declared selectors/reference coordinates with the same six logical calls. The separate format benchmark records 25.87% across its eligible collection corpus. These are reproducible local `o200k_base` estimates, not universal token, billing, cache, or latency claims.
 
 ## Requirements
 
@@ -224,11 +224,14 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 | `ast_get_diagnostics`       | Project- or file-scoped TypeScript diagnostics                       | No            |
 | `ast_rename_symbol`         | Prepare a project-wide rename                                        | No            |
 | `ast_replace_symbol_body`   | Prepare a body-only replacement while preserving the signature       | No            |
+| `ast_scaffold_class`        | Prepare one new class file with explicit placeholder methods         | No            |
 | `ast_get_operation_preview` | Retrieve the complete retained diff for a prepared plan              | No            |
 | `ast_apply_operation`       | Apply one reviewed, hash-bound plan                                  | Yes           |
 
 Read results use project-relative paths, deterministic ordering, structured MCP output, and pagination where result sets can grow with the project.
 
+Symbol search is relevance-ranked and defaults to at most 20 `summary` records containing `file`, a directly reusable `selector`, `kind`, and body-free `signature`. Request `detail: "selectors"` for routing coordinates only, or `detail: "full", limit: 100` for the v0.4.0 fields/page. References default to `detail: "locations"`; request `detail: "context"` only when the bounded source line is needed.
+
 ### Optional TOON results
 
 `ast_search_symbols`, `ast_find_references`, and `ast_get_diagnostics` accept `output_format: "toon"` for collection-heavy results consumed directly by a model. JSON remains the default and preserves the canonical structured object.
@@ -265,7 +268,7 @@ Example search-to-source pipeline:
       "tool": "ast_get_symbol_source",
       "input": {
         "file_path": { "$ref": "#/steps/search/symbols/0/file" },
-        "symbol_path": { "$ref": "#/steps/search/symbols/0/symbol_path" }
+        "symbol_path": { "$ref": "#/steps/search/symbols/0/selector" }
       }
     }
   ],
@@ -314,15 +317,17 @@ Success is one compact JSON value on stdout by default. `ast-tool run --output-f
 
 ### MCP process
 
-Rename and body replacement never write directly:
+Rename, body replacement, and class scaffold never write directly during preparation:
 
-1. Call `ast_rename_symbol` or `ast_replace_symbol_body`.
+1. Call `ast_rename_symbol`, `ast_replace_symbol_body`, or `ast_scaffold_class`.
 2. Review the diagnostic delta, affected files, `blocked`, and `plan_hash`.
 3. Fetch complete diffs with `ast_get_operation_preview` when needed.
 4. Call `ast_apply_operation` with both `operation_id` and `plan_hash`.
 
 MCP plans live in a bounded in-memory store and do not survive a server restart.
 
+`ast_scaffold_class` accepts structured imports, heritage, decorators, constructor parameter properties, initialized properties, and one or more method signatures. It creates an in-memory preview for one absent project-relative `.ts`/`.tsx` target. Each generated method initially contains only `throw new Error("Not implemented: Class.method")`. Review the `/dev/null` creation diff and diagnostics, apply the scaffold, then replace each pending method body with `ast_replace_symbol_body`. Existing targets and symbolic/traversing parents fail closed.
+
 ### CLI process boundary
 
 A batch may contain at most one prepare operation. It must be the final step and cannot use foreach. `ast_apply_operation` and arbitrary preview calls are forbidden inside batch documents.
@@ -380,15 +385,18 @@ yarn benchmark /absolute/project --sample 20 --output benchmark/results/project.
 yarn benchmark:corpus benchmark/task-corpus.json --output benchmark/results/self-corpus.json
 yarn benchmark:batch --iterations 5 --output benchmark/results/self-batch.json
 yarn benchmark:formats
+yarn benchmark:shapes
 ```
 
 The batch benchmark compares two separate client calls with one batch invocation in fresh Node processes, recording model round-trips, actual tool invocations, wall time, maximum RSS, and serialized character counts. Character counts are not model-specific token estimates.
 
 The format benchmark runs real tools against this repository plus deterministic reference/diagnostic fixtures. It checks JSON→TOON→value equality, UTF-8 bytes, `gpt-tokenizer` `o200k_base` estimates, encode/decode latency, the actual MCP envelope, tool metadata, and negative controls. Its checked result is `benchmark/results/self-formats.json`; local tokenizer estimates do not establish provider-side billing or cache savings. See `benchmark/README.md` for methodology and limitations.
 
+The result-shaping benchmark compares the v0.4.0-compatible `full/100/context` profiles with the new public defaults across exact-name, exact-path, prefix, broad-substring, and multi-file-reference tasks. It fails on missing evidence, extra logical calls, fewer than 11 tools, or less than 35% aggregate TOON token reduction. Its checked result is `benchmark/results/self-result-shapes.json`.
+
 ## Scope
 
 - TypeScript and JavaScript projects understood by the TypeScript compiler.
-- Structural rename and callable-body replacement.
+- Structural rename, callable-body replacement, and reviewed creation of one class scaffold.
 - Declarative DAG-like pipelines with prior-result references and bounded foreach.
-- No arbitrary signature migration, file creation/deletion plans, cross-language refactors, or general-purpose scripting language.
+- No arbitrary signature migration, general file creation/deletion, cross-language refactors, or general-purpose scripting language.

package/benchmark/README.md

@@ -101,18 +101,29 @@ The checked broad search-to-source batch result used five fresh-process samples:
 
 | Mode     | Model round-trips | Tool invocations | Context chars | Median wall time | Median max RSS |
 | -------- | ----------------: | ---------------: | ------------: | ---------------: | -------------: |
-| Separate |                 2 |                2 |        11,514 |        536.19 ms |      377.54 MB |
-| Batch    |                 1 |                2 |           552 |        535.24 ms |      378.35 MB |
+| Separate |                 2 |                2 |         7,818 |        587.03 ms |      380.68 MB |
+| Batch    |                 1 |                2 |           417 |        607.95 ms |      379.15 MB |
 
-That run reduced model round-trips by 50% and serialized context by 95.21%. Local execution latency decreased by 0.18% and RSS increased by 0.21%, both small enough to treat as noise rather than a performance claim. The batch value is orchestration/context reduction; it does not make TypeScript analysis free.
+That run reduced model round-trips by 50% and serialized context by 94.67%. Local execution latency increased by 3.56% and RSS decreased by 0.40%, both small enough to treat as noise rather than a performance claim. The batch value is orchestration/context reduction; it does not make TypeScript analysis free.
 
 The checked model-facing format corpus used the complete MCP envelope for TOON:
 
 | Payload             | Records | JSON tokens | MCP TOON tokens | Reduction |
 | ------------------- | ------: | ----------: | --------------: | --------: |
-| Broad symbol search |     100 |       5,225 |           3,881 |    25.72% |
-| References          |      71 |       3,086 |           2,150 |    30.33% |
+| Broad symbol search |     100 |       5,382 |           4,061 |    24.54% |
+| References          |      71 |       3,094 |           2,159 |    30.22% |
 | Diagnostics         |      30 |       1,309 |           1,034 |    21.01% |
-| Eligible aggregate  |     201 |       9,620 |           7,065 |    26.56% |
+| Eligible aggregate  |     201 |       9,785 |           7,254 |    25.87% |
 
-All seven positive and negative payloads round-tripped exactly. File list, outline, source, and prepare envelopes ranged from 5.50% to 23.40% worse in estimated tokens, which is why they remain JSON-only. Current serialized tool metadata is 2,451 characters smaller than the v0.3.0 baseline despite the three new input fields, because multi-shape tools no longer advertise a single incompatible output schema.
+All seven positive and negative payloads round-tripped exactly. File list, outline, source, and prepare envelopes were 5.13% to 13.56% worse in estimated tokens, which is why they remain JSON-only. The complete eleven-tool metadata is 3,372 serialized characters larger than the retained v0.3.0 baseline; this static protocol cost is reported separately from dynamic result savings.
+
+The checked result-shaping corpus compares the v0.4.0-compatible `full/100/context` profiles with the new public defaults across exact-name, exact-path, prefix, broad-substring, and multi-file-reference workflows:
+
+| Profile   | Logical calls | MCP TOON tokens |
+| --------- | ------------: | --------------: |
+| Baseline  |             6 |           3,910 |
+| Candidate |             6 |           1,220 |
+
+Every declared selector and reference coordinate remained present, and the aggregate reduction was 68.80%, above the checked 35% gate. `duration_ms` is omitted from both measured representations to make token counts deterministic; real JSON/TOON outputs are still decode-compared before measurement. These are local `o200k_base` estimates, not provider billing, cache, or latency evidence.
+
+The complete v0.5.0 `tools/list` metadata is 22,473 serialized characters versus the retained v0.4.0 value of 16,650 (`+5,823`). Removing only `ast_scaffold_class` from the current list reduces it by 5,411 characters and 1,295 local `o200k_base` tokens. No v0.4.0 metadata token count was retained, so the report intentionally leaves the historical token delta unset.

package/dist/batch/runner.js

@@ -1,7 +1,7 @@
 import { performance } from "node:perf_hooks";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { createServer } from "../server.js";
+import { createServer, PACKAGE_VERSION } from "../server.js";
 import { MAX_BATCH_CONTEXT_BYTES, MAX_BATCH_INVOCATIONS, MAX_BATCH_OUTPUT_BYTES, MAX_FOREACH_ITEMS, isItemTemplate, isPrepareBatchTool, isReadBatchTool, isReferenceTemplate, parseBatchDocument as parseDocument, } from "./schema.js";
 export { parseDocument as parseBatchDocument };
 export class BatchExecutionError extends Error {
@@ -76,7 +76,7 @@ function injectProjectRoot(resolved, projectRoot, step) {
 }
 async function connectBatchClient() {
     const server = createServer();
-    const client = new Client({ name: "ast-tool-batch", version: "0.3.0" });
+    const client = new Client({ name: "ast-tool-batch", version: PACKAGE_VERSION });
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
     return { client, server };

package/dist/batch/schema.js

@@ -16,7 +16,11 @@ export const READ_BATCH_TOOLS = [
     "ast_find_references",
     "ast_get_diagnostics",
 ];
-export const PREPARE_BATCH_TOOLS = ["ast_rename_symbol", "ast_replace_symbol_body"];
+export const PREPARE_BATCH_TOOLS = [
+    "ast_rename_symbol",
+    "ast_replace_symbol_body",
+    "ast_scaffold_class",
+];
 export const BATCH_TOOLS = [...READ_BATCH_TOOLS, ...PREPARE_BATCH_TOOLS];
 const BatchToolSchema = z.enum(BATCH_TOOLS);
 const BatchStepSchema = z

package/dist/server.js

@@ -1,20 +1,26 @@
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerApplyOperation } from "./tools/apply_operation.js";
 import { registerFindReferences } from "./tools/find_references.js";
 import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
 import { registerGetOperationPreview } from "./tools/get_operation_preview.js";
 import { registerGetOutline } from "./tools/get_outline.js";
+import { registerGetProjectStatus } from "./tools/get_project_status.js";
 import { registerGetSymbolSource } from "./tools/get_symbol_source.js";
 import { registerListFiles } from "./tools/list_files.js";
 import { registerRenameSymbol } from "./tools/rename_symbol.js";
 import { registerReplaceSymbolBody } from "./tools/replace_symbol_body.js";
+import { registerScaffoldClass } from "./tools/scaffold_class.js";
 import { registerSearchSymbols } from "./tools/search_symbols.js";
+const packageMetadata = createRequire(import.meta.url)("../package.json");
+export const PACKAGE_VERSION = packageMetadata.version;
 export function createServer() {
     const server = new McpServer({
         name: "ast-mcp-server",
-        version: "0.3.0",
+        version: PACKAGE_VERSION,
     });
     registerListFiles(server);
+    registerGetProjectStatus(server);
     registerGetOutline(server);
     registerGetSymbolSource(server);
     registerSearchSymbols(server);
@@ -22,6 +28,7 @@ export function createServer() {
     registerGetDiagnostics(server);
     registerRenameSymbol(server);
     registerReplaceSymbolBody(server);
+    registerScaffoldClass(server);
     registerGetOperationPreview(server);
     registerApplyOperation(server);
     return server;

package/dist/services/agent-setup.js

@@ -17,6 +17,7 @@ const EXPECTED_HERMES_TOOLS = [
     "ast_get_diagnostics",
     "ast_rename_symbol",
     "ast_replace_symbol_body",
+    "ast_scaffold_class",
     "ast_get_operation_preview",
     "ast_apply_operation",
 ];

package/dist/services/operation-plan-file.js

@@ -42,7 +42,7 @@ const PersistedOperationSchema = z
     .object({
     operation_id: z.string().uuid(),
     plan_hash: HashSchema,
-    kind: z.enum(["rename_symbol", "replace_symbol_body"]),
+    kind: z.enum(["rename_symbol", "replace_symbol_body", "scaffold_class"]),
     status: z.enum(["prepared", "applied"]),
     project_root: z.string().min(1),
     created_at: IsoDateSchema,

package/dist/services/operations.js

@@ -1,17 +1,20 @@
 import { createHash, randomUUID } from "node:crypto";
 import { lstatSync, realpathSync } from "node:fs";
-import { open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { link, open, readFile, rename, stat, unlink } from "node:fs/promises";
 import path from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { LanguageVariant, Node, ScriptTarget, SyntaxKind, ts } from "ts-morph";
 import { compareDiagnostics, normalizeDiagnostic, } from "./diagnostics.js";
 import { createFreshProject, findDeclarationByName, getSourceFileOrThrow, invalidateProject, } from "./project.js";
 import { executableDeclaration } from "./symbols.js";
+import { buildClassScaffold } from "./scaffold.js";
 import { withWorkspaceFileLock } from "./runtime-state.js";
 import { createWorkspaceSnapshot, hashBytes, hashWorkspaceFiles } from "./workspace.js";
 const DEFAULT_OPERATION_TTL_MS = 15 * 60 * 1000;
 const DEFAULT_MAX_OPERATIONS = 100;
 const MAX_INLINE_PREVIEW_CHARS = 100_000;
+const ABSENT_FILE_HASH = "0".repeat(64);
+const DEFAULT_NEW_FILE_MODE = 0o644;
 const operations = new Map();
 const writeQueues = new Map();
 let operationTestHooks = {};
@@ -104,6 +107,53 @@ function assertSafeOperationFile(projectRoot, absolutePath, displayPath) {
         throw new Error(`Operation target escapes the project root: ${displayPath}`);
     }
 }
+function isCreatedFile(file) {
+    return file.originalHash === ABSENT_FILE_HASH;
+}
+function assertSafeNewOperationFile(projectRoot, absolutePath, displayPath) {
+    const relative = path.relative(projectRoot, absolutePath);
+    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`)) {
+        throw new Error(`Operation target escapes the project root: ${displayPath}`);
+    }
+    try {
+        lstatSync(absolutePath);
+        throw new Error(`Operation target already exists: ${displayPath}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const parentPath = path.dirname(absolutePath);
+    const parentStat = lstatSync(parentPath);
+    if (parentStat.isSymbolicLink()) {
+        throw new Error(`Operation target parent must not be a symbolic link: ${displayPath}`);
+    }
+    if (!parentStat.isDirectory()) {
+        throw new Error(`Operation target parent must be a real directory: ${displayPath}`);
+    }
+    const canonicalParent = realpathSync(parentPath);
+    const sameParent = process.platform === "win32"
+        ? canonicalParent.toLowerCase() === parentPath.toLowerCase()
+        : canonicalParent === parentPath;
+    if (!sameParent) {
+        throw new Error(`Operation target parent traverses a symbolic link: ${displayPath}`);
+    }
+    const uid = process.getuid?.();
+    if (uid !== undefined && parentStat.uid !== uid) {
+        throw new Error(`Operation target parent is not owned by the current user: ${displayPath}`);
+    }
+}
+function assertSafeCreationState(projectRoot, absolutePath, displayPath) {
+    try {
+        lstatSync(absolutePath);
+        assertSafeOperationFile(projectRoot, absolutePath, displayPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        assertSafeNewOperationFile(projectRoot, absolutePath, displayPath);
+    }
+}
 async function createPlan(projectRootInput, kind, allowNewErrors, mutate) {
     pruneOperations();
     const context = createFreshProject(projectRootInput);
@@ -126,9 +176,28 @@ async function createPlan(projectRootInput, kind, allowNewErrors, mutate) {
     for (const sourceFile of context.project.getSourceFiles()) {
         const absolutePath = sourceFile.getFilePath();
         const originalText = originals.get(absolutePath);
-        if (originalText === undefined)
-            continue;
         const updatedText = sourceFile.getFullText();
+        if (originalText === undefined) {
+            const file = path.relative(context.projectRoot, absolutePath);
+            assertSafeNewOperationFile(context.projectRoot, absolutePath, file);
+            const originalBytes = Buffer.alloc(0);
+            const updatedBytes = Buffer.from(updatedText, "utf8");
+            files.push({
+                absolutePath,
+                file,
+                originalHash: ABSENT_FILE_HASH,
+                updatedHash: hashBytes(updatedBytes),
+                originalText: "",
+                updatedText,
+                originalBytes,
+                updatedBytes,
+                diff: createTwoFilesPatch("/dev/null", file, "", updatedText, "before", "after", {
+                    context: 3,
+                }),
+                mode: DEFAULT_NEW_FILE_MODE,
+            });
+            continue;
+        }
         if (updatedText === originalText)
             continue;
         const originalBytes = await readFile(absolutePath);
@@ -159,13 +228,13 @@ async function createPlan(projectRootInput, kind, allowNewErrors, mutate) {
     }
     const postWorkspaceFiles = new Map(workspaceBefore.files);
     for (const file of files) {
-        if (!postWorkspaceFiles.has(file.absolutePath)) {
+        if (!isCreatedFile(file) && !postWorkspaceFiles.has(file.absolutePath)) {
             throw new Error(`Affected file is missing from the workspace snapshot: ${file.file}`);
         }
         postWorkspaceFiles.set(file.absolutePath, file.updatedHash);
     }
     const postWorkspaceHash = hashWorkspaceFiles(postWorkspaceFiles);
-    const workspaceAfter = createWorkspaceSnapshot(context);
+    const workspaceAfter = createWorkspaceSnapshot(createFreshProject(context.tsConfigFilePath));
     if (workspaceAfter.digest !== workspaceBefore.digest) {
         throw new Error("Workspace changed while the operation was being prepared. Retry preparation.");
     }
@@ -261,6 +330,41 @@ export async function prepareReplaceBody(args) {
         return 0;
     });
 }
+export async function prepareScaffoldClass(args) {
+    if (path.isAbsolute(args.filePath)) {
+        throw new Error("Scaffold file_path must be project-relative.");
+    }
+    const normalizedFile = path.normalize(args.filePath);
+    if (normalizedFile === "." ||
+        normalizedFile === ".." ||
+        normalizedFile.startsWith(`..${path.sep}`) ||
+        normalizedFile !== args.filePath.split(path.posix.sep).join(path.sep)) {
+        throw new Error("Scaffold file_path must be normalized and remain inside the project root.");
+    }
+    if (!/\.(?:ts|tsx)$/.test(normalizedFile) || normalizedFile.endsWith(".d.ts")) {
+        throw new Error("Scaffold file_path must target a .ts or .tsx implementation file.");
+    }
+    let metadata;
+    const operation = await createPlan(args.projectRoot, "scaffold_class", args.allowNewErrors ?? false, (project, projectRoot) => {
+        const absolutePath = path.resolve(projectRoot, normalizedFile);
+        assertSafeNewOperationFile(projectRoot, absolutePath, normalizedFile);
+        const scaffold = buildClassScaffold(project, absolutePath, args.spec);
+        metadata = {
+            outline: scaffold.outline,
+            pendingMethods: scaffold.pendingMethods,
+        };
+        return 0;
+    });
+    if (!metadata)
+        throw new Error("Scaffold generation did not produce metadata.");
+    return {
+        operation,
+        file: normalizedFile.split(path.sep).join(path.posix.sep),
+        className: args.spec.className,
+        outline: metadata.outline,
+        pendingMethods: metadata.pendingMethods,
+    };
+}
 async function withWriteLock(key, callback) {
     const previous = writeQueues.get(key) ?? Promise.resolve();
     let release;
@@ -325,6 +429,24 @@ async function syncDirectories(files) {
         }
     }
 }
+async function currentWorkspaceHash(operation) {
+    const context = createFreshProject(operation.tsConfigFilePath);
+    const snapshot = createWorkspaceSnapshot(context);
+    const files = new Map(snapshot.files);
+    for (const file of operation.files) {
+        if (!isCreatedFile(file))
+            continue;
+        try {
+            files.set(file.absolutePath, hashBytes(await readFile(file.absolutePath)));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            files.delete(file.absolutePath);
+        }
+    }
+    return hashWorkspaceFiles(files);
+}
 function appliedResult(operation, idempotentReplay) {
     return {
         operation_id: operation.operation_id,
@@ -364,6 +486,7 @@ export async function applyOperation(operationId, planHash) {
     return withWriteLock(operation.tsConfigFilePath, async () => withWorkspaceFileLock(operation.tsConfigFilePath, { stateDirectory: operation.lockStateDirectory }, async () => {
         if (operation.status === "applied") {
             for (const file of operation.files) {
+                assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
                 const currentBytes = await readFile(file.absolutePath);
                 if (hashBytes(currentBytes) !== file.updatedHash) {
                     throw new Error(`Applied receipt conflict: ${file.file} no longer matches the recorded postimage.`);
@@ -380,12 +503,17 @@ export async function applyOperation(operationId, planHash) {
             throw new Error(operation.block_reason ?? "The operation is blocked by validation errors.");
         }
         for (const file of operation.files) {
-            assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
+            if (isCreatedFile(file)) {
+                assertSafeCreationState(operation.project_root, file.absolutePath, file.file);
+            }
+            else {
+                assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
+            }
         }
-        const currentContext = createFreshProject(operation.tsConfigFilePath);
-        const currentWorkspace = createWorkspaceSnapshot(currentContext);
-        if (currentWorkspace.digest === operation.post_workspace_hash) {
+        const workspaceHash = await currentWorkspaceHash(operation);
+        if (workspaceHash === operation.post_workspace_hash) {
             for (const file of operation.files) {
+                assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
                 const currentBytes = await readFile(file.absolutePath);
                 if (hashBytes(currentBytes) !== file.updatedHash) {
                     throw new Error(`Postimage recovery conflict: ${file.file} does not match the reviewed postimage.`);
@@ -397,10 +525,12 @@ export async function applyOperation(operationId, planHash) {
             await persistReceipt();
             return appliedResult(operation, true);
         }
-        if (currentWorkspace.digest !== operation.workspace_hash) {
+        if (workspaceHash !== operation.workspace_hash) {
             throw new Error("Conflict: the project source/config workspace changed after preparation. No files were written.");
         }
         for (const file of operation.files) {
+            if (isCreatedFile(file))
+                continue;
             const currentBytes = await readFile(file.absolutePath);
             if (hashBytes(currentBytes) !== file.originalHash) {
                 throw new Error(`Conflict: ${file.file} changed after the operation was prepared. No files were written.`);
@@ -413,6 +543,10 @@ export async function applyOperation(operationId, planHash) {
                 staged.set(file, await stageFile(file, operationId));
             }
             for (const file of operation.files) {
+                if (isCreatedFile(file)) {
+                    assertSafeNewOperationFile(operation.project_root, file.absolutePath, file.file);
+                    continue;
+                }
                 const currentBytes = await readFile(file.absolutePath);
                 if (hashBytes(currentBytes) !== file.originalHash) {
                     throw new Error(`Conflict: ${file.file} changed while the operation was being staged. No files were written.`);
@@ -420,9 +554,18 @@ export async function applyOperation(operationId, planHash) {
             }
             for (const [index, file] of operation.files.entries()) {
                 await operationTestHooks.beforeReplace?.(file.file, index);
-                await rename(staged.get(file), file.absolutePath);
-                staged.delete(file);
-                applied.push(file);
+                if (isCreatedFile(file)) {
+                    await link(staged.get(file), file.absolutePath);
+                    applied.push(file);
+                    await safeUnlink(staged.get(file));
+                    staged.delete(file);
+                }
+                else {
+                    await rename(staged.get(file), file.absolutePath);
+                    staged.delete(file);
+                    applied.push(file);
+                }
+                await operationTestHooks.afterReplace?.(file.file, index);
                 const writtenBytes = await readFile(file.absolutePath);
                 if (hashBytes(writtenBytes) !== file.updatedHash) {
                     throw new Error(`Post-write verification failed for ${file.file}.`);
@@ -439,7 +582,13 @@ export async function applyOperation(operationId, planHash) {
                         rollbackErrors.push(`${file.file}: current bytes no longer match this operation's postimage`);
                         continue;
                     }
-                    await restoreFile(file, operationId);
+                    if (isCreatedFile(file)) {
+                        assertSafeOperationFile(operation.project_root, file.absolutePath, file.file);
+                        await safeUnlink(file.absolutePath);
+                    }
+                    else {
+                        await restoreFile(file, operationId);
+                    }
                 }
                 catch (rollbackError) {
                     rollbackErrors.push(`${file.file}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
@@ -497,7 +646,6 @@ function containedOperationPath(projectRoot, file) {
     if (relative !== file.split(path.posix.sep).join(path.sep)) {
         throw new Error(`Persisted operation file path is not normalized: ${file}`);
     }
-    assertSafeOperationFile(projectRoot, absolutePath, file);
     return absolutePath;
 }
 export function exportOperationRecord(operationId) {
@@ -539,12 +687,19 @@ export function importOperationRecord(persisted, expectedPlanHash) {
         const absolutePath = containedOperationPath(context.projectRoot, file.file);
         const originalBytes = decodePersistedBytes(file.original_bytes_base64, `${file.file} original bytes`);
         const updatedBytes = decodePersistedBytes(file.updated_bytes_base64, `${file.file} updated bytes`);
-        if (hashBytes(originalBytes) !== file.original_hash) {
+        const createsFile = file.original_hash === ABSENT_FILE_HASH;
+        if (createsFile ? originalBytes.length !== 0 : hashBytes(originalBytes) !== file.original_hash) {
             throw new Error(`Persisted original hash mismatch for ${file.file}.`);
         }
         if (hashBytes(updatedBytes) !== file.updated_hash) {
             throw new Error(`Persisted updated hash mismatch for ${file.file}.`);
         }
+        if (createsFile) {
+            assertSafeCreationState(context.projectRoot, absolutePath, file.file);
+        }
+        else {
+            assertSafeOperationFile(context.projectRoot, absolutePath, file.file);
+        }
         const originalText = decodeSource(originalBytes, absolutePath);
         const updatedText = decodeSource(updatedBytes, absolutePath);
         return {
@@ -556,7 +711,7 @@ export function importOperationRecord(persisted, expectedPlanHash) {
             updatedText,
             originalBytes,
             updatedBytes,
-            diff: createTwoFilesPatch(file.file, file.file, originalText, updatedText, "before", "after", { context: 3 }),
+            diff: createTwoFilesPatch(createsFile ? "/dev/null" : file.file, file.file, originalText, updatedText, "before", "after", { context: 3 }),
             mode: file.mode,
         };
     });

package/dist/services/pagination.js

@@ -1,16 +1,22 @@
 import { z } from "zod";
 export const DEFAULT_PAGE_LIMIT = 100;
 export const MAX_PAGE_LIMIT = 500;
-export const PaginationInputSchema = {
-    offset: z.number().int().min(0).default(0).describe("Zero-based result offset."),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(MAX_PAGE_LIMIT)
-        .default(DEFAULT_PAGE_LIMIT)
-        .describe(`Maximum results to return (1-${MAX_PAGE_LIMIT}).`),
-};
+export function createPaginationInputSchema(defaultLimit = DEFAULT_PAGE_LIMIT) {
+    if (!Number.isInteger(defaultLimit) || defaultLimit < 1 || defaultLimit > MAX_PAGE_LIMIT) {
+        throw new Error(`Default page limit must be an integer from 1 to ${MAX_PAGE_LIMIT}.`);
+    }
+    return {
+        offset: z.number().int().min(0).default(0).describe("Zero-based result offset."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_PAGE_LIMIT)
+            .default(defaultLimit)
+            .describe(`Maximum results to return (1-${MAX_PAGE_LIMIT}).`),
+    };
+}
+export const PaginationInputSchema = createPaginationInputSchema();
 export const PaginationOutputSchema = {
     offset: z.number().int().min(0),
     limit: z.number().int().min(1),