create-t2k 0.4.0 → 0.4.1

package/README.md

@@ -5,7 +5,7 @@ a Decision Context, two executable policies, and disjoint replay evidence.
 The existing decision-loop project remains the default profile.
 
 ```bash
-npx create-t2k@latest my-decision-loop
+npx create-t2k@0.4.1 my-decision-loop
 cd my-decision-loop
 npm start
 ```
@@ -31,6 +31,10 @@ 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.
 
+Compose binds PostgreSQL to `127.0.0.1:55432` only. The included `t2k` username
+and `t2k` password are disposable local-only quickstart credentials; never
+reuse them or expose this generated database to another host.
+
 To expose ontology validation, compilation, policy execution, replay, and
 reward evaluation to an MCP host, add:
 
@@ -39,7 +43,7 @@ reward evaluation to an MCP host, add:
   "mcpServers": {
     "t2k": {
       "command": "npx",
-      "args": ["-y", "@t2kai/mcp@latest"]
+      "args": ["-y", "@t2kai/mcp@0.3.0"]
     }
   }
 }
@@ -52,9 +56,12 @@ before enabling database access or agent writes.
 Use `--no-install` to generate files without running `npm install`:
 
 ```bash
-npx create-t2k@latest my-decision-loop --no-install
+npx create-t2k@0.4.1 my-decision-loop --no-install
 ```
 
+The normal command installs dependencies for you. Run `npm install` inside the
+generated project only when you chose `--no-install`.
+
 The command refuses to write into a non-empty directory. Node.js 20.10 or newer
 is required.
 
@@ -63,7 +70,7 @@ is required.
 Generate a focused, fully synthetic source-integration project explicitly:
 
 ```bash
-npx create-t2k@latest my-integration-hub --profile integration-hub
+npx create-t2k@0.4.1 my-integration-hub --profile integration-hub
 cd my-integration-hub
 npm start
 ```
@@ -71,21 +78,31 @@ npm start
 This profile maps two independent registry records into one canonical party
 identity, preserves conflicting name evidence, and applies a versioned authority
 order to a conflicting registry state. It runs reconciliation again with the
-opposite input order and proves the proposal hash is identical.
+opposite input order and reports that specifically scoped proposal-hash
+comparison; it does not claim to check every permutation after more sources are
+added.
 
 Every regular `source-records/*.json` file is discovered in canonical filename
 order, so the generated README experiments work without editing the runner:
-reverse the versioned authority priorities or add a third synthetic source with
-the same canonical key and run `npm start` again.
+reverse the authority priorities while bumping `policyVersion`, or add a third
+synthetic source with the same canonical key and run `npm start` again.
 
 The output is a deterministic evidence packet for human review. It preserves
-the complete source receipts and alternatives inside the hashed packet, does
-not mutate any source record, and does not promote the authority-selected
+every canonical record with its complete receipt, the exact loaded
+`@t2kai/core` package version, the complete authority policy, and the full
+forward and reverse reconciliation proposals and issues inside the hashed
+packet. It does not mutate any source record or promote the authority-selected
 candidate to accepted truth. Both included synthetic sources deliberately have
 an `unknown` authentication state. The unkeyed hashes demonstrate deterministic
 self-consistency only; they are not signatures, authentication, or proof that a
 source assertion is true.
 
+After an envelope has been mapped, keep it immutable: represent a later
+observation with a new file, source-record key, payload record ID, and event and
+observation times. Bump `policyVersion` after changing authority priorities;
+bump `mappingVersion` and `ontologyVersion` after changing a mapping; and bump
+`ontologyVersion` for any other ontology contract change.
+
 Supported profiles are `decision-loop` (the default) and `integration-hub`.
 An unknown or repeated `--profile` option fails before the target directory is
 created.

package/package.json

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

package/template/README.md.template

@@ -4,10 +4,12 @@ This project is a local T2K governed-decision quickstart. Its data is fully
 synthetic.
 
 ```bash
-npm install
 npm start
 ```
 
+`create-t2k` installs dependencies by default. Run `npm install` first only if
+this project was generated with `--no-install`.
+
 The run performs five explicit steps:
 
 1. validate `ontology-pack.json` against the published T2K schema;
@@ -44,6 +46,10 @@ 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`.
 
+Compose binds PostgreSQL to `127.0.0.1:55432` only. Its `t2k` username and
+`t2k` password are disposable local-only quickstart credentials; never reuse
+them outside this generated project or expose this database to another host.
+
 ## Connect an MCP host
 
 Expose validation, compilation, policy execution, replay, and reward evaluation
@@ -54,7 +60,7 @@ to an MCP host with the safe database-free mode:
   "mcpServers": {
     "t2k": {
       "command": "npx",
-      "args": ["-y", "@t2kai/mcp@latest"]
+      "args": ["-y", "@t2kai/mcp@0.3.0"]
     }
   }
 }
@@ -67,9 +73,15 @@ mutation modes.
 ## Change the example
 
 - Change current facts in `decision-context.json`.
-- Change executable rules in `policies/*.json`.
+- Change executable rules in `policies/*.json` and bump the policy `version`.
 - Add observed outcomes to `episodes/holdout.json` without reusing training data.
-- Change concepts and decision contracts in `ontology-pack.json`.
+- Change concepts or decision contracts in `ontology-pack.json` and bump
+  `ontologyVersion`.
+
+Treat any context, policy, episode, or ontology artifact that has already been
+executed or persisted as immutable evidence. Model a later observation with a
+new context or episode identifier, and keep the prior artifact available for
+replay instead of rewriting history.
 
 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

package/template/compose.yml

@@ -2,6 +2,8 @@ services:
   postgres:
     image: postgres:16-alpine
     environment:
+      # Disposable local-only quickstart credentials. Never reuse t2k/t2k
+      # outside this generated project.
       POSTGRES_DB: t2k_reference
       POSTGRES_PASSWORD: t2k
       POSTGRES_USER: t2k
@@ -11,7 +13,7 @@ services:
       timeout: 5s
       retries: 15
     ports:
-      - "55432:5432"
+      - "127.0.0.1:55432:5432"
     volumes:
       - t2k-reference-data:/var/lib/postgresql/data
 

package/template/package.json.template

@@ -15,6 +15,6 @@
     "lifecycle": "node src/lifecycle.mjs"
   },
   "dependencies": {
-    "@t2kai/core": "^0.4.0"
+    "@t2kai/core": "^0.4.1"
   }
 }

package/template/src/lifecycle.mjs

@@ -10,8 +10,21 @@ 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"));
+
+async function readJson(relativePath) {
+  const contents = await fs.readFile(
+    path.join(projectRoot, relativePath),
+    "utf8"
+  );
+  try {
+    return JSON.parse(contents);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new SyntaxError(`Invalid JSON in ${relativePath}${detail}`, {
+      cause: error,
+    });
+  }
+}
 const [manifest, baseline, candidatePolicy, holdout] = await Promise.all([
   readJson("ontology-pack.json"),
   readJson("policies/baseline.json"),

package/template/src/run.mjs

@@ -12,8 +12,21 @@ import {
 import { compileOntologyPackSet } from "@t2kai/core/compiler";
 
 const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const readJson = async (relativePath) =>
-  JSON.parse(await fs.readFile(path.join(projectRoot, relativePath), "utf8"));
+
+async function readJson(relativePath) {
+  const contents = await fs.readFile(
+    path.join(projectRoot, relativePath),
+    "utf8"
+  );
+  try {
+    return JSON.parse(contents);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new SyntaxError(`Invalid JSON in ${relativePath}${detail}`, {
+      cause: error,
+    });
+  }
+}
 
 const [manifest, context, baseline, candidate, episodes] = await Promise.all([
   readJson("ontology-pack.json"),

package/template-integration-hub/README.md.template

@@ -5,10 +5,12 @@ two independently governed source records can be mapped into one canonical
 identity without silently merging evidence or declaring either source true.
 
 ```bash
-npm install
 npm start
 ```
 
+`create-t2k` installs dependencies by default. Run `npm install` first only if
+this project was generated with `--no-install`.
+
 The run performs these explicit steps:
 
 1. validate and compile `ontology-pack.json`;
@@ -17,8 +19,9 @@ The run performs these explicit steps:
 3. preserve all conflicting display-name candidates;
 4. apply `authority-policy.json` to select a registry-state candidate within
    the proposal;
-5. repeat reconciliation in the opposite input order; and
-6. emit a deterministic evidence packet for human review.
+5. compare the forward source order with its reverse (not every possible
+   ordering when more than two sources exist); and
+6. emit a repeatable evidence packet for human review.
 
 The selected registry-state value is only a candidate within a non-mutating
 proposal. No source record is changed and no value becomes accepted truth.
@@ -26,18 +29,29 @@ Both source envelopes deliberately use `authenticationState: "unknown"`.
 Production callers must authenticate or attest sources and policies outside
 this example.
 
-Each complete source-mapping receipt is included in the evidence packet before
-the packet hash is computed. The receipt, policy, proposal, and packet hashes
-are unkeyed deterministic self-consistency checks. They are not signatures,
-authentication tokens, or proof that an assertion is true.
-
-## Explore the hub
-
-- Change a source value in `source-records/` and inspect the preserved evidence.
-- Reverse the priorities in `authority-policy.json`, rerun, and inspect the
-  changed proposed authority selection.
-- Add a third synthetic `.json` source with the same `party_key`; it is
-  discovered automatically on the next run.
+Each canonical record is paired with its complete source-mapping receipt in the
+evidence packet. The packet also includes the exact loaded `@t2kai/core`
+package version, the complete authority policy, both complete reconciliation
+proposals and their issues, and an explicitly scoped forward-versus-reverse
+hash comparison. All of those fields are included before the packet hash is
+computed. The receipt, policy, proposal, and packet hashes are unkeyed
+deterministic self-consistency checks. They are not signatures, authentication
+tokens, or proof that an assertion is true.
+
+## Explore the hub safely
+
+- Treat a source envelope as immutable once it has been mapped. To model a
+  later observation, copy it to a new `.json` file and assign a new
+  `sourceRecordKey`, payload `record_id`, `eventTime`, and `observedTime`; never
+  rewrite the earlier envelope.
+- To reverse the priorities in `authority-policy.json`, also bump
+  `policyVersion`, rerun, and inspect the changed proposed authority selection.
+- Add a third synthetic `.json` source with the same `party_key` and its own
+  new envelope identifiers and timestamps; it is discovered automatically on
+  the next run.
+- When a field mapping changes, bump its `mappingVersion`. Because mappings are
+  part of this ontology pack, also bump `ontologyVersion`; bump
+  `ontologyVersion` for any other ontology contract change as well.
 - Replace `humanCheckpoint: "always"` only after defining a real review and
   authorization boundary in the calling system.
 

package/template-integration-hub/package.json.template

@@ -11,6 +11,6 @@
     "check": "node src/run.mjs"
   },
   "dependencies": {
-    "@t2kai/core": "^0.4.0"
+    "@t2kai/core": "^0.4.1"
   }
 }

package/template-integration-hub/src/run.mjs

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import fs from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -15,9 +16,18 @@ import {
 } from "@t2kai/core/compiler";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const loadPackageManifest = createRequire(import.meta.url);
 
 async function readJson(relativePath) {
-  return JSON.parse(await fs.readFile(path.join(root, relativePath), "utf8"));
+  const contents = await fs.readFile(path.join(root, relativePath), "utf8");
+  try {
+    return JSON.parse(contents);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new SyntaxError(`Invalid JSON in ${relativePath}${detail}`, {
+      cause: error,
+    });
+  }
 }
 
 async function readSourceRecords() {
@@ -43,6 +53,17 @@ const manifest = await readJson("ontology-pack.json");
 const authorityPolicy = await readJson("authority-policy.json");
 const sourceRecords = await readSourceRecords();
 const sourceSnapshot = structuredClone(sourceRecords);
+const corePackageManifest = loadPackageManifest("@t2kai/core/package.json");
+assert.equal(
+  corePackageManifest.name,
+  "@t2kai/core",
+  "The integration packet must identify the loaded core runtime."
+);
+assert.ok(
+  typeof corePackageManifest.version === "string" &&
+    corePackageManifest.version.length > 0,
+  "The loaded core runtime must expose an exact package version."
+);
 
 const validation = validateOntologyPackManifest(manifest);
 assert.equal(
@@ -160,8 +181,13 @@ assert.ok(preferAuthorityField.candidates.length >= 2);
 
 const packetWithoutHash = {
   profile: "integration-hub",
+  coreRuntime: {
+    packageName: corePackageManifest.name,
+    packageVersion: corePackageManifest.version,
+  },
   ontology: `${manifest.ontologyId}@${manifest.ontologyVersion}`,
   resolutionHash: compilation.resolutionHash,
+  authorityPolicy: structuredClone(authorityPolicy),
   sourceEvidence: mappedResults
     .map((result) => ({
       summary: {
@@ -172,6 +198,7 @@ const packetWithoutHash = {
         receiptHash: result.receipt.receiptHash,
         humanReviewRequired: result.receipt.humanReviewRequired,
       },
+      canonicalRecord: result.canonicalRecord,
       receipt: result.receipt,
     }))
     .sort((left, right) =>
@@ -181,38 +208,27 @@ const packetWithoutHash = {
       )
     ),
   reconciliation: {
-    proposalHash: reconciliation.proposalHash,
-    status: reconciliation.status,
-    canonicalIdentity: reconciliation.identity,
-    authorityPolicy: {
-      policyId: reconciliation.policyId,
-      policyVersion: reconciliation.policyVersion,
-      policyHash: reconciliation.policyHash,
-    },
-    deterministicAcrossInputOrder:
-      reconciliation.proposalHash === reverseOrderReconciliation.proposalHash,
-    humanReviewRequired: reconciliation.humanReviewRequired,
-    nonMutating: reconciliation.nonMutating,
-    alternativesPreserved: reconciliation.alternativesPreserved,
-    preserveAll: {
-      propertyRef: preserveAllField.propertyRef,
-      resolution: preserveAllField.resolution,
-      selectedValue: preserveAllField.selectedValue,
-      candidates: preserveAllField.candidates,
-    },
-    preferAuthority: {
-      propertyRef: preferAuthorityField.propertyRef,
-      resolution: preferAuthorityField.resolution,
-      selectedWithinProposal: preferAuthorityField.selectedValue,
-      candidates: preferAuthorityField.candidates,
+    proposal: reconciliation,
+    reverseInputOrderProposal: reverseOrderReconciliation,
+    forwardReverseInputOrderCheck: {
+      comparisonScope: "forward_and_reverse_input_order_only",
+      allPermutationsChecked: mappedResults.length === 2,
+      forwardReceiptHashes: mappedResults.map(
+        (result) => result.receipt.receiptHash
+      ),
+      reverseReceiptHashes: [...mappedResults]
+        .reverse()
+        .map((result) => result.receipt.receiptHash),
+      forwardProposalHash: reconciliation.proposalHash,
+      reverseProposalHash: reverseOrderReconciliation.proposalHash,
+      proposalHashesMatch:
+        reconciliation.proposalHash === reverseOrderReconciliation.proposalHash,
     },
   },
   humanReview: {
     status: "pending_human_review",
     proposalOnly: true,
-    issues: reconciliation.issues
-      .filter((issue) => issue.severity === "review")
-      .map(({ code, message, receiptHash }) => ({ code, message, receiptHash })),
+    issues: reconciliation.issues,
   },
   boundaries: {
     syntheticDataOnly: true,