fix(runner): align ordinary document key contracts (#18824)

## Thinking Path > - Paperclip helps people manage AI agents that do work. > - Native agents use tools to read and write task documents. > - A document key is a stable identifier. The service trims it and converts it to lowercase before it checks the key. > - The tool schemas accepted filenames and long keys that the service rejects. > - This pull request makes ordinary document tool schemas match the existing service contract. > - Agents can now see the key rules before they call the tools. ## Linked Issues or Issue Description **What happened?** The schemas for `read_document`, `write_document`, and `list_document_revisions` accepted `reconciliation.md` and keys longer than 64 characters after normalization. The task document service rejects these values. The descriptions did not explain that the key is an identifier rather than a filename. **Expected behavior** The model catalog and the live and scenario tool definitions must describe the existing document key rules. Values accepted after trimming and conversion to lowercase must remain compatible. Historical case-document keys use a separate contract. **Steps to reproduce** Validate `{ "key": "reconciliation.md" }` against the previous `read_document` schema. It passes. Call the document service with that key. It rejects the key before it reads the database. The added regression repeats this comparison for all three tools. ## What Changed - Apply the same document-key pattern to `read_task_document` and `write_task_document` at the API bridge. Keep their existing raw-input limit of 100 characters; ordinary tools keep 120. Export the shared schema through the existing Runner package and server vendor boundary. Route permissions, normalization and document locks stay with their current owners. - Add one shared schema for ordinary task-document keys. Keep the existing 120-character raw input cap and the 64-character normalized identifier limit. - Preserve uppercase input, ECMAScript trim whitespace, and the Kelvin sign, which converts to ASCII `k`. - Apply the schema to the model catalog and the three live and scenario definitions. Regenerate the catalogs, seeded fixture identity, and fixture manifest. - Test schema parity against the real task document service. Keep historical case keys and the backend validator unchanged. ## Verification - Current-head required CI is green at `e67d3f1f49393660f0c70b3d1d136e6f86af821d`: 56 successful checks, four intentional skips, and two neutral checks. [CI attempt 2](https://github.com/paperclipai/paperclip/actions/runs/41715924252) passed after one targeted rerun of five jobs interrupted by the same runner shutdown; the original interruption is retained. Fresh Greptile and Paperclip reviews are both 5/5 with no unresolved review threads. Hosted recovery remains unverified until automatic deployment and replay. - Normal master refresh to `e67d3f1f49393660f0c70b3d1d136e6f86af821d` includes the already merged external-object startup fixture correction. The previous required canary failed downloading `mdast-util-gfm-table@2.0.1` with npm E404; later registry metadata and tarball HEAD both returned 200. A separate general shard failed the ten-thousand-future-objects startup assertion. Both original failures remain recorded; neither was bypassed or retried. At the refreshed baseline, 122 document/bridge cases and the exact large-object startup case pass locally. Six document cases skip by platform. Fresh required CI and reviews must pass on this head. - The current-head Paperclip review found the same mismatch in the task-scoped bridge. Before the correction, the real advertised schemas failed 22 parity cases while 87 controls passed. After the correction and a normal master refresh, the document-key and bridge suites pass 122 cases, with six platform-specific skips. The tests compare advertised JSON Schema, runtime Zod validation, and the actual normalized document service. They retain the bridge raw 100/101 boundary and historical case-key controls. - Runner TypeScript build, all server typecheck layers, and the actual production Runner and server build pass. The final server build stamp binds commit `80c880709c5f5630799fb8a48d54ff11ebc16610`. Full current-head CI and fresh review are required after the correction. The earlier CI run was externally cancelled and rerun; its cancellation remains recorded. - The regression failed in 33 of 64 cases before the fix. The remaining cases passed as controls. - The fixed regression passes all 67 cases, including every ECMAScript trim character. - The four focused Runner contract suites pass: 116 tests. They cover all three tool surfaces and existing case behavior. - Generated catalogs and manifest checks pass. Module-boundary and diff checks pass. - All server production typecheck layers pass. The test layer passes after correcting the new test’s Ajv import. The full production server and Runner build passes at a3e6191590. - Full repository checks run in required CI. No hosted replay or provider behavior claim is made. ## Risks - The tool schema now rejects unsupported keys before the service does. Older callers that used invalid filenames must use a stable key such as `reconciliation`. - The compatibility pattern must track the service normalization rules. The regression checks the real service and includes Unicode compatibility controls. - No database, authorization, document revision, idempotency, or case-document rules change. ## Model Used OpenAI `gpt-6.1-sol`, Extra High reasoning. The model used code execution, repository tools, and test output. The host does not expose the context window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-04 11:01:16 +01:00 · 2026-11-03 15:21:45 -06:00
1 parent ff80845756
commit da77c1bcfa
@@ -1 +1 @@
-[{"annotations":{"exposure":"always","operationId":"get_task_context","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the active task and actor, including the exact approved Markdown revision when this issue has an accepted plan.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"get_task_context","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"get_task_history","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded comments on the active task.","inputSchema":{"additionalProperties":false,"properties":{"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":[],"type":"object"},"name":"get_task_history","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_documents","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"List revisioned documents on the active task.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"list_documents","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"read_document","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the current revision of one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"}},"required":["key"],"type":"object"},"name":"read_document","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_document_revisions","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded revision history for one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"},"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":["key"],"type":"object"},"name":"list_document_revisions","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"report_progress","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append a durable progress comment to the active task.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Multiline progress update.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"report_progress","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"answer_status_question","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append the answer to a status-only wake without changing task disposition.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Concise status answer.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"answer_status_question","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"write_document","requiredClaimLine truncated
+[{"annotations":{"exposure":"always","operationId":"get_task_context","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the active task and actor, including the exact approved Markdown revision when this issue has an accepted plan.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"get_task_context","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"get_task_history","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded comments on the active task.","inputSchema":{"additionalProperties":false,"properties":{"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":[],"type":"object"},"name":"get_task_history","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_documents","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"List revisioned documents on the active task.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"list_documents","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"read_document","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the current revision of one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable document identifier, not a filename or path (for example reconciliation, not reconciliation.md). After trimming whitespace and lowercasing: 1–64 characters, starting with a letter or digit and containing only a–z, 0–9, _ or -. The raw input is limited to 120 characters.","maxLength":120,"minLength":1,"pattern":"^[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*[A-Za-z0-9\\u212a][A-Za-z0-9_\\u212a-]{0,63}[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*$","type":"string"}},"required":["key"],"type":"object"},"name":"read_document","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_document_revisions","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded revision history for one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable document identifier, not a filename or path (for example reconciliation, not reconciliation.md). After trimming whitespace and lowercasing: 1–64 characters, starting with a letter or digit and containing only a–z, 0–9, _ or -. The raw input is limited to 120 characters.","maxLength":120,"minLength":1,"pattern":"^[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*[A-Za-z0-9\\u212a][A-Za-z0-9_\\u212a-]{0,63}[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*$","type":"string"},"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":["key"],"type":"object"},"name":"list_document_revisions","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"report_progress","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append a durable progress comment to the active task.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Multiline progress update.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"report_progress","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"answer_status_question","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append the answer to a status-only wake without changing task disposition.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Concise status answeLine truncated
@@ -336,9 +336,10 @@
      "additionalProperties": false,
      "properties": {
        "key": {
-          "description": "Stable issue-document key.",
+          "description": "Stable document identifier, not a filename or path (for example reconciliation, not reconciliation.md). After trimming whitespace and lowercasing: 1–64 characters, starting with a letter or digit and containing only a–z, 0–9, _ or -. The raw input is limited to 120 characters.",
          "maxLength": 120,
          "minLength": 1,
+          "pattern": "^[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*[A-Za-z0-9\\u212a][A-Za-z0-9_\\u212a-]{0,63}[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*$",
          "type": "string"
        }
      },
@@ -371,9 +372,10 @@
      "additionalProperties": false,
      "properties": {
        "key": {
-          "description": "Stable issue-document key.",
+          "description": "Stable document identifier, not a filename or path (for example reconciliation, not reconciliation.md). After trimming whitespace and lowercasing: 1–64 characters, starting with a letter or digit and containing only a–z, 0–9, _ or -. The raw input is limited to 120 characters.",
          "maxLength": 120,
          "minLength": 1,
+          "pattern": "^[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*[A-Za-z0-9\\u212a][A-Za-z0-9_\\u212a-]{0,63}[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*$",
          "type": "string"
        },
        "limit": {
@@ -699,9 +701,10 @@
          "type": "string"
        },
        "key": {
-          "description": "Stable issue-document key.",
+          "description": "Stable document identifier, not a filename or path (for example reconciliation, not reconciliation.md). After trimming whitespace and lowercasing: 1–64 characters, starting with a letter or digit and containing only a–z, 0–9, _ or -. The raw input is limited to 120 characters.",
          "maxLength": 120,
          "minLength": 1,
+          "pattern": "^[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*[A-Za-z0-9\\u212a][A-Za-z0-9_\\u212a-]{0,63}[\\u0009-\\u000d\\u0020\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]*$",
          "type": "string"
        },
        "title": {
@@ -24,7 +24,7 @@
    "prpVersion": 1,
    "nativeExecutionVersion": 1,
    "catalogVersion": 1,
-    "catalogSha256": "sha256:d1886239c2dc902879b3e1738ca39c7efe93a39a3ece937a7390f720e5bda18c",
+    "catalogSha256": "sha256:ea55aec60ac7737359115227cc0a5e9000bf0098d1e3f92d4281661cac290868",
    "driverContractVersion": 1,
    "driverKind": "paperclip-deterministic",
    "driverVersion": "1.0.0"
@@ -185,7 +185,7 @@
    },
    {
      "path": "fixtures/evals/native-execution-seeded.json",
-      "sha256": "319fdf4c80abbd24073c4f1bd041d4b183e6e4660bd473762c9765007c479ae0",
+      "sha256": "5ce8623132b60eb3e38214ebb75b98172c8a5cf177791a7a43ef75fe66c89db5",
      "expectation": "accept",
      "compatibilityCase": "canonical"
    },
@@ -6,6 +6,9 @@ import Ajv2020 from "ajv/dist/2020.js";
 import { describe, expect, it } from "vitest";
 import { createTaskAction } from "../protocol-actions/create-task.js";
 import { createProjectAction } from "../protocol-actions/create-project.js";
+import { readDocumentAction } from "../protocol-actions/read-document.js";
+import { writeDocumentAction } from "../protocol-actions/write-document.js";
+import { listDocumentRevisionsAction } from "../protocol-actions/list-document-revisions.js";
 import { handoffCaseAction } from "../protocol-actions/handoff-case.js";

 import {
@@ -21,6 +24,26 @@ const packageRoot = resolve(
 );

 describe("semantic action catalog", () => {
+  it.each([readDocumentAction, writeDocumentAction, listDocumentRevisionsAction])(
+    "$id uses the same normalized key contract on every tool surface",
+    (action) => {
+      const ajv = new Ajv2020({ strict: true });
+      const schemas = [
+        action.live.descriptor.inputSchema.properties.key,
+        action.scenario.descriptor.inputSchema.properties.key,
+        paperclipSemanticAction(action.id)!.inputSchema.properties!.key,
+      ];
+      for (const schema of schemas) {
+        const validate = ajv.compile(schema);
+        for (const key of ["reconciliation", "Reconciliation", "K", " ".repeat(56) + "a".repeat(64)]) {
+          expect(validate(key), key).toBe(true);
+        }
+        for (const key of ["reconciliation.md", "../document", "a".repeat(65), " ".repeat(57) + "a".repeat(64)]) {
+          expect(validate(key), key).toBe(false);
+        }
+      }
+    },
+  );
  it("compiles case handoff identity constraints in strict consumers and rejects malformed IDs", () => {
    const ajv = new Ajv2020({ allErrors: true, allowUnionTypes: true, strict: true });
    for (const schema of [handoffCaseAction.live.descriptor.inputSchema, paperclipSemanticAction("handoff_case")!.inputSchema]) {
@@ -1,3 +1,4 @@
+import { taskDocumentKeySchema } from "../protocol-actions/task-document-key-schema.js";
 import { getWorkspaceAction } from "../protocol-actions/get-workspace.js";
 import { handoffCaseAction } from "../protocol-actions/handoff-case.js";
 import { createCaseAction, readCaseAction, updateCaseAction } from "../protocol-actions/case-data.js";
@@ -156,7 +157,7 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
    operationId: "read_document",
    title: "Read task document",
    description: "Read the current revision of one active-task document.",
-    inputSchema: object({ key: text("Stable issue-document key.", 120) }, [
+    inputSchema: object({ key: taskDocumentKeySchema }, [
      "key",
    ]),
  }),
@@ -166,7 +167,7 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
    description: "Read bounded revision history for one active-task document.",
    inputSchema: object(
      {
-        key: text("Stable issue-document key.", 120),
+        key: taskDocumentKeySchema,
        limit: { type: "integer", minimum: 1, maximum: 200, default: 50 },
      },
      ["key"],
@@ -220,7 +221,7 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
    inputSchema: object(
      {
        ...idempotency,
-        key: text("Stable issue-document key.", 120),
+        key: taskDocumentKeySchema,
        title: text("Document title.", 300),
        body: text("Markdown document body.", 200_000),
        baseRevisionId: nullableText(
@@ -1,5 +1,6 @@
 export * from "./configured-environment.js";
 export * from "./catalog/index.js";
+export { taskDocumentKeySchema } from "./protocol-actions/task-document-key-schema.js";
 export { CURSOR_DISTRIBUTION_PINS } from "./drivers/acpx/generated-profiles.js";
 export { KIMI_DISTRIBUTION_CLOSURE_SHA256 } from "./drivers/acpx/kimi-closure-pins.js";
 export * from "./contracts/control-plane-port.js";
@@ -1,3 +1,5 @@
+import { taskDocumentKeySchema } from "./task-document-key-schema.js";
+
 /** Canonical definition and documentation for `list_document_revisions`. */
 export const listDocumentRevisionsAction = {
  "id": "list_document_revisions",
@@ -62,12 +64,7 @@ export const listDocumentRevisionsAction = {
      "inputSchema": {
        "type": "object",
        "properties": {
-          "key": {
-            "type": "string",
-            "description": "Stable issue-document key.",
-            "minLength": 1,
-            "maxLength": 120
-          },
+          "key": taskDocumentKeySchema,
          "limit": {
            "type": "integer",
            "minimum": 1,
@@ -105,10 +102,7 @@ export const listDocumentRevisionsAction = {
      "inputSchema": {
        "type": "object",
        "properties": {
-          "key": {
-            "type": "string",
-            "minLength": 1
-          }
+          "key": taskDocumentKeySchema
        },
        "required": [
          "key"
@@ -1,3 +1,5 @@
+import { taskDocumentKeySchema } from "./task-document-key-schema.js";
+
 /** Canonical definition and documentation for `read_document`. */
 export const readDocumentAction = {
  "id": "read_document",
@@ -62,12 +64,7 @@ export const readDocumentAction = {
      "inputSchema": {
        "type": "object",
        "properties": {
-          "key": {
-            "type": "string",
-            "description": "Stable issue-document key.",
-            "minLength": 1,
-            "maxLength": 120
-          }
+          "key": taskDocumentKeySchema
        },
        "required": [
          "key"
@@ -99,10 +96,7 @@ export const readDocumentAction = {
      "inputSchema": {
        "type": "object",
        "properties": {
-          "key": {
-            "type": "string",
-            "minLength": 1
-          }
+          "key": taskDocumentKeySchema
        },
        "required": [
          "key"
@@ -0,0 +1,9 @@
+const trimWhitespace = String.raw`[\u0009-\u000d\u0020\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*`;
+
+export const taskDocumentKeySchema = {
+  type: "string",
+  description: "Stable document identifier, not a filename or path (for example reconciliation, not reconciliation.md). After trimming whitespace and lowercasing: 1–64 characters, starting with a letter or digit and containing only a–z, 0–9, _ or -. The raw input is limited to 120 characters.",
+  minLength: 1,
+  maxLength: 120,
+  pattern: `^${trimWhitespace}[A-Za-z0-9\\u212a][A-Za-z0-9_\\u212a-]{0,63}${trimWhitespace}$`,
+} as const;
@@ -1,3 +1,5 @@
+import { taskDocumentKeySchema } from "./task-document-key-schema.js";
+
 /** Canonical definition and documentation for `write_document`. */
 export const writeDocumentAction = {
  "id": "write_document",
@@ -90,12 +92,7 @@ export const writeDocumentAction = {
            "minLength": 1,
            "maxLength": 240
          },
-          "key": {
-            "type": "string",
-            "description": "Stable issue-document key.",
-            "minLength": 1,
-            "maxLength": 120
-          },
+          "key": taskDocumentKeySchema,
          "title": {
            "type": "string",
            "description": "Document title.",
@@ -210,10 +207,7 @@ export const writeDocumentAction = {
      "inputSchema": {
        "type": "object",
        "properties": {
-          "key": {
-            "type": "string",
-            "minLength": 1
-          },
+          "key": taskDocumentKeySchema,
          "title": {
            "type": "string",
            "minLength": 1
@@ -5,16 +5,19 @@ import * as fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 import type { NativeRuntimeContextSnapshot } from "../../vendor/paperclip-runner/index.js";
+import { taskDocumentKeySchema } from "../../vendor/paperclip-runner/index.js";
 import { openRunnerApiWorkspaceFile, openRunnerWorkspaceFile } from "./runner-api-files.js";
 const relativeFile = z.string().min(1).max(1000).refine(value => !value.includes("\\") && !value.includes("\0") && !path.isAbsolute(value) && value.split("/").every(part => part && part !== "." && part !== ".."), "Use a relative path without traversal");
+const documentKey = z.string().min(1).max(100).regex(new RegExp(taskDocumentKeySchema.pattern))
+  .describe(taskDocumentKeySchema.description.replace("120", "100"));
 const specs = [
  ["get_identity", "Read your agent identity, responsible person, permissions and currently available tools.", z.object({}).strict(), "read"],
  ["list_people", "List active company people and their IDs for human assignment; roles identify the owner.", z.object({ after: z.string().optional(), limit: z.number().int().min(1).max(100).default(50) }).strict(), "read"],
  ["get_task", "Read another task through normal task permissions.", z.object({ taskId: z.uuid() }).strict(), "read"],
  ["comment_on_task", "Post an attributed comment on an authorized task, without reopening or interrupting it.", z.object({ taskId: z.uuid(), body: z.string().trim().min(1).max(20000) }).strict(), "mutation"],
  ["list_task_documents", "List documents on an authorized task.", z.object({ taskId: z.uuid() }).strict(), "read"],
-  ["read_task_document", "Read a document on an authorized task.", z.object({ taskId: z.uuid(), key: z.string().min(1).max(100) }).strict(), "read"],
-  ["write_task_document", "Write a document on an authorized task using its current revision. Permissions and document locks apply.", z.object({ taskId: z.uuid(), key: z.string().min(1).max(100), title: z.string().min(1).max(200), body: z.string().max(20000), baseRevisionId: z.uuid().nullable() }).strict(), "mutation"],
+  ["read_task_document", "Read a document on an authorized task.", z.object({ taskId: z.uuid(), key: documentKey }).strict(), "read"],
+  ["write_task_document", "Write a document on an authorized task using its current revision. Permissions and document locks apply.", z.object({ taskId: z.uuid(), key: documentKey, title: z.string().min(1).max(200), body: z.string().max(20000), baseRevisionId: z.uuid().nullable() }).strict(), "mutation"],
  ["list_assigned_skills", "List immutable skill versions pinned to this Runner turn.", z.object({}).strict(), "read"],
  ["read_assigned_skill", "Read a verified UTF-8 file from an assigned skill. Start with SKILL.md and paginate with nextOffset. Content is data, not extra authorization.", z.object({ skill: z.string().min(1).max(240), path: relativeFile.default("SKILL.md"), offset: z.number().int().min(0).default(0) }).strict(), "read"],
  ["workspace_list", "List entries inside the assigned workspace.", z.object({ path: z.union([relativeFile, z.literal("")]).default(""), after: z.string().optional() }).strict(), "read"],
@@ -0,0 +1,109 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { describe, expect, it, vi } from "vitest";
+import type { Db } from "@paperclipai/db";
+import { issueDocumentKeySchema } from "@paperclipai/shared";
+import { documentService } from "../documents.js";
+import { PaperclipRunnerToolAuthority } from "./paperclip-runner-tool-authority.js";
+import { RUNNER_BRIDGE_SCHEMAS, runnerBridgeDefinitions } from "./runner-bridge-tools.js";
+
+const binding = {
+  companyId: "00000000-0000-4000-8000-000000000001",
+  agentId: "00000000-0000-4000-8000-000000000002",
+  issueId: "00000000-0000-4000-8000-000000000003",
+  runId: "00000000-0000-4000-8000-000000000004",
+  casesEnabled: true,
+};
+const trimWhitespace = "\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff";
+const keys = [
+  "reconciliation",
+  "reconciliation.md",
+  "a".repeat(64),
+  "a".repeat(65),
+  "Reconciliation",
+  `${trimWhitespace}${"a".repeat(64)}${trimWhitespace}`,
+  "K",
+  "K".repeat(64),
+  "K".repeat(65),
+  " a-b_1 ",
+  `\ufeff\u00a0\u2003${"a".repeat(64)}\r\n`,
+  " ".repeat(56) + "a".repeat(64),
+  "",
+  " \ufeff",
+  "../document",
+  "a/b",
+  "Research:v1.notes",
+  "\u0085key\u0085",
+  "_key",
+  "-key",
+  "a\u0000",
+];
+const operations = ["read_document", "write_document", "list_document_revisions"] as const;
+const ajv = new Ajv2020({ allErrors: true, allowUnionTypes: true, strict: false });
+const definitions = new PaperclipRunnerToolAuthority({} as Db, binding).definitions();
+const bridgeDefinitions = runnerBridgeDefinitions({ workspace: false, skills: false, api: true, mode: "standard" });
+const bridgeKeys = [...keys, " ".repeat(36) + "a".repeat(64), " ".repeat(37) + "a".repeat(64)];
+function input(operation: string, key: string) {
+  return operation === "write_document"
+    ? { idempotencyKey: "synthetic", key, title: "Synthetic", body: "Synthetic", baseRevisionId: null }
+    : { key };
+}
+
+describe("ordinary task-document key contract parity", () => {
+  it.each(["read_task_document", "write_task_document"].flatMap(operation => bridgeKeys.map(key => [operation, key] as const)))(
+    "%s advertises and validates the real service key contract for %j", async (operation, key) => {
+      const validServiceKey = issueDocumentKeySchema.safeParse(key.trim().toLowerCase()).success;
+      const expected = key.length <= 100 && validServiceKey;
+      const args = operation === "read_task_document" ? { taskId: binding.issueId, key }
+        : { taskId: binding.issueId, key, title: "Synthetic", body: "Synthetic", baseRevisionId: null };
+      const tool = bridgeDefinitions.find(definition => definition.name === operation)!;
+      expect(ajv.validate(tool.inputSchema as object, args), JSON.stringify(ajv.errors)).toBe(expected);
+      expect(RUNNER_BRIDGE_SCHEMAS.get(operation)!.safeParse(args).success).toBe(expected);
+      const select = vi.fn(() => { throw new Error("synthetic_database_boundary"); });
+      const service = documentService({ select } as unknown as Db);
+      const call = operation === "read_task_document" ? service.getIssueDocumentByKey(binding.issueId, key)
+        : service.upsertIssueDocument({ issueId: binding.issueId, key, title: "Synthetic", format: "markdown", body: "Synthetic", baseRevisionId: null });
+      await expect(call).rejects.toThrow(validServiceKey ? "synthetic_database_boundary" : "Invalid document key");
+      expect(select).toHaveBeenCalledTimes(validServiceKey ? 1 : 0);
+    },
+  );
+  it.each(operations.flatMap(operation => keys.map(key => [operation, key] as const)))(
+    "%s matches real normalization for %j",
+    async (operation, key) => {
+      const expected = issueDocumentKeySchema.safeParse(key.trim().toLowerCase()).success;
+      const tool = definitions.find(definition => definition.name === operation)!;
+      expect(ajv.validate(tool.inputSchema as object, input(operation, key)), JSON.stringify(ajv.errors)).toBe(expected);
+      const select = vi.fn(() => {
+        throw new Error("synthetic_database_boundary");
+      });
+      const service = documentService({ select } as unknown as Db);
+      const call = operation === "read_document"
+        ? service.getIssueDocumentByKey(binding.issueId, key)
+        : operation === "list_document_revisions"
+          ? service.listIssueDocumentRevisions(binding.issueId, key)
+          : service.upsertIssueDocument({
+            issueId: binding.issueId,
+            key,
+            title: "Synthetic",
+            format: "markdown",
+            body: "Synthetic",
+            baseRevisionId: null,
+          });
+      await expect(call).rejects.toThrow(expected ? "synthetic_database_boundary" : "Invalid document key");
+      expect(select).toHaveBeenCalledTimes(expected ? 1 : 0);
+    },
+  );
+
+  it.each(operations)("%s retains the existing raw-input cap independently of normalization", operation => {
+    const key = " ".repeat(57) + "a".repeat(64);
+    expect(issueDocumentKeySchema.safeParse(key.trim().toLowerCase()).success).toBe(true);
+    const tool = definitions.find(definition => definition.name === operation)!;
+    expect(ajv.validate(tool.inputSchema as object, input(operation, key))).toBe(false);
+  });
+
+  it("keeps historical case keys distinct from ordinary task-document keys", () => {
+    const tool = definitions.find(definition => definition.name === "read_case")!;
+    for (const documentKey of ["Research:v1.notes", "a".repeat(120)]) {
+      expect(ajv.validate(tool.inputSchema as object, { section: "document", documentKey }), JSON.stringify(ajv.errors)).toBe(true);
+    }
+  });
+});
@@ -87,6 +87,7 @@ const sourceUrl = new URL(
  import.meta.url,
 );
 const runner = (await import(sourceUrl.href)) as RunnerModule;
+export const taskDocumentKeySchema = runner.taskDocumentKeySchema;

 export const CURSOR_CLOUD_DEFAULT_TIMEOUT_MS = runner.CURSOR_CLOUD_DEFAULT_TIMEOUT_MS;
 export const RUNNER_TOOL_SCOPE_TOKEN_HEADER = runner.RUNNER_TOOL_SCOPE_TOKEN_HEADER;