@telorun/starlark 0.4.1 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @telorun/starlark
 
+## 0.5.0
+
+### Minor Changes
+
+- 2ee3598: A resource's declared invocation contract is now enforced.
+
+  `inputType` / `outputType` were declared all over the standard library and read almost nowhere: a declared `default:` never applied, a misspelled input, a wrong-typed value and a misread result field were all silent, and three modules of roughly forty validated anything at all — each re-deciding it for itself. Underneath was a naming collision: `inputs:` meant _a schema_ on the six `modules/run` kinds and _values_ at every call site, so the run kinds' whole declared contract was inert.
+
+  One invariant now holds everywhere: **`inputs`/`outputs` are values; `inputType`/`outputType` are schemas.** The normative rules are in `kernel/specs/invocation-contract.md`.
+
+  **Resolution.** A shared resolver answers "what is this target's contract" for both halves — `telo check` and the runtime — layering the instance's own declaration over the kind's. A kind's contract resolves to the **nearest declaration along `extends`** and **replaces** rather than merges: config and observed state merge because construction and reported state are additive, but a call signature is not, and merging a child's required inputs into its parent's yields a union no caller can satisfy. This also fixes multi-level chains, which previously resolved to nothing.
+
+  A child that inherits its controller and declares its own contract must bridge it — `inputType` needs `inputs:`, `outputType` needs `result:` — because the inherited controller understands only the shape it was written for. That combination used to pass `telo check`, run, exit 0 and do nothing at all.
+
+  **Enforcement.** The kernel binds the resolved contract to the instance at creation, so **an instance is never observable unbound**. Enforcing at a handoff would have meant enforcing at every handoff — injection, explicit resolution, scope handles, template dispatch, the chokepoint — and the dominant path is injection: a consumer reads the reference off its own config and invokes it directly. `invoke` and `provide` are bound; `run()` is parameterless and void, so a resource whose contract requires inputs is rejected statically at a run site. Defaults are filled and both directions validated on every call, skipping `x-telo-stream` properties in **both** directions.
+
+  Violations raise the ambient `ERR_INPUT_INVALID` / `ERR_OUTPUT_INVALID` as structured errors: catchable and typo-checked by name in a `catches:` block, never counted toward a kind's own declared union. `JS.Script`, `Starlark.Script` and `Run.Choice` drop their controller-side validators, and `Run.Choice`'s duplicate `ERR_OUTPUT_INVALID` declaration goes with them; `Image.Blank`, `Image.Overlay`, `Pdf.Rasterizer` and `Pdf.FormFields` drop the input guards that duplicated their own declared bounds, keeping only what a schema cannot express (a CSS colour's validity, a PDF's decodability, a page against the document's real page count).
+
+  **`Telo.JsonSchema` is now a kernel built-in.** Declaring a data shape stopped being optional once any kind can carry a contract: writing `inputType:` should not require an import, and a library declaring its own contract should not import a module purely to describe itself — the same reasoning that keeps the mandatory log sinks in the kernel. `modules/type` is deprecated and unchanged, so `Type.JsonSchema` and every published manifest importing it keep working; the standard library, examples and templates now write the built-in and have dropped the import.
+
+  The six `modules/run` kinds declare `inputType:` / `outputType:` in place of the `inputs:` property map, and each result slot is annotated `x-telo-value-schema-from: outputType` so every branch is checked statically — including ones no input selects. Consumers in this repo are migrated; a manifest pinning a published `run` by digest keeps the old spelling and keeps working.
+
+  A `Telo.JsonSchema` rule's declared `code:` now reaches a `catch` block. Rules raise an error that carries a code but not the marker a catch matches on, so `error.code` was the generic plain-failure code and every `catches:` entry naming a rule code silently never matched — the behaviour `modules/type` has always documented was never the behaviour. Contract enforcement re-raises a rule failure structurally, preserving the author's code; only a structural schema failure becomes the ambient contract code.
+
+  CEL evaluates an integer literal to a BigInt, which a JSON Schema validator does not accept as `integer` — so with enforcement on, every computed integer reaching a declared integer input would have been rejected for a reason no author could act on. Validation runs against a view where those read as ordinary numbers while the callee still receives the original values, and `Assert.Equals` no longer throws while rendering one.
+
+  `Type.JsonSchema` is now a controller-less `extends: Telo.JsonSchema` alias rather than a second copy of the same controller, so the deprecated module has no implementation left to drift.
+
+  **Statically**, `telo check` now validates each call site's `inputs:` against the target's contract, rejects an unmapped contract replacement, rejects a contract-requiring resource wired where the caller cannot supply arguments, and rejects a contract naming a type that is not declared in scope — which the runtime would otherwise only discover at the first dispatch through it, and which was invisible on a KIND because `Telo.Definition` is excluded from ordinary reference validation.
+
+  Several latent bugs surfaced and are fixed. A wrapped `invoke` dropped every argument after the first, discarding the InvokeContext — so a detached body never observed cancellation and anything holding a resource across it was never released. `base:` validation demanded `metadata` and then rejected it, making any `base:` child of `JS.Script` impossible. The canonical type-schema id carried a URI authority (`telo://<module>/<Type>`), which no JSON Schema validator can resolve, so a `$ref`-based contract was uncompilable; the internal id is now authority-free, with the authored form unchanged.
+
+  CEL placeholder substitution — how the checker avoids judging a value it cannot know — gained the same discipline: bounds it ignored (`exclusiveMinimum`, `minLength`, `minItems`, `required`, `allOf`-inherited constraints) are now honoured, a `oneOf` / `anyOf` is resolved to the single branch a value is written against so leaves underneath are typed rather than nulled, and a finding located AT a substituted path is dropped outright — a `pattern`-constrained string cannot be satisfied by any stand-in, so the checker declines to judge it. Structural findings survive, because they are located at the container.
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -23,9 +23,9 @@ Built to be language-agnostic and infinitely extensible.
 
 ```bash
 # Reconcile your manifest into a running backend
-$ telo ./examples/hello-api.yaml
+$ telo ./examples/todo-app
 
-{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
+{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8077"}
 ```
 
 ## Why use Telo?
@@ -44,165 +44,13 @@ $ telo ./examples/hello-api.yaml
 
 ## Example manifest
 
-Here is an example Telo application that defines a simple HTTP API:
-
-```yaml
-kind: Telo.Application
-metadata:
-  name: feedback
-  version: 1.0.0
-  description: |
-    A complete feedback collection REST API — no code, pure YAML.
-    Persists entries to SQLite and serves them over HTTP.
-targets:
-  - Migrations
-  - Server
----
-kind: Telo.Import
-metadata:
-  name: Http
-source: std/http-server@0.5.0
----
-kind: Telo.Import
-metadata:
-  name: Sql
-source: std/sql@0.3.0
----
-# SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
-kind: Sql.Connection
-metadata:
-  name: Db
-driver: sqlite
-file: ./tmp/feedback.db
----
-# Migrations: applied automatically before the server starts
-kind: Sql.Migrations
-metadata:
-  name: Migrations
-connection:
-  kind: Sql.Connection
-  name: Db
----
-kind: Sql.Migration
-metadata:
-  name: Migration_20260413_182154_CreateFeedback
-version: 20260413_182154_CreateFeedback
-sql: |
-  CREATE TABLE IF NOT EXISTS feedback (
-    id        INTEGER PRIMARY KEY AUTOINCREMENT,
-    text      TEXT    NOT NULL,
-    source    TEXT,
-    score     INTEGER NOT NULL DEFAULT 0,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-  )
----
-kind: Http.Server
-metadata:
-  name: Server
-baseUrl: http://localhost:8844
-port: 8844
-logger: true
-openapi:
-  info:
-    title: Feedback API
-    version: 1.0.0
-mounts:
-  - path: /v1
-    type: Http.Api.FeedbackRoutes
----
-kind: Http.Api
-metadata:
-  name: FeedbackRoutes
-routes:
-  # POST /v1/feedback — insert a new entry, score derived from body length heuristic
-  - request:
-      path: /feedback
-      method: POST
-      schema:
-        body:
-          type: object
-          properties:
-            text:
-              type: string
-              minLength: 1
-            source:
-              type: string
-          required: [text]
-    handler:
-      kind: Sql.Exec
-      connection:
-        kind: Sql.Connection
-        name: Db
-    inputs:
-      sql: "INSERT INTO feedback (text, source, score) VALUES (?, ?, ?)"
-      bindings:
-        - "${{ request.body.text }}"
-        - "${{ request.body.source }}"
-        - "${{ size(request.body.text) }}"
-    response:
-      - status: 201
-        headers:
-          Content-Type: application/json
-        body:
-          ok: true
-          message: Feedback received
-
-  # GET /v1/feedback — list all entries, newest first
-  - request:
-      path: /feedback
-      method: GET
-    handler:
-      kind: Sql.Select
-      connection:
-        kind: Sql.Connection
-        name: Db
-      from: feedback
-      columns: [id, text, source, score, created_at]
-      orderBy:
-        - { column: created_at, direction: desc }
-    response:
-      - status: 200
-        headers:
-          Content-Type: application/json
-        body: "${{ result.rows }}"
-
-  # GET /v1/feedback/{id} — fetch a single entry
-  - request:
-      path: /feedback/{id}
-      method: GET
-      schema:
-        params:
-          type: object
-          properties:
-            id:
-              type: integer
-          required: [id]
-    handler:
-      kind: Sql.Select
-      connection:
-        kind: Sql.Connection
-        name: Db
-      from: feedback
-      columns: [id, text, source, score, created_at]
-      where:
-        - { column: id, op: "=", value: "${{ request.params.id }}" }
-    response:
-      - status: 200
-        when: "size(result.rows) > 0"
-        headers:
-          Content-Type: application/json
-        body: "${{ result.rows[0] }}"
-      - status: 404
-        headers:
-          Content-Type: application/json
-        body:
-          ok: false
-          message: Not found
-```
+See [examples/](./examples/) for a list of working applications.
 
 ## Status
 
-Telo is under **active development**. The core runtime, module system, and standard library are functional, but the API surface — including YAML shapes — may change without notice. Not yet recommended for production use.
+Telo is under heavy development. While it is pre-1.0, breaking changes ship in **minor** releases — manifest shapes, kind schemas, and APIs can change between versions. Pin your imports and expect to update manifests when you upgrade. The core runtime, module system, and standard library are functional, but Telo is not yet recommended for production use.
+
+**1.0 lands when the Rust kernel reaches feature parity with the Node.js implementation** — that is the milestone that freezes the manifest contract across runtimes.
 
 ## The Meaning of Telo
 

package/dist/script.js

@@ -41,24 +41,22 @@ export async function register(ctx) {
         initialized = true;
     }
 }
+/** `inputType` / `outputType` are declared but never read here: the kernel binds
+ *  the resolved contract to this instance at creation and validates both
+ *  directions around `invoke()`. Validating again would double-check every call
+ *  and let this controller's wording pre-empt the kernel's, which names the
+ *  target and the side that supplied the bad value. */
 class StarlarkScript {
     ctx;
     manifest;
     code;
-    inputValidator;
-    outputValidator;
     constructor(ctx, manifest) {
         this.ctx = ctx;
         this.manifest = manifest;
         this.code = manifest.code || "";
-        this.inputValidator = ctx.createTypeValidator(manifest.inputType);
-        this.outputValidator = ctx.createTypeValidator(manifest.outputType);
     }
     async invoke(input) {
-        this.inputValidator.validate(input);
-        const result = await executeStarlark(this.code, input);
-        this.outputValidator.validate(result);
-        return result;
+        return executeStarlark(this.code, input);
     }
 }
 export async function create(resource, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/starlark",
-  "version": "0.4.1",
+  "version": "0.12.1",
   "description": "Telo Starlark module - Starlark script execution for Telo manifests.",
   "keywords": [
     "telo",
@@ -33,7 +33,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.16.0"
+    "@telorun/sdk": "0.75.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/script.ts

@@ -61,25 +61,23 @@ export async function register(ctx: ControllerContext): Promise<void> {
   }
 }
 
+/** `inputType` / `outputType` are declared but never read here: the kernel binds
+ *  the resolved contract to this instance at creation and validates both
+ *  directions around `invoke()`. Validating again would double-check every call
+ *  and let this controller's wording pre-empt the kernel's, which names the
+ *  target and the side that supplied the bad value. */
 class StarlarkScript implements ResourceInstance {
   private code: string;
-  private inputValidator: DataValidator;
-  private outputValidator: DataValidator;
 
   constructor(
     readonly ctx: ResourceContext,
     readonly manifest: ResourceManifest,
   ) {
     this.code = manifest.code || "";
-    this.inputValidator = ctx.createTypeValidator(manifest.inputType);
-    this.outputValidator = ctx.createTypeValidator(manifest.outputType);
   }
 
   async invoke(input: Record<string, any>): Promise<any> {
-    this.inputValidator.validate(input);
-    const result = await executeStarlark(this.code, input);
-    this.outputValidator.validate(result);
-    return result;
+    return executeStarlark(this.code, input);
   }
 }