cube-template

The cube: six swappable face contracts + a Cube assembler that runs the governed, eval-gated golden path (sense → substrate → cognition → eval → governance → [human] → action → feedback), threaded by one correlation id.

Status: M4 · part of the Vollko cube platform. Language: TypeScript (Bun/Node) · deps: cube-spine, eval-gate, governance.

The six faces (Sensing/Substrate/Cognition/Action/Feedback/Human) are interfaces with deterministic default fakes; evalSeam/policySeam adapters wire the real M1 (eval-gate) and M3 (governance) engines behind the contracts. Cognition is satisfiable by a fake or by cube-runtime's LoopEngine. Dev: bun install, bun test, bun run typecheck.

create-cube (the package bin) stamps a runnable cube repo from a declarative cube.config manifest. Optional, backward-compatible seams let a cube run on real engines with no change at the call site: a SubstrateFace.knowledgeLookup folds knowledge/memory evidence into context, and a TrustSeam adds last-mile per-call authorization right before an action dispatches (deny ⇒ blocked). With no trust seam supplied, the golden path is byte-for-byte unchanged.

Part of the Vollko cube platform — a polyrepo of composable, zero-dependency building blocks for AI-native organizations. See reference-constellation for the whole stack running end-to-end; packages depend on each other via file:../, so clone the siblings alongside this one.

This package depends on its siblings (cube-spine, eval-gate, governance) through file:../ paths. A standalone clone will not bun install or build — clone the sibling repos into the same workspace directory first.

Install

bun install
bun test
bunx tsc --noEmit

Usage

Assemble a cube from the six faces and run the golden path. The default fakes are deterministic, so this runs end-to-end with no external engines:

import {
  Cube,
  FixedCognition,
  FixedSensing,
  FixedSubstrate,
  HmacAction,
  RecordingFeedback,
  ScriptedHuman,
  type CubeConfig,
} from "cube-template";
import { Bus } from "cube-spine";

const config: CubeConfig = {
  name: "announce-cube",
  who: "did:web:cube",
  actionKind: "send-announcement",
  actionTarget: "ok.com",
};

const cube = new Cube(config, {
  sensing: new FixedSensing("sense.message.received", "ingest"),
  substrate: new FixedSubstrate(["context line"]),
  cognition: new FixedCognition("a fine draft."),
  action: new HmacAction(),
  feedback: new RecordingFeedback(),
  human: new ScriptedHuman(true),
  // EvalSeam / PolicySeam are interfaces — supply inline fakes, or wire the real
  // engines with evalSeam()/policySeam() (see Adapters below).
  evalSeam: { evaluate: () => ({ decision: "ship", score: 4.2 }) },
  policySeam: { decide: () => ({ decision: "allow", reason: "ok" }) },
}, new Bus());

const result = cube.run({ message: "hello" });
console.log(result.decision); // "shipped"

To run on the real platform engines, swap the inline seams for the adapters, which take an eval-gate Jury and a governance Gate:

import { evalSeam, policySeam, trustSeam } from "cube-template";

// evalSeam(jury, profile?)  → EvalSeam onto eval-gate (M1)
// policySeam(gate)          → PolicySeam onto governance (M3)
// trustSeam(authorizer)     → optional last-mile per-call authorization (deny ⇒ blocked)

Stamping a cube with create-cube

create-cube (the package bin) stamps a runnable cube repo from a declarative cube.config.json manifest:

create-cube --config cube.config.json --out ./my-cube

It writes package.json, tsconfig.json, README.md, the copied manifest, and a wired src/run.ts that builds a Cube and runs the golden path. The same generators are exposed programmatically via createCube(manifest, outDir) and parseCubeManifest(input).

CI & deploy recipes

Pure string generators (no filesystem, no deps) for wiring a stamped cube. The caller writes the returned text to the right path:

import { githubWorkflow, compositeAction, systemdUnit, dockerfile } from "cube-template";

githubWorkflow({ name: "ci" });                    // → .github/workflows/ci.yml
compositeAction({ binName: "cube-agent" });        // → action.yml
systemdUnit({ name: "billing-ops", execStart: "/usr/bin/bun run /app/src/run.ts", workingDir: "/app" });
dockerfile({ entry: "src/run.ts" });               // → Dockerfile

Public API

Exported from cube-template (src/index.ts):

• Assembler — Cube, and types CubeConfig, CubeFaces, GoldenPathResult.
• Face contracts (types) — SensingFace, SubstrateFace, CognitionFace, ActionFace, FeedbackFace, HumanFace, plus supporting types SensedInput, CognitionResultLite, Receipt, OutcomeKind, OutcomeSignal, ReviewRequest, ReviewResult.
• Seams (types) — EvalSeam, PolicySeam, TrustSeam, TrustDecisionLite.
• Default fakes — FixedSensing, FixedSubstrate, FixedCognition, HmacAction, RecordingFeedback, ScriptedHuman.
• Adapters — evalSeam, policySeam, trustSeam, and type Authorizer.
• Receipts — signReceipt, verifyReceipt.
• Manifest — parseCubeManifest, and types CubeManifest, SensorSpec, SopSpec.
• Generator — createCube.
• CI — githubWorkflow, compositeAction, and type CiOptions.
• Deploy — systemdUnit, dockerfile.

---

Apache-2.0 © 2026 Vlad Bordei bordeivlad@gmail.com · https://github.com/p-vbordei