@almadar/shell-node 0.0.0-stage → 1.0.0

package/dist/chunk-7QE32QQR.js

@@ -0,0 +1,523 @@
+import { installedWorkspaceHost, workspaceOwnerSegment } from './chunk-BWMLDDCL.js';
+import { execFile, spawnSync } from 'child_process';
+import { mkdtempSync, rmSync, readFileSync, mkdirSync, writeFileSync, existsSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { tmpdir } from 'os';
+import { relative, resolve, isAbsolute, sep, join } from 'path';
+import { z } from 'zod';
+import { createLogger } from '@almadar/logger';
+import { decodeProveReport, decodeOsGrantsReport, decodeValidationJsonOutput, isStepRefusal, decodeStepRefusal, decodePlayedStep } from '@almadar/core/kernel-wire';
+import { resolveOrbBinary, discoverBehaviorPackages } from '@almadar/core/behavior-package';
+import { EventPayloadSchema, CatalogEntrySchema, formatTraitValueLiteral, BehaviorDescriptionSchema, importsOf, dependencyGraphOf, DescribeTargetSchema, CatalogScopeSchema, parseProgram, ProgramInspectionSchema, TraitDescriptionSchema } from '@almadar/core';
+
+var log = createLogger("almadar:integrations:program");
+function runOrb(args, opts) {
+  const bin = opts.orbBin ?? resolveOrbBinary(opts.cwd);
+  return new Promise((done) => {
+    execFile(bin, [...args], { cwd: opts.cwd, maxBuffer: 1024 * 1024 * 512 }, (error, stdout, stderr) => {
+      const code = error === null ? 0 : typeof error.code === "number" ? error.code : 1;
+      if (code !== 0) log.warn("orb exited non-zero", { args: args.join(" "), code, stderr });
+      done({ stdout, stderr, code });
+    });
+  });
+}
+function runOrbSync(args, opts) {
+  const bin = opts.orbBin ?? resolveOrbBinary(opts.cwd);
+  const res = spawnSync(bin, [...args], { cwd: opts.cwd, maxBuffer: 1024 * 1024 * 512, encoding: "utf-8" });
+  const code = res.error !== void 0 ? 1 : res.status ?? 1;
+  const stderr = res.error !== void 0 ? res.error.message : res.stderr;
+  if (code !== 0) log.warn("orb exited non-zero", { args: args.join(" "), code, stderr });
+  return { stdout: res.stdout, stderr, code };
+}
+var ProgramParser = {
+  safeParse(value) {
+    try {
+      return { success: true, data: parseProgram(value) };
+    } catch (error) {
+      return { success: false, error: { message: error instanceof Error ? error.message : String(error) } };
+    }
+  }
+};
+function parseJson(schema, run, what) {
+  if (run.code !== 0) throw new Error(`${what}: orb exited ${run.code}: ${run.stderr.trim()}`);
+  const parsed = schema.safeParse(JSON.parse(run.stdout));
+  if (!parsed.success) throw new Error(`${what}: unexpected orb output: ${parsed.error.message}`);
+  return parsed.data;
+}
+function decodeJson(decode, run, what) {
+  if (run.code !== 0) throw new Error(`${what}: orb exited ${run.code}: ${run.stderr.trim()}`);
+  try {
+    return decode(JSON.parse(run.stdout));
+  } catch (error) {
+    throw new Error(`${what}: unexpected orb output: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function issueOf(finding) {
+  return { code: finding.code, message: finding.message, path: finding.path, ...finding.line !== void 0 ? { line: finding.line } : {}, ...finding.column !== void 0 ? { column: finding.column } : {} };
+}
+function withTempFile(name, content, use) {
+  const dir = mkdtempSync(join(tmpdir(), "almadar-program-"));
+  const path = join(dir, name);
+  writeFileSync(path, content);
+  return use(path).finally(() => rmSync(dir, { recursive: true, force: true }));
+}
+function withProjectFile(cwd, name, content, use) {
+  const path = join(cwd, `.${randomUUID()}-${name}`);
+  writeFileSync(path, content);
+  return use(path).finally(() => rmSync(path, { force: true }));
+}
+async function behaviorCatalog(scope, opts, options = {}) {
+  const exposure = (scope.exposure ?? []).flatMap((e) => ["--exposure", e]);
+  const noTraits = options.traits === false ? ["--no-traits"] : [];
+  const run = await runOrb(["behaviors", "catalog", "--json", ...noTraits, ...scope.paths, ...exposure], opts);
+  return parseJson(CatalogEntrySchema.array(), run, "behavior/catalog");
+}
+function behaviorCatalogSync(scope, opts) {
+  const exposure = (scope.exposure ?? []).flatMap((e) => ["--exposure", e]);
+  return parseJson(CatalogEntrySchema.array(), runOrbSync(["behaviors", "catalog", "--json", ...scope.paths, ...exposure], opts), "behavior/catalog");
+}
+async function behaviorDescribe(value, opts) {
+  if ("trait" in value) {
+    const run = await runOrb(["behaviors", "describe", "--json", formatTraitValueLiteral(value)], opts);
+    return parseJson(TraitDescriptionSchema, run, "behavior/describe");
+  }
+  const spec = "orbital" in value ? `${value.behavior}.orbitals.${value.orbital}` : value.behavior;
+  return parseJson(BehaviorDescriptionSchema, await runOrb(["behaviors", "describe", "--json", spec], opts), "behavior/describe");
+}
+function booleanOptions(op, raw, keys) {
+  const options = raw ?? {};
+  if (options === null || typeof options !== "object" || Array.isArray(options)) return `${op}: options must be an object`;
+  const out = {};
+  for (const [k, v] of Object.entries(options)) {
+    const key = keys.find((known) => known === k);
+    if (key === void 0) return `${op}: unsupported option "${k}"`;
+    if (typeof v !== "boolean") return `${op}: ${k} must be a boolean`;
+    out[key] = v;
+  }
+  return out;
+}
+async function behaviorSource(value, opts) {
+  const run = await runOrb(["behaviors", "source", "--json", value.behavior], opts);
+  return parseJson(ProgramParser, run, "behavior/source");
+}
+function programRead(text, opts) {
+  return withTempFile(
+    "program.lolo",
+    text,
+    async (path) => parseJson(ProgramParser, await runOrb(["emit", "orb", path], opts), "program/read")
+  );
+}
+async function programReadOutcome(text, opts) {
+  return withTempFile("program.lolo", text, async (path) => {
+    const run = await runOrb(["emit", "orb", path], opts);
+    if (run.code !== 0) return fail(`program/read: orb exited ${run.code}: ${run.stderr.trim()}`);
+    const parsed = ProgramParser.safeParse(JSON.parse(run.stdout));
+    if (parsed.success) return { ok: true, result: parsed.data };
+    const report = decodeJson(decodeValidationJsonOutput, await runOrb(["validate", "--json", "--deny-warnings", path], opts), "program/read");
+    const issues = [...report.errors ?? [], ...report.warnings ?? []].map(issueOf);
+    if (issues.length === 0) return fail(`program/read: not a program: ${parsed.error.message}`);
+    return { ok: false, error: `program/read: ${issues.length} validation issue(s): ${issues.map((e) => e.message).join("; ")}`, errors: issues };
+  });
+}
+async function programInspectOutcome(text, raw, opts) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return fail("program/read inspect: options must be an object");
+  if (typeof raw.path !== "string" || !isAbsolute(raw.path)) return fail("program/read inspect: path must be the original absolute .lolo path");
+  if (raw.version !== void 0 && raw.version !== null && (typeof raw.version !== "number" || !Number.isSafeInteger(raw.version) || raw.version < 0)) return fail("program/read inspect: version must be a nonnegative integer");
+  const originalPath = raw.path;
+  const version = raw.version;
+  return withTempFile("program.lolo", text, async (path) => {
+    const args = ["emit", "orb", path, "--inspect-source", originalPath];
+    if (typeof version === "number") args.push("--document-version", String(version));
+    const run = await runOrb(args, opts);
+    if (run.code !== 0) return fail(`program/read inspect: orb exited ${run.code}: ${run.stderr.trim()}`);
+    return { ok: true, result: parseJson(ProgramInspectionSchema, run, "program/read inspect") };
+  });
+}
+function programPrint(program, opts) {
+  return withTempFile("program.orb", JSON.stringify(program), async (path) => {
+    const run = await runOrb(["emit", "lolo", path], opts);
+    if (run.code !== 0) throw new Error(`program/print: orb exited ${run.code}: ${run.stderr.trim()}`);
+    return run.stdout;
+  });
+}
+function workspaceAccessError(behavior, opts, context) {
+  const host = installedWorkspaceHost();
+  if (host === null || !behavior.startsWith("./")) return void 0;
+  const under = relative(host.root, resolve(opts.cwd, behavior));
+  if (under.startsWith("..") || isAbsolute(under)) return void 0;
+  const owner = under.split(sep)[0];
+  if (context?.principal !== void 0 && workspaceOwnerSegment(context.principal) === owner) return void 0;
+  return `behavior "${behavior}" is in another user's workspace`;
+}
+var PROGRAM_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+async function stampAndValidate(program, opts, dir, caller) {
+  if (!PROGRAM_NAME.test(program.name)) {
+    return { ok: false, errors: [{ code: "PROGRAM_NAME_INVALID", message: `program name "${program.name}" is not a file name` }] };
+  }
+  const input = join(dir, `${program.name}.orb`);
+  const stamped = join(dir, `${program.name}.stamped.orb`);
+  writeFileSync(input, JSON.stringify(program));
+  const stampArgs = ["stamp", input, "-o", stamped];
+  if (opts.prior !== void 0) {
+    const priorPath = join(dir, "prior.orb");
+    writeFileSync(priorPath, JSON.stringify(opts.prior));
+    stampArgs.push("--prior", priorPath);
+  }
+  const stamp = await runOrb(stampArgs, opts);
+  if (stamp.code !== 0) {
+    return { ok: false, errors: [{ code: "PROGRAM_STAMP_FAILED", message: stamp.stderr.trim() }] };
+  }
+  const validateArgs = ["validate", "--json", "--deny-warnings", ...opts.final === true ? ["--final"] : [], stamped];
+  const report = decodeJson(decodeValidationJsonOutput, await runOrb(validateArgs, opts), caller);
+  const errors = (report.errors ?? []).map(issueOf);
+  const warnings = (report.warnings ?? []).map(issueOf);
+  return { ok: true, stamped, errors, warnings, valid: report.valid && errors.length === 0 && warnings.length === 0 };
+}
+async function programValidate(program, opts) {
+  const dir = mkdtempSync(join(tmpdir(), "almadar-validate-"));
+  try {
+    const run = await stampAndValidate(program, opts, dir, "program/validate");
+    return run.ok ? { valid: run.valid, errors: run.errors, warnings: run.warnings } : { valid: false, errors: run.errors, warnings: [] };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+async function programProve(target, opts) {
+  if ("path" in target) return decodeJson(decodeProveReport, await runOrb(["prove", target.path], opts), "program/prove");
+  if (!PROGRAM_NAME.test(target.program.name)) throw new Error(`program/prove: program name "${target.program.name}" is not a file name`);
+  return withTempFile(`${target.program.name}.orb`, JSON.stringify(target.program), async (file) => decodeJson(decodeProveReport, await runOrb(["prove", file], opts), "program/prove"));
+}
+async function programOsGrants(target, opts) {
+  const flags = opts.final === true ? ["--final"] : [];
+  if ("path" in target) return decodeJson(decodeOsGrantsReport, await runOrb(["os-grants", target.path, ...flags], opts), "program/os-grants");
+  if (!PROGRAM_NAME.test(target.program.name)) throw new Error(`program/os-grants: program name "${target.program.name}" is not a file name`);
+  return withTempFile(`${target.program.name}.orb`, JSON.stringify(target.program), async (file) => decodeJson(decodeOsGrantsReport, await runOrb(["os-grants", file, ...flags], opts), "program/os-grants"));
+}
+async function programEval(program, opts) {
+  const dir = mkdtempSync(join(tmpdir(), "almadar-eval-"));
+  try {
+    const run = await stampAndValidate(program, opts, dir, "program/eval");
+    if (!run.ok) return { ok: false, errors: run.errors };
+    const stamped = run.stamped;
+    const issues = [...run.errors, ...run.warnings];
+    if (!run.valid || issues.length > 0) return { ok: false, errors: issues };
+    const written = ProgramParser.safeParse(JSON.parse(readFileSync(stamped, "utf-8")));
+    if (!written.success) throw new Error(`program/eval: stamped program does not parse: ${written.error.message}`);
+    const content = JSON.stringify(written.data, null, 2);
+    let behavior;
+    if (opts.workspace !== void 0) {
+      const host = installedWorkspaceHost();
+      if (host === null) return { ok: false, errors: [{ code: "PROGRAM_NO_WORKSPACE_HOST", message: "no workspace host is installed on this host" }] };
+      if (opts.workspace.context.principal === void 0) {
+        return { ok: false, errors: [{ code: "PROGRAM_WORKSPACE_UNAUTHORIZED", message: "a workspace eval needs a signed-in caller" }] };
+      }
+      const ws = await host.open(opts.workspace.id, opts.workspace.context);
+      const rel = relative(opts.cwd, ws.workDir);
+      if (rel.startsWith("..") || isAbsolute(rel)) {
+        return { ok: false, errors: [{ code: "PROGRAM_WORKSPACE_OUTSIDE_PROJECT", message: `workspace ${ws.workDir} is outside the project ${opts.cwd}` }] };
+      }
+      await ws.writeFile(`orbitals/${program.name}.orb`, content);
+      await ws.snapshot(`program/eval ${program.name}`);
+      behavior = `./${rel.split(sep).join("/")}/orbitals/${program.name}`;
+    } else {
+      const target = join(opts.cwd, "orbitals");
+      mkdirSync(target, { recursive: true });
+      writeFileSync(join(target, `${program.name}.orb`), content);
+      behavior = `./orbitals/${program.name}`;
+    }
+    const traits = written.data.orbitals.flatMap(
+      (orbital) => orbital.traits.flatMap((t) => typeof t === "object" && "name" in t && typeof t.name === "string" ? [{ behavior, trait: t.name }] : [])
+    );
+    return { ok: true, result: { behavior, traits, value: { behavior } } };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+var LAYOUT_STRATEGIES = ["sidebar", "tabs", "dashboard", "wizard-flow", "single"];
+async function programCompose(programs, options, opts) {
+  const dir = mkdtempSync(join(tmpdir(), "almadar-compose-"));
+  try {
+    const files = programs.map((program, index) => {
+      const file = join(dir, `${index}.orb`);
+      writeFileSync(file, JSON.stringify(program));
+      return file;
+    });
+    const flags = [
+      "--app-name",
+      options.appName,
+      ...options.layout !== void 0 ? ["--layout", options.layout] : [],
+      ...options.theme !== void 0 ? ["--theme", options.theme] : []
+    ];
+    return parseJson(ProgramParser, await runOrb(["compose", ...flags, ...files], opts), "program/compose");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+var WHICH_LINE = /^(\/\S+\.(?:orb|lolo)) \((.+)\)$/;
+async function behaviorFile(behavior, opts) {
+  if (behavior.startsWith("./")) {
+    const path = `${resolve(opts.cwd, behavior)}.orb`;
+    return existsSync(path) ? path : { error: `no program at ${behavior}` };
+  }
+  const run = await runOrb(["behaviors", "which", behavior], opts);
+  const line = run.stdout.trim().split("\n").pop() ?? "";
+  const match = WHICH_LINE.exec(line);
+  if (run.code !== 0 || match === null) return { error: `behavior "${behavior}" is not installed${run.stderr.trim() ? `: ${run.stderr.trim()}` : ""}` };
+  return match[1];
+}
+async function programResolve(path, opts) {
+  return parseJson(ProgramParser, await runOrb(["resolve", path], opts), "program/resolve");
+}
+function programResolveSchema(program, opts) {
+  return withProjectFile(opts.cwd, "program.orb", JSON.stringify(program), (path) => programResolve(path, opts));
+}
+async function behaviorResolve(value, opts) {
+  const file = await behaviorFile(value.behavior, opts);
+  if (typeof file !== "string") return file;
+  return parseJson(ProgramParser, await runOrb(["resolve", file], opts), "behavior/resolve");
+}
+function installedBehaviorIndex(opts) {
+  const out = /* @__PURE__ */ new Map();
+  for (const pkg of discoverBehaviorPackages(opts.cwd)) {
+    const tier = pkg.name === "@almadar/std" ? "std" : pkg.name === "@almadar-io/behaviors" ? "io" : "unknown";
+    const catalog = parseJson(CatalogEntrySchema.array(), runOrbSync(["behaviors", "catalog", "--json", "--no-vectors", pkg.orb.prefix], opts), "behavior/dependencies");
+    for (const entry of catalog) {
+      const name = entry.behavior.slice(pkg.orb.prefix.length + 1);
+      if (!out.has(name)) out.set(name, { tier, prefix: pkg.orb.prefix, ...entry.pattern !== void 0 ? { pattern: entry.pattern } : {} });
+    }
+  }
+  return out;
+}
+async function behaviorDependencies(program, opts) {
+  const index = installedBehaviorIndex(opts);
+  const orbs = /* @__PURE__ */ new Map();
+  let frontier = [...new Set(importsOf(program, () => "unknown").map((i) => i.behavior))];
+  while (frontier.length > 0) {
+    const loaded = await Promise.all(
+      frontier.map(async (name) => {
+        const entry = index.get(name);
+        return [name, entry ? await behaviorSource({ behavior: `${entry.prefix}/${name}` }, opts) : null];
+      })
+    );
+    const next = /* @__PURE__ */ new Set();
+    for (const [name, orb] of loaded) {
+      orbs.set(name, orb);
+      for (const i of orb ? importsOf(orb, () => "unknown") : []) if (!orbs.has(i.behavior)) next.add(i.behavior);
+    }
+    frontier = [...next].filter((n) => !orbs.has(n));
+  }
+  return dependencyGraphOf(program, {
+    tierOf: (n) => index.get(n)?.tier ?? "unknown",
+    orbOf: (n) => orbs.get(n) ?? null,
+    patternOf: (n) => index.get(n)?.pattern
+  });
+}
+var StepRequestSchema = z.object({
+  orbital: z.string(),
+  trait: z.string(),
+  from: z.string(),
+  event: z.string(),
+  payload: EventPayloadSchema,
+  entity: EventPayloadSchema.optional(),
+  config: EventPayloadSchema.optional(),
+  now: z.number().optional(),
+  settleMs: z.number().optional(),
+  identity: z.object({ subject: z.string(), claims: EventPayloadSchema }).optional()
+});
+function decodePlayedSteps(printed) {
+  if (!Array.isArray(printed)) throw new Error("program/step: expected an array of played steps");
+  return printed.map((step) => decodePlayedStep(step));
+}
+function decodePlayedOutput(run) {
+  if (run.code !== 0) throw new Error(`program/step: orb exited ${run.code}: ${run.stderr.trim()}`);
+  try {
+    const printed = JSON.parse(run.stdout);
+    return isStepRefusal(printed) ? decodeStepRefusal(printed) : decodePlayedSteps(printed);
+  } catch (error) {
+    throw new Error(`program/step: unexpected orb output: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function programStep(program, requests, opts, live = false) {
+  const steps = requests.map((r) => ({ orbital: r.orbital, trait: r.trait, event: r.event, payload: r.payload, from: r.from, ...r.entity !== void 0 ? { entity: r.entity } : {}, ...r.config !== void 0 ? { config: r.config } : {}, ...r.now !== void 0 ? { now: r.now } : {}, ...r.settleMs !== void 0 ? { settleMs: r.settleMs } : {}, ...r.identity !== void 0 ? { identity: r.identity } : {} }));
+  return withTempFile("program.orb", JSON.stringify(program), async (path) => {
+    const run = await runOrb(["execute", path, "--steps", JSON.stringify(steps), "--played", ...live ? ["--live"] : []], opts);
+    return decodePlayedOutput(run);
+  });
+}
+function fail(error) {
+  return { ok: false, error };
+}
+function issuesOf(error) {
+  return error.issues.map((i) => i.path.length > 0 ? `${i.path.map(String).join(".")}: ${i.message}` : i.message).join("; ");
+}
+function programArg(op, value) {
+  const parsed = ProgramParser.safeParse(value);
+  return parsed.success ? parsed.data : `${op}: not a program: ${parsed.error.message}`;
+}
+async function runProgramEffect(op, args, opts, context) {
+  log.debug("effect", { op, args: JSON.stringify(args) });
+  try {
+    switch (op) {
+      case "behavior/catalog": {
+        const scope = CatalogScopeSchema.safeParse(args[0]);
+        if (!scope.success) return fail(`behavior/catalog: ${issuesOf(scope.error)}`);
+        const options = booleanOptions(op, args[1], ["traits"]);
+        if (typeof options === "string") return fail(options);
+        return { ok: true, result: await behaviorCatalog(scope.data, opts, options.traits === void 0 ? {} : { traits: options.traits }) };
+      }
+      case "behavior/describe": {
+        const value = DescribeTargetSchema.safeParse(args[0]);
+        if (!value.success) return fail(`${op}: ${issuesOf(value.error)}`);
+        const none = booleanOptions(op, args[1], []);
+        if (typeof none === "string") return fail(none);
+        const denied = workspaceAccessError(value.data.behavior, opts, context);
+        if (denied !== void 0) return fail(`${op}: ${denied}`);
+        return { ok: true, result: await behaviorDescribe(value.data, opts) };
+      }
+      case "behavior/source": {
+        const value = DescribeTargetSchema.safeParse(args[0]);
+        if (!value.success) return fail(`${op}: ${issuesOf(value.error)}`);
+        const denied = workspaceAccessError(value.data.behavior, opts, context);
+        if (denied !== void 0) return fail(`${op}: ${denied}`);
+        return { ok: true, result: await behaviorSource(value.data, opts) };
+      }
+      case "behavior/resolve": {
+        const value = DescribeTargetSchema.safeParse(args[0]);
+        if (!value.success) return fail(`${op}: ${issuesOf(value.error)}`);
+        const denied = workspaceAccessError(value.data.behavior, opts, context);
+        if (denied !== void 0) return fail(`${op}: ${denied}`);
+        const resolved = await behaviorResolve(value.data, opts);
+        return "error" in resolved ? fail(`${op}: ${resolved.error}`) : { ok: true, result: resolved };
+      }
+      case "program/step": {
+        const program = programArg(op, args[0]);
+        if (typeof program === "string") return fail(program);
+        const requests = z.array(StepRequestSchema).safeParse(args[1]);
+        if (!requests.success) return fail(`${op}: ${issuesOf(requests.error)}`);
+        const options = args[2];
+        const live = options !== null && typeof options === "object" && !Array.isArray(options) ? options["live"] : void 0;
+        if (live !== void 0 && live !== null && typeof live !== "boolean") return fail(`${op}: options.live must be a boolean`);
+        const played = await programStep(program, requests.data, opts, live === true);
+        return "error" in played ? fail(`${op}: ${played.error}`) : { ok: true, result: played };
+      }
+      case "behavior/dependencies": {
+        const program = programArg(op, args[0]);
+        return typeof program === "string" ? fail(program) : { ok: true, result: await behaviorDependencies(program, opts) };
+      }
+      case "program/read": {
+        if (typeof args[0] !== "string") return fail("program/read: expected .lolo text");
+        const options = args[1];
+        if (options !== null && typeof options === "object" && !Array.isArray(options) && options.inspect === true) return programInspectOutcome(args[0], options, opts);
+        return programReadOutcome(args[0], opts);
+      }
+      case "program/print": {
+        const program = programArg(op, args[0]);
+        return typeof program === "string" ? fail(program) : { ok: true, result: await programPrint(program, opts) };
+      }
+      case "program/compose": {
+        if (!Array.isArray(args[0])) return fail("program/compose: expected a list of programs");
+        const programs = [];
+        for (const raw of args[0]) {
+          const program = programArg(op, raw);
+          if (typeof program === "string") return fail(program);
+          programs.push(program);
+        }
+        const options = args[1];
+        if (options === null || options === void 0 || typeof options !== "object" || Array.isArray(options)) {
+          return fail("program/compose: options must be an object with an appName");
+        }
+        let appName;
+        let layout;
+        let theme;
+        for (const [key, value] of Object.entries(options)) {
+          if (key === "appName" && typeof value === "string" && value.length > 0) appName = value;
+          else if (key === "theme" && typeof value === "string") theme = value.length > 0 ? value : void 0;
+          else if (key === "layout") {
+            const match = LAYOUT_STRATEGIES.find((l) => l === value);
+            if (match === void 0) return fail(`program/compose: layout must be one of ${LAYOUT_STRATEGIES.join(", ")}`);
+            layout = match;
+          } else return fail(`program/compose: unsupported option "${key}"`);
+        }
+        if (appName === void 0) return fail("program/compose: options must name the app (appName)");
+        return { ok: true, result: await programCompose(programs, { appName, ...layout !== void 0 ? { layout } : {}, ...theme !== void 0 ? { theme } : {} }, opts) };
+      }
+      case "program/validate": {
+        const program = programArg(op, args[0]);
+        if (typeof program === "string") return fail(program);
+        const options = args[1] ?? {};
+        if (options === null || typeof options !== "object" || Array.isArray(options)) return fail("program/validate: options must be an object");
+        let prior;
+        let final;
+        for (const [key, value] of Object.entries(options)) {
+          if (key === "final") {
+            if (typeof value !== "boolean") return fail("program/validate: final must be a boolean");
+            final = value;
+          } else if (key === "prior") {
+            const p = programArg("program/validate prior", value);
+            if (typeof p === "string") return fail(p);
+            prior = p;
+          } else return fail(`program/validate: unsupported option "${key}"`);
+        }
+        return { ok: true, result: await programValidate(program, { ...opts, ...prior !== void 0 ? { prior } : {}, ...final !== void 0 ? { final } : {} }) };
+      }
+      case "program/prove": {
+        const options = args[1] ?? {};
+        if (options === null || typeof options !== "object" || Array.isArray(options)) return fail("program/prove: options must be an object");
+        for (const key of Object.keys(options)) if (key !== "path") return fail(`program/prove: unsupported option "${key}"`);
+        const path = options["path"];
+        if (path !== void 0) {
+          if (typeof path !== "string" || !isAbsolute(path)) return fail("program/prove: path must be an absolute path");
+          return { ok: true, result: await programProve({ path }, opts) };
+        }
+        const program = programArg(op, args[0]);
+        if (typeof program === "string") return fail(program);
+        return { ok: true, result: await programProve({ program }, opts) };
+      }
+      case "program/os-grants": {
+        const options = args[1] ?? {};
+        if (options === null || typeof options !== "object" || Array.isArray(options)) return fail("program/os-grants: options must be an object");
+        for (const key of Object.keys(options)) if (key !== "path" && key !== "final") return fail(`program/os-grants: unsupported option "${key}"`);
+        const final = options["final"];
+        if (final !== void 0 && typeof final !== "boolean") return fail("program/os-grants: final must be a boolean");
+        const pass = final === true ? { final } : {};
+        const path = options["path"];
+        if (path !== void 0) {
+          if (typeof path !== "string" || !isAbsolute(path)) return fail("program/os-grants: path must be an absolute path");
+          return { ok: true, result: await programOsGrants({ path }, { ...opts, ...pass }) };
+        }
+        const program = programArg(op, args[0]);
+        if (typeof program === "string") return fail(program);
+        return { ok: true, result: await programOsGrants({ program }, { ...opts, ...pass }) };
+      }
+      case "program/eval": {
+        const program = programArg(op, args[0]);
+        if (typeof program === "string") return fail(program);
+        const options = args[1] ?? {};
+        if (options === null || typeof options !== "object" || Array.isArray(options)) return fail("program/eval: options must be an object");
+        let workspace;
+        let prior;
+        let final;
+        for (const [key, value] of Object.entries(options)) {
+          if (key === "workspace") {
+            if (typeof value !== "string" || value === "") return fail("program/eval: workspace must be a non-empty id");
+            workspace = value;
+          } else if (key === "final") {
+            if (typeof value !== "boolean") return fail("program/eval: final must be a boolean");
+            final = value;
+          } else if (key === "prior") {
+            const p = programArg("program/eval prior", value);
+            if (typeof p === "string") return fail(p);
+            prior = p;
+          } else return fail(`program/eval: unsupported option "${key}"`);
+        }
+        const outcome = await programEval(program, { ...opts, ...workspace !== void 0 ? { workspace: { id: workspace, context: context ?? {} } } : {}, ...prior !== void 0 ? { prior } : {}, ...final !== void 0 ? { final } : {} });
+        if (outcome.ok) return { ok: true, result: outcome.result };
+        return { ok: false, error: `program/eval: ${outcome.errors.length} validation issue(s): ${outcome.errors.map((e) => e.message).join("; ")}`, errors: outcome.errors };
+      }
+    }
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+export { behaviorCatalog, behaviorCatalogSync, behaviorDependencies, behaviorDescribe, behaviorResolve, behaviorSource, programCompose, programEval, programOsGrants, programPrint, programProve, programRead, programResolve, programResolveSchema, programStep, programValidate, runProgramEffect, workspaceAccessError };

package/dist/chunk-7QG7JGKQ.js

@@ -0,0 +1,18 @@
+import { workspacesRoot, kernelWorkspaceHost, workspaceBucketFromEnv } from './chunk-YLFK5OJN.js';
+import { runProgramEffect } from './chunk-7QE32QQR.js';
+import { installedWorkspaceHost, installWorkspaceHost } from './chunk-BWMLDDCL.js';
+
+// src/program/createProgramHandlers.ts
+var bucketOf = () => {
+  const bucket = workspaceBucketFromEnv(process.env);
+  return bucket === void 0 ? {} : { bucket };
+};
+function createProgramHandlers(host) {
+  const opts = host.orbBin === void 0 ? { cwd: host.cwd } : { cwd: host.cwd, orbBin: host.orbBin };
+  if (installedWorkspaceHost()?.root !== workspacesRoot(host.cwd)) {
+    installWorkspaceHost(kernelWorkspaceHost({ projectRoot: host.cwd, ...bucketOf(), ...host.orbBin !== void 0 ? { orb: host.orbBin } : {} }));
+  }
+  return { programEffect: (op, args, context) => runProgramEffect(op, args, opts, context) };
+}
+
+export { createProgramHandlers };

package/dist/chunk-BWMLDDCL.js

@@ -0,0 +1,21 @@
+// src/program/workspace-host.ts
+var installedHost = null;
+function installWorkspaceHost(host) {
+  installedHost = host;
+}
+function uninstallWorkspaceHost() {
+  installedHost = null;
+}
+function installedWorkspaceHost() {
+  return installedHost;
+}
+function workspaceOwnerSegment(principal) {
+  let out = "";
+  for (const byte of new TextEncoder().encode(principal)) {
+    const ch = String.fromCharCode(byte);
+    out += /[A-Za-z0-9-]/.test(ch) ? ch : `_${byte.toString(16).padStart(2, "0")}`;
+  }
+  return out;
+}
+
+export { installWorkspaceHost, installedWorkspaceHost, uninstallWorkspaceHost, workspaceOwnerSegment };

package/dist/chunk-EEYGL7AB.js

@@ -0,0 +1,53 @@
+import { createRequire } from 'module';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { pathToFileURL } from 'url';
+import { installKernelEvaluator } from '@almadar/core';
+import { readLanguageBundle } from '@almadar/core/language-data';
+import * as installedModule from '@almadar/kernel';
+import { NativeMemoryPersistenceAdapter } from '@almadar/shell-runtime';
+
+// src/kernel-loader.ts
+function hasMemoryStore(kernel) {
+  return "MemoryStore" in kernel;
+}
+function nativeMemoryOf(kernel) {
+  if (!hasMemoryStore(kernel)) throw new Error("this kernel module exports no MemoryStore; install a kernel build that carries it");
+  return new NativeMemoryPersistenceAdapter(new kernel.MemoryStore());
+}
+var initialised = /* @__PURE__ */ new WeakSet();
+function initOnce(loaded, wasm, languageFrom) {
+  if (initialised.has(loaded)) return loaded;
+  if (wasm !== void 0) loaded.initSync({ module: wasm });
+  loaded.installLanguage(JSON.stringify(readLanguageBundle(languageFrom)));
+  installKernelEvaluator(loaded);
+  initialised.add(loaded);
+  return loaded;
+}
+async function loadInstalledKernel(languageFrom) {
+  return initOnce(installedModule, readFileSync(createRequire(import.meta.url).resolve("@almadar/kernel/kernel.wasm")), languageFrom);
+}
+async function loadKernelModule(kernelDir, options) {
+  const loaded = await import(pathToFileURL(join(kernelDir, "pkg/orbital_wasm.js")).href);
+  return initOnce(loaded, initialised.has(loaded) ? void 0 : readFileSync(join(kernelDir, "pkg/orbital_wasm_bg.wasm")), options.languageFrom);
+}
+var NATIVE_PLATFORMS = {
+  "darwin-x64": "darwin-x64",
+  "darwin-arm64": "darwin-arm64",
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+  "win32-x64": "windows-x64"
+};
+function resolveNativeAddon(from) {
+  const named = process.env.ALMADAR_KERNEL_NODE;
+  if (named !== void 0 && named !== "") return named;
+  const platform = NATIVE_PLATFORMS[`${process.platform}-${process.arch}`];
+  if (platform === void 0) throw new Error(`no native kernel add-on is shipped for ${process.platform}-${process.arch}`);
+  return createRequire(join(from, "resolve.js")).resolve(`@almadar/orb-${platform}/kernel.node`);
+}
+async function loadNativeKernelModule(addonPath, options) {
+  const loaded = createRequire(import.meta.url)(addonPath);
+  return initOnce(loaded, void 0, options.languageFrom);
+}
+
+export { loadInstalledKernel, loadKernelModule, loadNativeKernelModule, nativeMemoryOf, resolveNativeAddon };