@sutraa/kalpa-compiler

@sutraa/kalpa-compiler

@sutraa/kalpa-compiler validates canonical manifests and provides a Node-only subpath for loading files, normalizing supported multi-file composition, and building portable JSON artifacts. The root entry point is framework-neutral; @sutraa/kalpa-compiler/node uses synchronous Node.js filesystem APIs.

npm install @sutraa/kalpa-compiler

Root API: validate an in-memory manifest

compileManifest(input, options?) accepts unknown input. It checks the schema, duplicate IDs, unresolved semantic references, and whether every behavior command is declared by its target capability.

import { compileManifest } from "@sutraa/kalpa-compiler";

const result = compileManifest(input, {
  source: { file: "experience.kalpa.json", line: 1, column: 1 },
});

if (!result.ok || !result.manifest) {
  for (const diagnostic of result.diagnostics) {
    console.error(diagnostic.code, diagnostic.path, diagnostic.message);
  }
} else {
  console.log(result.summary);
}

Result field	Meaning
ok	true only when no compiler diagnostic exists.
manifest	validated canonical manifest when ok is true.
summary	entity, relationship, capability, behavior, and representation counts.
diagnostics	structured errors with code, path, message, and optional source.

Node API: files, composition, and artifacts

Import Node-only helpers from the explicit subpath.

import {
  buildProjectArtifact,
  compileManifestFile,
  compileProjectFile,
  loadProjectArtifact,
} from "@sutraa/kalpa-compiler/node";

Use compileManifestFile for a single canonical JSON manifest. Use compileProjectFile for either a canonical manifest or a supported composition entry. The latter normalizes valid fragments into a canonical manifest before returning it.

const project = compileProjectFile("./manifests/equipment.kalpa.json");
if (!project.ok) throw new Error(JSON.stringify(project.diagnostics));

const built = buildProjectArtifact(
  "./manifests/equipment.kalpa.json",
  "./dist/equipment.artifact.json",
);
if (!built.ok) throw new Error(JSON.stringify(built.diagnostics));

const loaded = loadProjectArtifact("./dist/equipment.artifact.json");
if (loaded.ok) console.log(loaded.artifact?.summary);

Supported composition model

Composition is authoring input, not renderer or runtime input. A composition entry owns the experience declaration and relationships; fragments each own exactly one or more of the required semantic collections. Every required collection must have one owner: entities, capabilities, behaviors, and representations.

{
  "compositionVersion": "0.1",
  "experience": { "id": "pump-demo", "name": "Pump demo", "purpose": "Inspect a pump", "defaultRepresentation": "dom" },
  "relationships": [],
  "fragments": ["./entities.kalpa.json", "./interaction.kalpa.json"]
}

{
  "fragmentVersion": "0.1",
  "owns": ["entities"],
  "entities": []
}

Rule	Consequence
A fragment reference appears twice	deterministic COMPOSITION_CONFLICT diagnostic.
Two fragments own the same collection	deterministic COMPOSITION_CONFLICT diagnostic.
A required collection has no owner	COMPOSITION_INVALID diagnostic.
Raw composition is sent to a runtime or renderer	unsupported contract use; compile first.

The normal boundary is: raw composition → compileProjectFile → canonical manifest → runtime / renderer / artifact.

Artifact contents

buildProjectArtifact writes a JSON artifact with version, source provenance, semantic summary, canonical manifest, and graph snapshot. loadProjectArtifact reparses and revalidates that canonical manifest before returning it. Artifacts are designed for portable structured processing, not as an executable bundle.

License

MIT. Requires Node.js 18 or later.