@kalada/host 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# `@kalada/host`
+
+`@kalada/host` defines immutable, schema-neutral environment descriptors and a synchronous
+parse/compile/link/prepared execution pipeline for Kalada.
+
+## Authority separation
+
+Every binding declares `semanticType` as the syntax-owned `KaladaSyntaxStaticType`. That field is the
+only semantic projection. Editor shape, metadata, validators, codecs, and provider-owned tags never
+infer or fabricate a `KaladaType`. In particular, a metadata property named `$type` is ordinary data;
+only a future provider adapter with explicit trusted provenance may interpret its own tags.
+
+Editor shape is normalized into an ordered `kalada-editor-graph-v1` node table. Roots, definitions,
+properties, tuple items, union variants, paths, unresolved references, unknown constructs, and cycle
+edges retain input order. Graph construction, roots, definitions, reference resolution, and traversal
+are bounded, with limit evidence retained in the graph. Node IDs such as `n0` are
+deterministic traversal identities scoped only to that normalized document (`nodeIdScope` is
+`document-local`); they are not hashes, cache keys, or cross-document fingerprints.
+
+The schema-neutral graph can also retain literal, enum, never, unconstrained, opaque, record,
+intersection, wrapper, relation, additional-property, presence, source-ID, annotation, and
+constraint evidence. These constructs carry editor/provider evidence only; they do not infer the
+binding's semantic type. `readSemanticType` is the public bounded reader for generic adapter-owned
+type declarations.
+New normalized evidence fields on pre-existing public node/property interfaces are optional for
+source compatibility; host-produced normalized graphs always populate deterministic relation,
+presence, and required-name values.
+
+Normalized environments contain only recursively frozen serializable data. Validator and codec
+callbacks are held separately in the returned, instance-scoped `capabilitySnapshot`. There is no
+global provider registry, ambient lookup, cache, or import-time registration.
+
+## Manual provider
+
+```ts
+import { createManualProvider, describeEnvironment } from "@kalada/host";
+
+const provider = createManualProvider({
+  mode: "sync",
+  providerId: "example.manual",
+  providerVersion: "1",
+  configurationDigest: "sha256:configuration-owned-by-the-host",
+  bindings: [
+    {
+      id: "customer",
+      name: "customer",
+      path: ["customer"],
+      semanticType: "dynamic",
+      editorShape: {
+        root: {
+          kind: "object",
+          properties: [
+            { name: "name", required: true, shape: { kind: "scalar", name: "string" } },
+          ],
+        },
+      },
+      metadata: { description: "A customer record" },
+    },
+  ],
+});
+
+const described = describeEnvironment(provider);
+if (!described.ok) throw new Error(described.diagnostics[0]?.code);
+```
+
+Capability declarations and the provider explicitly state `mode: "sync" | "async"`; synchronous
+execution rejects async declarations before callback invocation and offers no asynchronous API. A
+capability is referenced from a binding by its declared handle. The normalized declaration is
+data-only while the matching `decode` or `convert` function exists only in `capabilitySnapshot`.
+
+Reusable cacheability requires all three provider fields (`providerId`, `providerVersion`, and
+`configurationDigest`) and all three capability fields (`capabilityId`, `capabilityVersion`, and
+`configurationDigest`). `cacheable: false` explicitly opts out. Any missing identity makes the
+environment explicitly non-cacheable; this package emits no link fingerprint.
+
+All failures use a frozen `phase: "environment"` diagnostic with a stable code and fixed message.
+Diagnostics may include a copied binding path and allow-listed provenance strings, but never include
+input values, callback/provider objects, exception messages, stacks, source text, or secrets.
+The public `HostDiagnostic` envelope covers parse, lower, compile, link, bind, and evaluate phases,
+UTF-16 sources, and immutable syntax/core causes.
+
+## Prepared execution
+
+```ts
+import { evaluateExpression, prepareExpression } from "@kalada/host";
+
+const prepared = prepareExpression("customerTotal + shipping", provider, {
+  parse: { sourceUri: "memory:///checkout.kalada" },
+});
+if (prepared.ok) {
+  const first = prepared.value.evaluate({ customerTotal: 10, shipping: 2 });
+  const second = prepared.value.evaluate({ customerTotal: 20, shipping: 3 });
+}
+const oneShot = evaluateExpression("customerTotal + shipping", provider, values);
+```
+
+`prepareExpression` composes environment description, `parseExpression`, `compileExpression`, and
+`linkExpression`. A prepared evaluation repeats own-data-property lookup, synchronous validation,
+explicit conversion, canonical semantic validation, freezing, binding, and core evaluation. It does
+not repeat source or link phases. Non-cacheable providers remain executable but omit
+`linkFingerprint`; the package owns no hidden cache.