@supernovae-st/nika 0.120.2 → 0.120.3

package/docs/http-api.md

@@ -15,6 +15,7 @@ Any other non-2xx body is discarded and reported as a redacted
 | `GET /v1/openapi.json` | generation only | authenticated OpenAPI 3.1 document |
 | `GET /v1/workflows` | `listWorkflows()` | contained relative workflow names |
 | `GET /v1/workflows/{name}` | `workflow(name)` | path-free metadata, never source bytes |
+| `POST /v1/compile` | `compile()` | capability-gated stateless source authoring; 200 ready/incomplete/refused, no job |
 | `POST /v1/check` | `check()` | validates a served name or immutable snapshot bytes without a job |
 | `POST /v1/jobs` | `run()` | admits a served name or exact snapshot bytes with an idempotency key |
 | `GET /v1/jobs/{id}` | internal settlement | durable job identity, outputs, receipt, settlement, or redacted error |
@@ -58,6 +59,29 @@ engine. Prefix a local file with `./` to capture and submit its snapshot.
 A successful by-name check returns `clean: true` and the compact resident
 acknowledgement; no local check report or exit code is fabricated.
 
+## Compile foundation
+
+Serve must advertise `compile` in `/health`. This route was added in engine
+commit `4334e58bddf539a6253f448eb05d562b6919f2b7`, after release 0.120.2, and
+first published in release 0.120.3.
+The bundled OpenAPI and generated types preserve that exact producer contract. The SDK then posts a v1 create
+intent or inline edit source to `/v1/compile`, with bearer authentication and
+JSON content type. A string change becomes `{text: change}`; a structured change
+preserves `{set_constant: {name, value}}`. Literal answers retain their JSON
+types. There is no path, destination, idempotency key or local fallback.
+
+Every core outcome uses HTTP 200. `incomplete` and `refused` remain reviewable
+data; non-200 error envelopes raise `NikaOperationError` with the HTTP status
+and engine code. Bad versions, malformed outcomes, overflow, cancellation and
+timeout fail typed. The response is bounded by the smaller of
+`machineBufferBytes` and 8 MiB. Compile's timeout covers health negotiation,
+response headers and the complete body.
+
+The shared outcome contains candidate source, questions, diagnostics, requested
+boundary, source-only Check preview and provenance. It carries no process exit
+code or materialized destination. A candidate and its requested boundary grant
+nothing: execution needs a separate caller decision and normal `run` admission.
+
 ## Settlement
 
 The terminal `execution.settled` frame and the durable job nest the run's

package/docs/testing.md

@@ -179,3 +179,40 @@ cleanup before emitting green evidence. The corpus runs in a fresh project and
 HOME. Changed fixtures require new measured results: old committed ledgers
 remain historical observations until a successful exact-version replay replaces
 them. Never relabel an old binary or weaken the replay comparison.
+
+## Compile foundation parity
+
+Hermetic compile cases run with `npm test`, including strict request literals,
+capability/version refusal, native exit and signal laws, temporary-file failure
+cleanup, authenticated HTTP responses and cancellation. `npm run check:package-surface`
+checks both packed module faces and their public TypeScript contracts.
+
+For a frozen engine that advertises `compile` on both native and Serve doors:
+
+```sh
+NIKA_BIN=/absolute/path/to/frozen/nika \
+NIKA_COMPILE_PARITY_REPORT=/absolute/path/to/compile-parity.json \
+node scripts/run-compile-parity-e2e.mjs
+```
+
+This installs the SDK tarball into an isolated consumer and compares the full
+common authoring outcomes across native/HTTP and ESM/CommonJS. It checks literal
+round trips, incomplete questions, refused expression islands, invalid bases,
+authentication, no project-file changes and no created jobs. HTTP is given a
+nonexistent local engine path, proving that it cannot use a fallback. The report
+records binary and package hashes and is green only after owned-process cleanup.
+A source binary containing engine commit
+`4334e58bddf539a6253f448eb05d562b6919f2b7` is required for both doors.
+Released engine 0.120.3 supports native compile and its Serve advertises HTTP
+compile; 0.120.2 and older predate the route. This is a foundation test, not general intent authoring
+or execution admission qualification.
+
+The [2026-09-19 source-build receipt](../evidence/compile-4334e58b-20260919.json)
+records 14 cases across both doors and both module systems at that producer,
+with exact outcome parity and no resident-state or project-file mutation. Its
+engine is a clean source build predating the published v0.120.3 binary; its SDK
+tarball is the unreleased PR candidate. The hashes identify those tested bytes.
+
+Compile source-build receipts live outside the published package, so recording
+a tarball hash does not change the bytes it identifies. They do not participate
+in the released-engine behavioral ledgers.

package/openapi.json

@@ -61,6 +61,246 @@
         ],
         "type": "object"
       },
+      "CompileOutcome": {
+        "description": "The engine-owned machine document of one authoring result — the document `nika compile --json` prints, without the CLI-only `written`. No field grants authority, writes or executes source.",
+        "properties": {
+          "candidate": {
+            "description": "Ordinary `.nika` source; may still be incomplete",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "check_preview": {
+            "description": "The engine's pure Check report over the source only. No child file, skill, credential probe, access plan or admission was evaluated",
+            "properties": {
+              "report": {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              "scope": {
+                "const": "sourceOnly",
+                "type": "string"
+              }
+            },
+            "required": [
+              "scope",
+              "report"
+            ],
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "compile_version": {
+            "const": 1,
+            "type": "integer"
+          },
+          "diagnostics": {
+            "items": {
+              "properties": {
+                "kind": {
+                  "enum": [
+                    "applied",
+                    "missed",
+                    "unknown",
+                    "requiresHuman",
+                    "refused"
+                  ],
+                  "type": "string"
+                },
+                "message": {
+                  "description": "For a reader; never parsed to recover compiler state",
+                  "type": "string"
+                },
+                "target": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "kind",
+                "target",
+                "message"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "provenance": {
+            "description": "Reproduction metadata; neither program identity nor run evidence",
+            "properties": {
+              "cognition": {
+                "const": "deterministicOnly",
+                "type": "string"
+              },
+              "compiler_version": {
+                "type": "string"
+              },
+              "skeleton": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "spec_pin": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "compiler_version",
+              "spec_pin",
+              "skeleton",
+              "cognition"
+            ],
+            "type": "object"
+          },
+          "questions": {
+            "items": {
+              "properties": {
+                "key": {
+                  "description": "Stable semantic hole path such as `const.request`, never a session id",
+                  "type": "string"
+                },
+                "label": {
+                  "type": "string"
+                },
+                "mandatory": {
+                  "type": "boolean"
+                },
+                "type": {
+                  "enum": [
+                    "text",
+                    "literal"
+                  ],
+                  "type": "string"
+                },
+                "why": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "key",
+                "label",
+                "type",
+                "why",
+                "mandatory"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "requested_boundary": {
+            "additionalProperties": true,
+            "description": "The candidate's requested permits, derived by Check. Requested, never granted",
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "status": {
+            "description": "Completeness of authoring, never permission to execute",
+            "enum": [
+              "ready",
+              "incomplete",
+              "refused"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "compile_version",
+          "status",
+          "candidate",
+          "questions",
+          "diagnostics",
+          "requested_boundary",
+          "check_preview",
+          "provenance"
+        ],
+        "type": "object"
+      },
+      "CompileRequest": {
+        "additionalProperties": false,
+        "description": "Generation 1 of the compile request. The encoded body is limited to 1048576 bytes (or the listener's lower ceiling). Byte bounds below are UTF-8 bytes. Unknown fields, a present null, duplicate keys (including inside `answers`) and positional arrays are refused. No field names a host path: an EDIT base travels inline in `source`.",
+        "properties": {
+          "answers": {
+            "additionalProperties": true,
+            "description": "Question key → one JSON literal with its type preserved, judged exactly as sent (at most 65536 bytes each)",
+            "maxProperties": 64,
+            "propertyNames": {
+              "maxLength": 256
+            },
+            "type": "object"
+          },
+          "change": {
+            "additionalProperties": false,
+            "maxProperties": 1,
+            "minProperties": 1,
+            "properties": {
+              "set_constant": {
+                "additionalProperties": false,
+                "properties": {
+                  "name": {
+                    "description": "Bare constant name, not a path",
+                    "maxLength": 128,
+                    "type": "string"
+                  },
+                  "value": {
+                    "description": "One JSON literal, judged exactly as sent (at most 65536 bytes)"
+                  }
+                },
+                "required": [
+                  "name",
+                  "value"
+                ],
+                "type": "object"
+              },
+              "text": {
+                "description": "`Set const.NAME to JSON_LITERAL`, or `Set const.NAME` answered through `answers`",
+                "maxLength": 4096,
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "cognition": {
+            "const": "deterministicOnly",
+            "description": "The only authoring cognition of this build. Any other value is refused; no authoring model is contacted",
+            "type": "string"
+          },
+          "compile_version": {
+            "const": 1,
+            "type": "integer"
+          },
+          "intent": {
+            "maxLength": 4096,
+            "type": "string"
+          },
+          "mode": {
+            "description": "create requires `intent` and forbids `source`/`change`; edit requires `source` and `change` and forbids `intent`",
+            "enum": [
+              "create",
+              "edit"
+            ],
+            "type": "string"
+          },
+          "source": {
+            "description": "Accepted `.nika` source, inline. The caller owns source selection, revision checks and materialization",
+            "maxLength": 524288,
+            "type": "string"
+          },
+          "workflow_id": {
+            "description": "Names a created workflow. On edit the core refuses it as data: an edit cannot rename its accepted base",
+            "maxLength": 128,
+            "type": "string"
+          }
+        },
+        "required": [
+          "compile_version",
+          "mode"
+        ],
+        "type": "object"
+      },
       "Error": {
         "additionalProperties": false,
         "properties": {
@@ -1012,9 +1252,9 @@
     }
   },
   "info": {
-    "description": "Authenticated loopback remote execution and declarative schedules. Artifacts, schedule list/delete/trigger/backfill, /v1/arm, and POST /v1/run are absent.",
+    "description": "Authenticated loopback remote execution, declarative schedules and stateless source-only authoring (POST /v1/compile never runs, admits or writes). Artifacts, schedule list/delete/trigger/backfill, /v1/arm, and POST /v1/run are absent.",
     "title": "nika serve",
-    "version": "0.120.2"
+    "version": "0.120.3"
   },
   "openapi": "3.1.0",
   "paths": {
@@ -1121,6 +1361,104 @@
         "summary": "Judge a workflow without creating a job — by served name, or as immutable snapshot bytes"
       }
     },
+    "/v1/compile": {
+      "post": {
+        "description": "The HTTP transport of the same Compile core as `nika compile`. Foundation scope: CREATE resolves an exact embedded skeleton name (or `hello`), EDIT changes one existing constant, answers are explicit JSON literals; any other intent is answered `incomplete` with no substitute workflow. Creates no job, run, approval or trace, writes no file, contacts no provider: ambient keys are never consent. `check_preview` is a REVIEW of the source only, never admission: POST /v1/jobs judges a candidate again. Questions carry stable keys; answering is a new request, not a session.",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CompileRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CompileOutcome"
+                }
+              }
+            },
+            "description": "Authoring outcome — ready, incomplete and refused are all data"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Error envelope"
+          },
+          "408": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Request deadline"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Encoded body above the compile ceiling"
+          },
+          "415": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Content-Type or Content-Encoding refused"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "malformed_compile_request · compile_version_unsupported · compile_mode_unsupported · compile_cognition_unsupported · compile_limit"
+          },
+          "500": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "Compiler machinery failure; nothing is echoed"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            },
+            "description": "compile_busy — every compile slot is in use"
+          }
+        },
+        "summary": "Author a candidate workflow without running it (stateless · source-only)"
+      }
+    },
     "/v1/jobs": {
       "post": {
         "description": "Two forms, one admission (ADR-131). `{\"workflow\": \"<name>\"}` names a workflow the served registry lists: the resident captures its world through ExecutionService, exactly as a schedule does. Optional `access` on that form is CLI `--access` for this job only. A snapshot body is the world `nika check <file> --json --sdk-snapshot` prints, decoded and readmitted through the same ExecutionService; its digests are optional caller-supplied integrity digests (a content assertion, never a signature). Snapshot jobs inherit the resident's unpinned plan. The server never interprets a caller filesystem path. Idempotency binds to the exact request bytes.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernovae-st/nika",
-  "version": "0.120.2",
+  "version": "0.120.3",
   "description": "One TypeScript SDK for local and remote Nika execution",
   "repository": {
     "type": "git",
@@ -69,10 +69,10 @@
     "prepublishOnly": "npm run build"
   },
   "optionalDependencies": {
-    "@supernovae-st/nika-darwin-arm64": "0.120.2",
-    "@supernovae-st/nika-darwin-x64": "0.120.2",
-    "@supernovae-st/nika-linux-arm64": "0.120.2",
-    "@supernovae-st/nika-linux-x64": "0.120.2"
+    "@supernovae-st/nika-darwin-arm64": "0.120.3",
+    "@supernovae-st/nika-darwin-x64": "0.120.3",
+    "@supernovae-st/nika-linux-arm64": "0.120.3",
+    "@supernovae-st/nika-linux-x64": "0.120.3"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",
@@ -87,7 +87,7 @@
   "license": "Apache-2.0",
   "mcpName": "io.github.supernovae-st/nika",
   "nikaRelease": {
-    "preparedCommit": "ddf7522cac40e9606a7d94e83af74234e066a96e",
-    "version": "0.120.2"
+    "preparedCommit": "4dcda1bacfc1cc77c87066784120151a67202033",
+    "version": "0.120.3"
   }
 }