@jarenjs/studio 0.34.2 → 0.43.1

package/README.md

@@ -25,7 +25,8 @@ This package ships in two layers, the suite's convention:
   host registers the DOM-touching islands — the live nested-app stage
   (hot-update via `app.setState`) and the drag splitter — which are
   browser-verified. Mounted live at the website's `#/project`, where `app`
-  files boot, `jslt`/`query` files run against a data file, and files are
+  files boot, `jslt`/`query` files run against a data file, `contract`
+  files render their `describe()`/OpenAPI projections, and files are
   added, renamed, deleted and opened from templates.
 
 ## The project document

package/dist/types/assemble.d.ts

@@ -14,7 +14,10 @@
  * HOT-DISPATCH into a running app (no reboot, the user keeps scroll and
  * inputs), while a `view`/`actions` change must reboot. It compares a
  * STRUCTURAL key (an app doc minus its `state`) via the suite's own
- * `contentKey`, so the policy in the widget reads clean, tested data.
+ * `semanticKey` — the collision-free identity, not the memo-grade
+ * `contentKey` fingerprint: a classification decides whether a running
+ * app reboots, so a fingerprint collision would read a changed document
+ * as unchanged. The artifacts are parsed JSON, so the identity is total.
  */
 /**
  * Compose the project's files into runnable artifacts (whole-document).

package/dist/types/component/editor.d.ts

@@ -65,4 +65,5 @@ export declare const KIND_BADGE: Readonly<{
     model: "model";
     fsm: "flow";
     dag: "flow";
+    contract: "model";
 }>;

package/dist/types/validate.d.ts

@@ -12,6 +12,9 @@
  *               real error comes back as its own coded `JQ`/`JT` code with
  *               a docPath — the closed grammar would reject the operators;
  *  - `fsm` / `dag` / `model` → their published grammar (structural);
+ *  - `contract` → COMPILED by `compileContract`, so a refusal comes back
+ *               as its stable `JC00xx` code with the docPath of the
+ *               member at fault — richer than the grammar alone;
  *  - `schema` → compiled as a JSON Schema (is it well-formed?);
  *  - `state` / `data` → any JSON (structural only).
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/studio",
   "private": false,
-  "version": "0.34.2",
+  "version": "0.43.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -59,11 +59,12 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.2",
-    "@jarenjs/validate": "^0.34.2",
-    "@jarenjs/json": "^0.34.2",
-    "@jarenjs/app": "^0.34.2",
-    "@jarenjs/flow": "^0.34.2",
-    "@jarenjs/db": "^0.34.2"
+    "@jarenjs/core": "^0.43.1",
+    "@jarenjs/validate": "^0.43.1",
+    "@jarenjs/json": "^0.43.1",
+    "@jarenjs/app": "^0.43.1",
+    "@jarenjs/flow": "^0.43.1",
+    "@jarenjs/db": "^0.43.1",
+    "@jarenjs/contract": "^0.43.1"
   }
 }

package/schemas/jaren-project.schema.json

@@ -28,7 +28,7 @@
         "name": { "type": "string", "minLength": 1 },
         "kind": {
           "description": "The file's grammar/role; its `text` is validated against this kind, not the envelope.",
-          "enum": ["app", "jslt", "query", "state", "data", "schema", "fsm", "dag", "model"]
+          "enum": ["app", "jslt", "query", "state", "data", "schema", "fsm", "dag", "model", "contract"]
         },
         "text": { "type": "string" }
       }

package/src/assemble.js

@@ -15,20 +15,24 @@
  * HOT-DISPATCH into a running app (no reboot, the user keeps scroll and
  * inputs), while a `view`/`actions` change must reboot. It compares a
  * STRUCTURAL key (an app doc minus its `state`) via the suite's own
- * `contentKey`, so the policy in the widget reads clean, tested data.
+ * `semanticKey` — the collision-free identity, not the memo-grade
+ * `contentKey` fingerprint: a classification decides whether a running
+ * app reboots, so a fingerprint collision would read a changed document
+ * as unchanged. The artifacts are parsed JSON, so the identity is total.
  */
 
-import { contentKey } from '@jarenjs/core/object';
+import { semanticKey } from '@jarenjs/core/object';
 import { validateFile } from './validate.js';
 
 /** Kinds that are runnable artifacts on their own (vs. `state`/`data`
  * inputs). */
-const RUNNABLE = new Set(['app', 'jslt', 'query', 'schema', 'fsm', 'dag', 'model']);
+const RUNNABLE = new Set(['app', 'jslt', 'query', 'schema', 'fsm', 'dag', 'model', 'contract']);
 
 /** A human role per kind, for the file rail's legibility. */
 const ROLE = Object.freeze({
   app: 'application', jslt: 'transform', query: 'query', state: 'state',
   data: 'data', schema: 'schema', fsm: 'state machine', dag: 'dataflow', model: 'data store',
+  contract: 'contract',
 });
 
 /**
@@ -59,8 +63,8 @@ export function assembleArtifacts(project) {
  * (its `state` excluded); everything else in full. */
 function structuralKey(artifact) {
   return artifact.kind === 'app'
-    ? contentKey({ view: artifact.doc.view, actions: artifact.doc.actions, subs: artifact.doc.subs })
-    : contentKey(artifact.doc);
+    ? semanticKey({ view: artifact.doc.view, actions: artifact.doc.actions, subs: artifact.doc.subs })
+    : semanticKey(artifact.doc);
 }
 
 const RANK = { none: 0, 'state-only': 1, structural: 2 };
@@ -88,7 +92,7 @@ export function classifyChange(prevProject, nextProject) {
     let c;
     if (b === undefined) c = 'structural';
     else if (structuralKey(b) !== structuralKey(a)) c = 'structural';
-    else if (contentKey(b.doc) !== contentKey(a.doc)) c = 'state-only';
+    else if (semanticKey(b.doc) !== semanticKey(a.doc)) c = 'state-only';
     else c = 'none';
     perArtifact[name] = c;
     bump(c);

package/src/component/editor.js

@@ -56,4 +56,7 @@ export function errorLine(content) {
 export const KIND_BADGE = Object.freeze({
   app: 'view', jslt: 'view', query: 'query', state: 'json',
   data: 'json', schema: 'json', model: 'model', fsm: 'flow', dag: 'flow',
+  // the model family: documents that declare a schema-backed surface —
+  // the badge palette is a closed five-hue set (studio.css header)
+  contract: 'model',
 });

package/src/component/view.js

@@ -87,6 +87,7 @@ const shell = {
         ['option', { value: 'state' }, 'state'],
         ['option', { value: 'data' }, 'data'],
         ['option', { value: 'schema' }, 'schema'],
+        ['option', { value: 'contract' }, 'contract'],
       ],
       [{ $apply: '$.rail[*]' }]],
     // ——— editor ———

package/src/component/viewmodel.js

@@ -37,10 +37,12 @@ function deriveStage(project, activeMeta, results, revision, committed) {
     // here it is the data: the assembled document + the reboot revision
     return { kind: 'app', mount: { doc: artifact.doc, revision } };
   }
-  if (activeMeta.kind === 'jslt' || activeMeta.kind === 'query' || activeMeta.kind === 'schema') {
-    // the host runs the file (a transform, or a schema validating the data
-    // file) and stores its render nodes; the stage renders them in `ui`
-    // mode, or a hint until the first run lands
+  if (activeMeta.kind === 'jslt' || activeMeta.kind === 'query' || activeMeta.kind === 'schema'
+    || activeMeta.kind === 'contract') {
+    // the host runs the file (a transform, a schema validating the data
+    // file, or a contract's describe()/OpenAPI projections) and stores
+    // its render nodes; the stage renders them in `ui` mode, or a hint
+    // until the first run lands
     const result = results[activeMeta.name] ?? null;
     return { kind: 'result', ran: result !== null, nodes: result?.nodes ?? [] };
   }

package/src/project.js

@@ -15,6 +15,7 @@ import { StudioError } from './errors.js';
 /** The closed set of file kinds (matches the schema `kind` enum). */
 export const KINDS = Object.freeze([
   'app', 'jslt', 'query', 'state', 'data', 'schema', 'fsm', 'dag', 'model',
+  'contract',
 ]);
 
 /** The default IDE layout — the frozen `{ mode, ratio, autorun }` shape

package/src/validate.js

@@ -13,6 +13,9 @@
  *               real error comes back as its own coded `JQ`/`JT` code with
  *               a docPath — the closed grammar would reject the operators;
  *  - `fsm` / `dag` / `model` → their published grammar (structural);
+ *  - `contract` → COMPILED by `compileContract`, so a refusal comes back
+ *               as its stable `JC00xx` code with the docPath of the
+ *               member at fault — richer than the grammar alone;
  *  - `schema` → compiled as a JSON Schema (is it well-formed?);
  *  - `state` / `data` → any JSON (structural only).
  *
@@ -27,6 +30,7 @@ import { compileJsonQuery } from '@jarenjs/json';
 import {
   compileJsltStylesheet, createJsltRegistry, mathPack, financePack, statsPack,
 } from '@jarenjs/json/jslt';
+import { compileContract } from '@jarenjs/contract';
 
 import appSchema from '@jarenjs/app/schemas/jaren-app.schema.json' with { type: 'json' };
 import querySchema from '@jarenjs/json/schemas/jaren-query.schema.json' with { type: 'json' };
@@ -178,6 +182,8 @@ function validateFileUncached(file, options = {}) {
       return schemaResult(kind, validateDag(doc));
     case 'model':
       return schemaResult(kind, validateModel(doc));
+    case 'contract':
+      return compileResult(kind, () => compileContract(doc));
     case 'schema':
       // a JSON Schema is a boolean or an object; anything else is not a
       // schema at all (the compiler is otherwise lenient about a schema's