@polycrest/document-service

Headless HTTP host for @polycrest/document-core — the source of truth in server-authoritative document editing. A stateless shell over the engine: every request carries the document; the service never invents behavior, it only calls normalizeChangeSet / applyChangeSetToDocument / validateChangeSet / createAgentContext / getOutline / searchDocument.

Zero runtime dependencies beyond document-core (Node built-in http). Binds to 127.0.0.1 only — this is an in-machine engine host, not a web API.

Run

node dist/server.js --port 5211 [--automation]
# or via the bin: polycrest-document-service --port 5211

• --port <n> (or PORT env) — default 5211.
• --automation — deterministic seeded IDs. The seed starts at 1000 so service-minted IDs never collide with a browser-side seeded generator minting from 1 (the harness under ?automation=1).

A ready line is printed once listening: [document-service] ready on http://127.0.0.1:<port> engine=<version> automation=<bool>

Endpoints (all JSON)

| Route | Request | Response | | --- | --- | --- | | POST /apply | {document, changeSet} | {document, result, normalizedChangeSet} | | POST /validate | {document, changeSet} | {valid, conflicts} | | POST /agent-context | {document, request?} | AgentDocumentContext | | GET\|POST /outline | {document} | OutlineEntry[] | | GET\|POST /search | {document, query, roles?, limit?} (?q= also accepted) | SearchResult[] | | GET /health | — | {ok, engineVersion} |

Contract rules:

• Normalize once (hard rule #5). /apply normalizes the change set exactly once and returns the normalized set so a mirror (the browser editor) replays the identical set without re-minting. The change-set id is minted server-side when omitted.
• Conflicts are data, not HTTP errors. A rejected apply returns 200 with result.applied === false and typed DocumentConflict[]. HTTP 400 means the request itself was malformed; 500 an unexpected fault.
• engineVersion is the resolved document-core version — consumers (the .NET DocumentServiceProcess launcher) pin against it and fail fast on mismatch.
• Determinism. No wall-clock ever appears in responses; under --automation every response is reproducible for identical request sequences.

Consumers

• dotnet/Polycrest.Document.ServiceClient — typed C# client + process launcher/supervisor (spawn via Node, /health poll, version pin).
• dotnet/Polycrest.Document.Mcp — the MCP collaborative-editing host.