bylazora 0.4.1 → 0.5.1

package/README.md

@@ -1,15 +1,29 @@
 # bylazora
 
 **Proof, not percentages.** Bylazora is the byte-exact mainframe migration
-standard: a migrated workload's outputs must equal the legacy COBOL reference
-byte for byte, or the gate fails it.
+standard: a migrated workload's outputs must equal the legacy COBOL
+reference byte for byte, or the gate fails it.
 
-This package reserves the `bylazora` name on npm. It will carry the MCP client
-and the agent rule packs: your coding assistant can operate the engine,
-propose, and measure, but it cannot mark a job proven. Only the validator can.
+This package is the agent-facing companion to the bylazora-core engine. It
+ships:
 
-The engine itself is a Rust crate, developed and released at
-**https://github.com/bylazora/bylazora** under AGPL-3.0-or-later (engine) and
+- **rules/**: the canon rule pack for coding agents (rules/CLAUDE.md for
+  Claude-family assistants, rules/README.md for everyone). The pack covers
+  the migration loop: read the contract, change the target, run
+  `bylazora-core migrate verify`, read the diff, repeat. Only the
+  validator marks a run proven.
+- **template/**: the shape `bylazora-core migrate new` generates for one
+  job, worked: SPEC.json, the reference capture script, verify.sh, and the
+  migrated Rust target from the public batch-txn sample. Copy it as a
+  reference while your agent writes the real logic.
+- **index.js**: exports the version and the absolute paths `rulesPath` and
+  `templatePath`, so an agent harness can locate the bundled files
+  directly.
+
+The engine itself, the validator, the bench runtime, the migrate routine,
+and the MCP server (`bylazora-core mcp`), is the Rust crate
+**bylazora-core**: https://crates.io/crates/bylazora-core, developed at
+https://github.com/bylazora/bylazora under AGPL-3.0-or-later (engine) and
 Apache-2.0 (the copybook and DB2 parsers).
 
 ## The engine in one paragraph
@@ -18,8 +32,11 @@ One Rust binary runs the equivalence gate and the production runtime across
 three compute tiers: CPU, any GPU through vendor-neutral wgpu, and CUDA.
 Measured at one billion rows against the compiled COBOL reference: 28.1x on
 CPU, 61.3x on wgpu, 68.8x on CUDA, every run byte-identical. Money stays
-integer cents and is never a float.
+integer cents and is never a float. The engine is free and unlimited under
+AGPL: a licence key, when installed, is a licensee record for the run
+record and the audit, never a gate.
 
 - Homepage: https://bylazora.com
 - Repository: https://github.com/bylazora/bylazora
 - Evidence annex: https://bylazora.com/evidence.html
+

package/index.js

@@ -1,17 +1,25 @@
 "use strict";
 
-// Reserves the `bylazora` package name on npm.
+// The `bylazora` package: the agent-facing companion to the bylazora-core
+// engine. It ships the canon rule packs and the migrate workspace template,
+// so a coding assistant can find them without scraping the repository.
 //
 // Bylazora is the byte-exact mainframe migration standard: a migrated
 // workload's outputs must equal the legacy COBOL reference byte for byte, or
-// the gate fails it. The engine itself is a Rust crate, developed and released
-// at https://github.com/bylazora/bylazora . This package will carry the MCP
-// client and the agent rule packs that let a coding assistant drive the engine
-// while the validator, and only the validator, decides what is proven.
+// the gate fails it. The engine (validator, bench runtime, migrate routine,
+// MCP server) is the Rust crate bylazora-core, developed and released at
+// https://github.com/bylazora/bylazora . The validator, and only the
+// validator, decides what is proven.
+
+const path = require("path");
 
 module.exports = {
-  version: "0.4.1",
+  version: "0.5.1",
   repository: "https://github.com/bylazora/bylazora",
   homepage: "https://bylazora.com",
-  note: "Name reservation. The MCP client and rule packs ship here."
+  // Absolute paths to the bundled assets, for agents that want to copy
+  // them into a job workspace or a repository's agent configuration.
+  rulesPath: path.join(__dirname, "rules"),
+  templatePath: path.join(__dirname, "template")
 };
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bylazora",
-  "version": "0.4.1",
-  "description": "Byte-exact mainframe migration: MCP client and agent rule packs for the open-source Bylazora engine and gate.",
+  "version": "0.5.1",
+  "description": "Byte-exact mainframe migration: agent rule packs and the migrate workspace template for the open-source Bylazora engine and gate.",
   "license": "AGPL-3.0-or-later",
   "repository": {
     "type": "git",
@@ -19,9 +19,12 @@
   "main": "index.js",
   "files": [
     "index.js",
-    "README.md"
+    "README.md",
+    "rules",
+    "template"
   ],
   "engines": {
     "node": ">=18"
   }
 }
+

package/rules/CLAUDE.md

@@ -0,0 +1,51 @@
+# Bylazora: rules for agents working on migrations
+
+You are working on a migration that will be certified by the Bylazora gate.
+The gate is absolute. These rules are not guidance; violating them fails the job.
+
+## The invariants
+
+1. The validator is the only authority that marks a run proven. A run is
+   proven when and only when every declared output file is byte-identical to
+   the legacy reference. No tool parameter, script, prompt, or confidence
+   score can mark a run proven.
+2. Money is integer cents, end to end. Never float, never double, never
+   rounding beyond the declared fixed-point precision. If a path cannot hold
+   exact integer arithmetic, stop and say so.
+3. Byte-exact means byte-exact: headers, field widths, ordering, totals rows,
+   line endings. A single differing byte is a failure with a diff.
+4. Reproducible or rejected: fixed seeds, same input yields the same output,
+   warm and cold runs agree.
+5. Never weaken the gate to make a run pass. No tolerance flags, no skipped
+   files, no partial comparisons. A missing reference means unvalidated -
+   never proven.
+
+## How you work
+
+- Draft, then run, then read the verdict. Use the MCP tools: bench (cpu, gpu,
+  cuda) and validate.
+- A MISMATCH is a diff to fix, never a threshold to tune.
+- Propose measurements, run them, report them with the run record. Do not
+  report a performance number without a recorded run.
+
+## The migration loop
+
+A migration is a workspace generated by `bylazora-core migrate new`. Inside it:
+
+- SPEC.json is the contract: declared inputs and outputs.
+- reference/ is sealed. Never edit it; the seal hash sits in SPEC.json, and
+  the verify step compares against the sealed copy.
+- target/rust/src/main.rs is the only file the logic belongs in. It takes
+  (input_dir, output_dir), reads the declared inputs, writes the declared
+  outputs. Everything else is scaffolding; leave it alone.
+- Run `bylazora-core migrate verify <job>` to build, run and gate. The
+  verdict record lands in runs/ and is never overwritten, which is what makes
+  the trail an audit artefact.
+- A MISMATCH is a diff to fix, never a threshold to tune.
+- The MCP tools migrate_verify and migrate_status drive the same loop from
+  inside your session.
+
+## The licence boundary
+
+The engine is AGPL-3.0-or-later; the parsers are Apache-2.0. Do not claim the
+gate passed when it did not; the run record is the audit trail.

package/rules/README.md

@@ -0,0 +1,63 @@
+# agents/
+
+The rule pack for AI coding agents that work on a Bylazora migration. Give an
+agent these rules and it knows the invariants; the gate still disposes of
+whatever it drafts. The agent proposes; the gate disposes.
+
+## What is here
+
+`CLAUDE.md` is the canonical pack. Deliberately one file of plain markdown, not
+one file per tool.
+
+## Installing it into your migration repository
+
+Every agent tool reads its instructions from a different path, and those paths
+move: `.cursorrules` was Cursor's legacy format and is now `.cursor/rules/*.mdc`,
+Copilot reads `.github/copilot-instructions.md`, and `AGENTS.md` has become the
+cross-tool convention. Shipping a copy per tool would mean shipping files that
+are wrong within a year and disagree with each other in the meantime.
+
+So copy the contents of `CLAUDE.md` into whichever file your tool reads:
+
+| Tool | Commonly read | Notes |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | at the repository root |
+| Most agents | `AGENTS.md` | the emerging cross-tool convention |
+| Cursor | `.cursor/rules/*.mdc` | rules can be scoped to a glob; `.cursorrules` is legacy |
+| GitHub Copilot | `.github/copilot-instructions.md` | repository-wide, with path-specific instructions also supported |
+
+Check your tool's current documentation rather than trusting this table: it is
+the part of this repository most likely to age badly, which is exactly why the
+pack is not split per tool.
+
+**If your repository already has one of those files, merge the invariants into
+it. Do not replace it.** Your file knows things about your estate that this pack
+does not.
+
+## If you are writing your own
+
+The five invariants are the non-negotiable part. Copy them verbatim, because
+each one is enforced by the gate rather than being a matter of taste:
+
+1. the validator is the only authority that marks a run proven;
+2. money is integer cents, end to end, never float;
+3. byte-exact means headers, field widths, ordering, totals rows and line endings;
+4. reproducible, or rejected;
+5. never weaken the gate to make a run pass.
+
+Everything after that - how the agent works, which tools it calls, the licence
+boundary - is yours to fit to the estate. Keep the rule about run records: a
+performance number without a recorded run is not a number.
+
+## The migration loop
+
+The pack pairs with the migration routine: `bylazora-core migrate new`
+scaffolds a gated workspace, the agent writes the logic into
+`target/rust/src/main.rs`, and `bylazora-core migrate verify` is the only
+thing that can mark the job proven. The same loop runs over MCP
+(migrate_verify, migrate_status).
+
+## Keeping it current
+
+The pack names the engine's CLI and MCP tools. If you pin a version, check that
+list against `bylazora-core --help` when you upgrade.

package/template/README.md

@@ -0,0 +1,20 @@
+# The migrate workspace template
+
+This directory mirrors what `bylazora-core migrate new` scaffolds for one
+job, worked with the public batch-txn sample. The inputs and the sealed
+reference outputs are not bundled here; the complete, proven workspace
+lives in the repository at sample/, where the verdict trail shows the gate
+passing.
+
+Copy this shape, then:
+
+1. Read SPEC.json: the job name, the declared inputs and outputs, the
+   copybook schema, and the sealed reference hash.
+2. Write the migrated logic in target/rust/src/main.rs. The contract is
+   argv[1] = input directory, argv[2] = output directory; read the declared
+   inputs, write the declared outputs.
+3. Seal the legacy reference: `bylazora-core migrate reference <job>`
+   (this runs reference/capture.sh and refuses to reseal without --force).
+4. Run the gate: `bylazora-core migrate verify <job>`. Read the diff, fix
+   the mismatch, repeat. Only the validator marks a run proven.
+

package/template/SPEC.json

@@ -0,0 +1,107 @@
+{
+  "name": "batch-txn",
+  "language": "rust",
+  "inputs": [
+    {
+      "path": "transactions.csv",
+      "format": "csv"
+    },
+    {
+      "path": "balances.csv",
+      "format": "csv"
+    }
+  ],
+  "outputs": [
+    "final_balances.csv",
+    "summary_report.csv"
+  ],
+  "schema": [
+    {
+      "children": [
+        {
+          "children": [],
+          "fixed_point": false,
+          "kind": "display",
+          "length": 7,
+          "level": 5,
+          "name": "TXN-ACCOUNT",
+          "occurs": 1,
+          "offset": 0,
+          "scale": 0,
+          "signed": false
+        },
+        {
+          "children": [],
+          "fixed_point": false,
+          "kind": "display",
+          "length": 7,
+          "level": 5,
+          "name": "TXN-AMOUNT",
+          "occurs": 1,
+          "offset": 7,
+          "scale": 0,
+          "signed": false
+        },
+        {
+          "children": [],
+          "fixed_point": false,
+          "kind": "display",
+          "length": 1,
+          "level": 5,
+          "name": "TXN-TYPE",
+          "occurs": 1,
+          "offset": 14,
+          "scale": 0,
+          "signed": false
+        }
+      ],
+      "fixed_point": false,
+      "kind": "group",
+      "length": 15,
+      "level": 1,
+      "name": "TXN-REC",
+      "occurs": 1,
+      "offset": 0,
+      "scale": 0,
+      "signed": false
+    },
+    {
+      "children": [
+        {
+          "children": [],
+          "fixed_point": false,
+          "kind": "display",
+          "length": 7,
+          "level": 5,
+          "name": "BAL-ACCOUNT",
+          "occurs": 1,
+          "offset": 0,
+          "scale": 0,
+          "signed": false
+        },
+        {
+          "children": [],
+          "fixed_point": false,
+          "kind": "display",
+          "length": 12,
+          "level": 5,
+          "name": "BAL-AMOUNT",
+          "occurs": 1,
+          "offset": 7,
+          "scale": 0,
+          "signed": true
+        }
+      ],
+      "fixed_point": false,
+      "kind": "group",
+      "length": 19,
+      "level": 1,
+      "name": "BAL-REC",
+      "occurs": 1,
+      "offset": 15,
+      "scale": 0,
+      "signed": false
+    }
+  ],
+  "sealed_reference_sha256": "1d2a70cf0770cff8e49e9a3b363bd640e8239a9b36be9d70a9a894c159df1ffd"
+}

package/template/reference/capture.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# The reference capture: compile the legacy COBOL with GnuCOBOL and run it
+# on the declared inputs. `bylazora-core migrate reference` executes this
+# script and seals whatever it leaves in output/ as the byte-level contract.
+set -euo pipefail
+cd "$(dirname "$0")"
+mkdir -p output
+rm -f output/*
+cobc -free -x -O2 -o /tmp/batch-txn-reference ../legacy/BATCHTXN.cob
+/tmp/batch-txn-reference ../input/transactions.csv ../input/balances.csv output

package/template/target/rust/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "batch-txn"
+version = "0.1.0"
+edition = "2021"
+
+[[bin]]
+name = "batch-txn"
+path = "src/main.rs"

package/template/target/rust/README.md

@@ -0,0 +1,6 @@
+# batch-txn: rules for whoever writes the logic
+
+The contract is SPEC.json. The gate is absolute: only
+`bylazora-core migrate verify` (which calls the validator) marks a run
+proven. Run it often; read the diff; a MISMATCH is a diff to fix, never a
+threshold to tune. The canon rules live in the agents/ rule pack.

package/template/target/rust/src/main.rs

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The migrated BATCHTXN application, in Rust. The workspace skeleton was
+// generated by `bylazora-core migrate new`; this file is the migration
+// work. Contract: argv[1] = input directory, argv[2] = output directory.
+// Read the declared inputs from argv[1], write the declared outputs to
+// argv[2]. The gate compares the outputs against the sealed COBOL
+// reference byte for byte, so one differing byte is a failure with a diff.
+//
+// Semantics mirror the legacy program exactly:
+// - balances.csv defines the account domain (ACCOUNT_ID,BALANCE_CENTS)
+// - transactions.csv applies deposits (D) and withdrawals (anything else)
+//   in integer cents
+// - final_balances.csv: ACCOUNT_ID,BALANCE_CENTS, one row per account
+// - summary_report.csv: per-account TOTAL_DEPOSITS, TOTAL_WITHDRAWALS,
+//   TXN_COUNT, ENDING_BALANCE, then one grand-totals row with account id -1
+use std::env;
+use std::fs;
+
+fn parse_i64(field: &str) -> i64 {
+    let mut v: i64 = 0;
+    for c in field.bytes() {
+        v = v * 10 + (c - b'0') as i64;
+    }
+    v
+}
+
+fn main() {
+    let args: Vec<String> = env::args().collect();
+    let input_dir = &args[1];
+    let output_dir = &args[2];
+    fs::create_dir_all(output_dir).expect("output dir");
+
+    // Balances define the account domain.
+    let mut starting: Vec<i64> = Vec::new();
+    let balances = fs::read_to_string(format!("{}/balances.csv", input_dir))
+        .expect("balances.csv");
+    for line in balances.lines().skip(1) {
+        let line = line.trim_end_matches('\r');
+        if line.is_empty() {
+            continue;
+        }
+        let f: Vec<&str> = line.split(',').collect();
+        let id = parse_i64(f[0]) as usize;
+        let balance = parse_i64(f[1]);
+        if starting.len() <= id {
+            starting.resize(id + 1, 0);
+        }
+        starting[id] = balance;
+    }
+    let n_acct = starting.len();
+
+    // Transactions: D deposits, anything else withdraws. Integer cents.
+    let mut deposits = vec![0i64; n_acct];
+    let mut withdrawals = vec![0i64; n_acct];
+    let mut counts = vec![0i64; n_acct];
+    let transactions = fs::read_to_string(format!("{}/transactions.csv", input_dir))
+        .expect("transactions.csv");
+    for line in transactions.lines().skip(1) {
+        let line = line.trim_end_matches('\r');
+        if line.is_empty() {
+            continue;
+        }
+        let f: Vec<&str> = line.split(',').collect();
+        let id = parse_i64(f[0]) as usize;
+        let amount = parse_i64(f[1]);
+        if f[2].as_bytes()[0] == b'D' {
+            deposits[id] += amount;
+        } else {
+            withdrawals[id] += amount;
+        }
+        counts[id] += 1;
+    }
+
+    // Write the two reports in the legacy program's exact shape.
+    let mut final_balances = String::from("ACCOUNT_ID,BALANCE_CENTS\n");
+    let mut summary = String::from(
+        "ACCOUNT_ID,TOTAL_DEPOSITS,TOTAL_WITHDRAWALS,TXN_COUNT,ENDING_BALANCE\n",
+    );
+    let (mut total_dep, mut total_wd, mut total_cnt, mut total_end) =
+        (0i64, 0i64, 0i64, 0i64);
+    for i in 0..n_acct {
+        let d = deposits[i];
+        let w = withdrawals[i];
+        let c = counts[i];
+        let e = starting[i] + d - w;
+        final_balances.push_str(&format!("{},{}\n", i, e));
+        summary.push_str(&format!("{},{},{},{},{}\n", i, d, w, c, e));
+        total_dep += d;
+        total_wd += w;
+        total_cnt += c;
+        total_end += e;
+    }
+    summary.push_str(&format!(
+        "-1,{},{},{},{}\n",
+        total_dep, total_wd, total_cnt, total_end
+    ));
+
+    fs::write(
+        format!("{}/final_balances.csv", output_dir),
+        final_balances,
+    )
+    .expect("write final_balances.csv");
+    fs::write(format!("{}/summary_report.csv", output_dir), summary)
+        .expect("write summary_report.csv");
+}

package/template/verify.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Runs the full gate for this job: build the target, run it on the declared
+# inputs, and byte-compare its outputs against the sealed reference.
+set -euo pipefail
+exec bylazora-core migrate verify "$(cd "$(dirname "$0")" && pwd)"