create-t2k 0.1.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Create a runnable local T2K project with a synthetic ontology, accepted facts,
 a Decision Context, two executable policies, and disjoint replay evidence.
 
 ```bash
-npx create-t2k my-decision-loop
+npx create-t2k@latest my-decision-loop
 cd my-decision-loop
 npm start
 ```
@@ -14,10 +14,44 @@ baseline and challenger policies against the current facts, computes a held-out
 replay comparison, and emits a recommendation that still requires explicit
 human authorization.
 
+The generated project also includes a PostgreSQL 16 Compose service and a
+persisted golden path:
+
+```bash
+npm run db:up
+npm run lifecycle
+```
+
+That command records authorization, execution receipts, observations, computed
+rewards, held-out evaluation, independent promotion, and exact rollback in the
+open reference runtime.
+
+Stop the local containers without deleting lifecycle data with `npm run
+db:down`. Use the explicitly destructive `npm run db:reset` only when you
+intend to delete the disposable local database volume.
+
+To expose ontology validation, compilation, policy execution, replay, and
+reward evaluation to an MCP host, add:
+
+```json
+{
+  "mcpServers": {
+    "t2k": {
+      "command": "npx",
+      "args": ["-y", "@t2kai/mcp@latest"]
+    }
+  }
+}
+```
+
+This starts read-only and does not send project data to a hosted service. See
+the [`@t2kai/mcp` guide](https://github.com/sigaihealth/t2k-core/blob/main/packages/mcp/README.md)
+before enabling database access or agent writes.
+
 Use `--no-install` to generate files without running `npm install`:
 
 ```bash
-npx create-t2k my-decision-loop --no-install
+npx create-t2k@latest my-decision-loop --no-install
 ```
 
 The command refuses to write into a non-empty directory. Node.js 20.10 or newer

package/bin/create-t2k.mjs

@@ -24,7 +24,8 @@ Options:
   -v, --version  Show the package version
 
 The default directory is my-t2k-project. Existing non-empty directories are
-never overwritten.`;
+never overwritten. Generated projects include decision and optional
+persisted-lifecycle examples.`;
 
 try {
   const options = parseArguments(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-t2k",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Create a local T2K governed-decision project in minutes.",
   "license": "Apache-2.0",
   "keywords": [

package/src/scaffold.mjs

@@ -170,6 +170,8 @@ export async function scaffoldProject({
   }
   stdout.write("  npm start\n\n");
   stdout.write("The first run computes a recommendation; a human must still authorize it.\n");
+  stdout.write("Run `npm run db:up && npm run lifecycle` for the persisted closed loop.\n");
+  stdout.write("Use `npm run db:down` to stop it or `npm run db:reset` to delete its volume.\n");
 
   return { targetPath, projectName };
 }

package/template/README.md.template

@@ -19,6 +19,51 @@ The run performs five explicit steps:
 The output is not an autonomous authorization. The generated Decision Context
 requires a `dispatch_owner` to review the evidence and authorize any action.
 
+## Run the complete persisted loop
+
+Start the included PostgreSQL 16 service, then execute the lifecycle:
+
+```bash
+npm run db:up
+npm run lifecycle
+```
+
+This path persists 24 synthetic episodes and proves the full sequence:
+
+```text
+context -> recommendation -> human authorization -> execution receipt
+        -> observation -> computed reward -> held-out replay
+        -> human promotion -> exact rollback
+```
+
+The actors who propose, evaluate, promote, and roll back are deliberately
+separate synthetic identities. The event ledger is hash-chained and append-only.
+In production, authenticate those actor IDs and enforce organization roles in
+the calling service; the local runtime is not an identity provider. To remove
+the local containers while preserving their volume, run `npm run db:down`. To
+explicitly delete the disposable local volume and all lifecycle data in it, run
+`npm run db:reset`.
+
+## Connect an MCP host
+
+Expose validation, compilation, policy execution, replay, and reward evaluation
+to an MCP host with the safe database-free mode:
+
+```json
+{
+  "mcpServers": {
+    "t2k": {
+      "command": "npx",
+      "args": ["-y", "@t2kai/mcp@latest"]
+    }
+  }
+}
+```
+
+The MCP server does not expose human authorization or promotion operations.
+Read <https://t2k.ai/developers/> before enabling its optional Postgres or agent
+mutation modes.
+
 ## Change the example
 
 - Change current facts in `decision-context.json`.
@@ -26,6 +71,7 @@ requires a `dispatch_owner` to review the evidence and authorize any action.
 - Add observed outcomes to `episodes/holdout.json` without reusing training data.
 - Change concepts and decision contracts in `ontology-pack.json`.
 
-The quickstart uses local files and `@t2kai/core`; it does not send data to a
-hosted service. Persistence, receipts, promotion, and rollback require the
-portable lifecycle runtime or hosted Studio and are not simulated here.
+The quickstart uses local files, local PostgreSQL, and `@t2kai/core`; it does not
+send data to a hosted service. Set `T2K_DATABASE_URL` to use another Postgres
+database. Use a dedicated database because the runtime owns the
+`t2k_reference` schema.

package/template/compose.yml

@@ -0,0 +1,19 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: t2k_reference
+      POSTGRES_PASSWORD: t2k
+      POSTGRES_USER: t2k
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U t2k -d t2k_reference"]
+      interval: 2s
+      timeout: 5s
+      retries: 15
+    ports:
+      - "55432:5432"
+    volumes:
+      - t2k-reference-data:/var/lib/postgresql/data
+
+volumes:
+  t2k-reference-data:

package/template/package.json.template

@@ -8,9 +8,13 @@
   },
   "scripts": {
     "start": "node src/run.mjs",
-    "check": "node src/run.mjs"
+    "check": "node src/run.mjs",
+    "db:up": "docker compose up -d --wait",
+    "db:down": "docker compose down",
+    "db:reset": "docker compose down -v",
+    "lifecycle": "node src/lifecycle.mjs"
   },
   "dependencies": {
-    "@t2kai/core": "^0.1.0"
+    "@t2kai/core": "^0.3.0"
   }
 }

package/template/src/lifecycle.mjs

@@ -0,0 +1,313 @@
+import assert from "node:assert/strict";
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { validateOntologyPackManifest } from "@t2kai/core";
+import { compileOntologyPackSet } from "@t2kai/core/compiler";
+import { PostgresReferenceLifecycle } from "@t2kai/core/postgres";
+
+const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const readJson = async (relativePath) =>
+  JSON.parse(await fs.readFile(path.join(projectRoot, relativePath), "utf8"));
+const [manifest, baseline, candidatePolicy, holdout] = await Promise.all([
+  readJson("ontology-pack.json"),
+  readJson("policies/baseline.json"),
+  readJson("policies/candidate.json"),
+  readJson("episodes/holdout.json"),
+]);
+
+const validation = validateOntologyPackManifest(manifest);
+assert.equal(validation.valid, true, JSON.stringify(validation.errors));
+const compilation = compileOntologyPackSet({
+  manifests: [manifest],
+  roots: [{ ontologyId: manifest.ontologyId, version: manifest.ontologyVersion }],
+});
+assert.equal(compilation.status, "valid", JSON.stringify(compilation.diagnostics));
+
+const template = manifest.decisionTemplates[0];
+const learningContract = template.learningContract;
+const runId = randomUUID().replaceAll("-", "").slice(0, 10);
+const policyKey = `${baseline.policyKey}-${runId}`;
+const decisionType = `${template.decisionType}.${runId}`;
+const connectionString =
+  process.env.T2K_DATABASE_URL ??
+  process.env.DATABASE_URL ??
+  process.env.T2K_TEST_DATABASE_URL ??
+  "postgresql://t2k:t2k@127.0.0.1:55432/t2k_reference";
+
+const actors = {
+  proposer: { actorType: "agent", actorId: "agent:policy-builder" },
+  reviewer: { actorType: "human", actorId: "human:dispatch-owner" },
+  evaluator: { actorType: "human", actorId: "human:policy-evaluator" },
+  promoter: { actorType: "human", actorId: "human:policy-promoter" },
+  rollback: { actorType: "human", actorId: "human:rollback-reviewer" },
+  reward: { actorType: "system", actorId: "system:reward-engine" },
+};
+const lifecycle = new PostgresReferenceLifecycle({ connectionString });
+const trainingEpisodeIds = [];
+const holdoutEpisodeIds = [];
+
+const sha256 = (value) =>
+  createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+async function createAcceptedVersion(version, specification, parentVersionId) {
+  const proposed = await lifecycle.createPolicyVersion(
+    policyKey,
+    {
+      policyVersion: version,
+      learningMode: learningContract.mode,
+      specification,
+      rewardSpec: learningContract.rewardSpec,
+      parentVersionId,
+      rationale: `Synthetic reference policy ${version}.`,
+    },
+    actors.proposer
+  );
+  return lifecycle.acceptPolicyVersion(
+    policyKey,
+    proposed.policyVersion,
+    "An independent human accepted the deterministic policy.",
+    actors.reviewer
+  );
+}
+
+async function persistFixture(fixture, index) {
+  const key = `${runId}:${fixture.cohort}:${fixture.fixtureId}`;
+  const pressure = fixture.state.facts[0].objectValue;
+  const context = await lifecycle.createDecisionContext(
+    {
+      contextKey: `context:${key}`,
+      question: template.question,
+      decisionType,
+      stateSnapshot: fixture.state,
+      objective: { maximize: template.successMeasure },
+      constraints: template.policies,
+      requiredAuthority: { role: template.authority },
+      learningContract,
+    },
+    actors.proposer
+  );
+  const recommendation = await lifecycle.recommend(
+    context.contextKey,
+    { recommendationKey: `recommendation:${key}` },
+    actors.proposer
+  );
+  assert.equal(recommendation.proposedAction, fixture.loggedAction);
+  const authorization = await lifecycle.authorizeRecommendation(
+    recommendation.id,
+    { rationale: "The dispatch owner authorizes this reversible synthetic action." },
+    actors.reviewer
+  );
+  const episode = await lifecycle.openEpisode(
+    {
+      episodeKey: `episode:${key}`,
+      contextKey: context.contextKey,
+      authorizedDecisionId: authorization.id,
+      externalEffect: true,
+    },
+    actors.proposer
+  );
+
+  const request = { action: fixture.loggedAction, pressure };
+  const response = { applied: true, synthetic: true };
+  await lifecycle.recordExecutionReceipt(
+    episode.id,
+    {
+      receiptKey: `receipt:${key}`,
+      idempotencyKey: `idempotency:${key}`,
+      connectorRef: "synthetic.harborlight.dispatch",
+      externalTransactionId: `dispatch-${key}`,
+      outcome: "succeeded",
+      requestHash: sha256(request),
+      responseHash: sha256(response),
+      response,
+      rollbackContract: { operation: "restore_prior_dispatch_plan" },
+      reconciliationStatus: "reconciled",
+    },
+    actors.proposer
+  );
+  await lifecycle.recordObservation(
+    episode.id,
+    {
+      measureRef: learningContract.rewardSpec[0].measureRef,
+      observedValue: 0.4 + fixture.scalarReward * 0.4,
+      baselineValue: 0.4,
+      unit: "ratio",
+      observationWindow: "7d",
+      sourceRefs: [`fixture://harborlight/${key}`],
+      provenance: { cohort: fixture.cohort, synthetic: true },
+      attributionConfidence: 1,
+      observedAt: new Date(Date.UTC(2026, 0, index + 1)).toISOString(),
+    },
+    actors.proposer
+  );
+  const reward = await lifecycle.assessReward(
+    episode.id,
+    {
+      assessmentKey: `assessment:${key}`,
+      attribution: { method: "deterministic_synthetic_fixture" },
+    },
+    actors.reward
+  );
+  assert.equal(reward.lifecycleStatus, "complete");
+  await lifecycle.closeEpisode(
+    episode.id,
+    "The receipt and outcome observation are complete.",
+    actors.reviewer
+  );
+  (fixture.cohort === "training" ? trainingEpisodeIds : holdoutEpisodeIds).push(
+    episode.id
+  );
+}
+
+const behaviorTraining = [
+  {
+    fixtureId: "training-rebalance-01",
+    cohort: "training",
+    state: { facts: [{ objectValue: 0.82 }] },
+    loggedAction: "rebalance_route",
+    scalarReward: 0.8,
+  },
+  {
+    fixtureId: "training-rebalance-02",
+    cohort: "training",
+    state: { facts: [{ objectValue: 0.74 }] },
+    loggedAction: "rebalance_route",
+    scalarReward: 0.7,
+  },
+];
+const baselineTraining = [
+  {
+    fixtureId: "training-hold-01",
+    cohort: "training",
+    state: { facts: [{ objectValue: 0.31 }] },
+    loggedAction: "hold",
+    scalarReward: 0,
+  },
+  {
+    fixtureId: "training-hold-02",
+    cohort: "training",
+    state: { facts: [{ objectValue: 0.22 }] },
+    loggedAction: "hold",
+    scalarReward: 0.05,
+  },
+];
+const normalizedHoldout = holdout.map((episode) => ({
+  ...episode,
+  fixtureId: episode.episodeId,
+  cohort: "holdout",
+}));
+
+try {
+  const schemaVersion = await lifecycle.migrate();
+  await lifecycle.createPolicy(
+    {
+      policyKey,
+      label: "Harborlight dispatch policy",
+      decisionType,
+      description: "A synthetic persisted decision-learning loop.",
+    },
+    actors.proposer
+  );
+
+  const behavior = await createAcceptedVersion(
+    "0.9.0",
+    candidatePolicy.specification
+  );
+  await lifecycle.deployPolicyVersion(policyKey, "0.9.0", actors.reviewer);
+  const behaviorFixtures = [
+    ...behaviorTraining,
+    ...normalizedHoldout.filter((episode) => episode.loggedAction === "rebalance_route"),
+  ];
+  for (const [index, fixture] of behaviorFixtures.entries()) {
+    await persistFixture(fixture, index);
+  }
+
+  const baselineVersion = await createAcceptedVersion(
+    baseline.version,
+    baseline.specification,
+    behavior.id
+  );
+  await lifecycle.deployPolicyVersion(policyKey, baseline.version, actors.reviewer);
+  const baselineFixtures = [
+    ...baselineTraining,
+    ...normalizedHoldout.filter((episode) => episode.loggedAction !== "rebalance_route"),
+  ];
+  for (const [index, fixture] of baselineFixtures.entries()) {
+    await persistFixture(fixture, behaviorFixtures.length + index);
+  }
+
+  assert.equal(trainingEpisodeIds.length, 4);
+  assert.equal(holdoutEpisodeIds.length, 20);
+  const candidate = await lifecycle.createCandidate(
+    {
+      candidateKey: `candidate:${runId}:${candidatePolicy.version}`,
+      policyKey,
+      sourcePolicyVersionId: baselineVersion.id,
+      proposedPolicyVersion: candidatePolicy.version,
+      proposedSpecification: candidatePolicy.specification,
+      trainingEpisodeIds,
+      rationale: "Training evidence supports route rebalancing under pressure.",
+    },
+    actors.proposer
+  );
+  const replay = await lifecycle.evaluateCandidate(
+    candidate.id,
+    {
+      evaluationKey: `replay:${runId}:${candidatePolicy.version}`,
+      holdoutEpisodeIds,
+      evidenceRefs: [`fixture://harborlight/${runId}/holdout`],
+    },
+    actors.evaluator
+  );
+  assert.equal(replay.lifecycleStatus, "passed");
+
+  const promoted = await lifecycle.promoteCandidate(
+    candidate.id,
+    {
+      reviewRationale: "Computed held-out replay passed the promotion threshold.",
+      deploy: true,
+    },
+    actors.promoter
+  );
+  const rollback = await lifecycle.rollbackPromotion(
+    promoted.promotion.id,
+    "Restore the exact parent after proving rollback.",
+    actors.rollback
+  );
+  const restored = await lifecycle.getActivePolicy(decisionType);
+  assert.equal(restored?.version.id, baselineVersion.id);
+  const eventChain = await lifecycle.verifyEventChain();
+  assert.equal(eventChain.valid, true);
+
+  console.log(
+    JSON.stringify(
+      {
+        status: "passed",
+        ontology: `${manifest.ontologyId}@${manifest.ontologyVersion}`,
+        resolutionHash: compilation.resolutionHash,
+        runId,
+        schemaVersion,
+        persisted: { episodes: 24, executionReceipts: 24 },
+        replay: replay.metrics,
+        promotion: {
+          version: promoted.policyVersion.policyVersion,
+          status: promoted.promotion.lifecycleStatus,
+        },
+        rollback: {
+          status: rollback.lifecycleStatus,
+          restoredVersion: restored.version.policyVersion,
+          exactParentRestored: true,
+        },
+        eventChain,
+      },
+      null,
+      2
+    )
+  );
+} finally {
+  await lifecycle.close();
+}