@fraczak/k 6.3.3 → 6.4.0

package/objects/README.md

@@ -7,17 +7,24 @@ CLI tools for compiling and inspecting k object files (`.ko`) and library files
 ### `k-compile`
 
 Compiles `.k` source into an executable object file (`.ko`), library file
-(`.klib`), or kVM JSON (`.kvm`). Output format is inferred from the output
-extension, or from `--format`.
+(`.klib`), or polymorphic kVM backend artifact (`.kvm`). Output format is
+inferred from the output extension, or from `--format`.
 
 ```bash
-k-compile [--lib lib-file] [--format ko|klib|kvm] [source-snippet | input-file [output-file]]
+k-compile [--lib lib-file] [--export spec]... [--format ko|klib|kvm] [source-snippet | input-file [output-file]]
 ```
 
 Existing input paths are read as files. A non-existing input with `.k`, `.ko`,
 or `.klib` extension is reported as a missing file; otherwise it is compiled as
 inline k source, in the same style as `k.mjs`.
 
+`.kvm` is a polymorphic kVM template artifact (`layer: "KVM-P"`). It carries the
+relational function definitions, their principal input/output pattern graphs, and
+lowered kVM instruction streams ready for runtime specialization when enveloped
+values arrive. Specialization occurs when functions are invoked on concrete values,
+eliminating the need for ahead-of-time input pattern or input type flags. Names from
+a `--lib` dependency can be imported into the entry scope using `--export (oldname:)?newname`.
+
 ### `k-decompile`
 
 Decompiles a `.ko` or `.klib` back into human-readable k source.
@@ -36,6 +43,27 @@ alias name and `compiledAt`.
 k-extract-aliases [object-file [k-file]]
 ```
 
+### `k-inspect-object`
+
+Inspects a `.ko` or `.klib`. By default it prints a compact object summary.
+With `--kir`, it prints the current KIR-P export used by backend experiments.
+
+```bash
+k-inspect-object [--summary | --kir] [object-file]
+```
+
+For scripts that only need KIR-P export, `k-kir [object-file]` is the direct
+exporter backed by `kir.mjs`.
+
+### `k-validate-object`
+
+Validates a `.ko` or `.klib` object and its derived KIR-P export. With
+`--kir`, it validates an already exported KIR-P artifact.
+
+```bash
+k-validate-object [--kir] [input-file]
+```
+
 The installed names are `k-` plus the source basename without `.mjs`. Every
 installed object binary supports `-h` and `--help`.
 
@@ -50,9 +78,15 @@ installed object binary supports `-h` and `--help`.
 - Origin entries do not have `kind`; the metadata entry has `type: "code"` or
   `type: "rel"`.
 - Stored relation bodies do not include generated input/output boundary filters.
+- KIR-P is available as an inspection/export contract; it does not change the
+  stored `.ko` or `.klib` payload.
+- `.kvm` is not a canonical source/object format; it is a polymorphic backend
+  template artifact (`layer: "KVM-P"`), lowered from KIR-P for runtime execution
+  and JIT specialization.
 
 ## Further reading
 
 - [DOCS/OBJECT_FILE_AND_PATTERN.md](../DOCS/OBJECT_FILE_AND_PATTERN.md) — object file format and pattern encoding
+- [DOCS/KIR_V1.md](../DOCS/KIR_V1.md) — KIR-P inspection/export contract for backends
 - [DOCS/TYPE_DERIVATION.md](../DOCS/TYPE_DERIVATION.md) — type derivation (what compilation skips when loading a `.ko`/`.klib`)
 - [DOCS/CONVERGENCE.md](../DOCS/CONVERGENCE.md) — convergence strategies for type inference

package/objects/compile.mjs

@@ -5,12 +5,12 @@ import path from "node:path";
 import { argv, exit, stdin, stdout } from "node:process";
 import {
   compileObjectBuffer,
+  compileLibrary,
   compileLibraryBuffer,
   decodeObject,
   loadLibrary
 } from "../object.mjs";
-import { lowerToKVM } from "../kvm.mjs";
-import { annotate } from "../index.mjs";
+import { objectToKVMArtifact } from "../kvm.mjs";
 
 function helpText() {
   return [
@@ -25,7 +25,7 @@ function helpText() {
     "  output-file     Output path (.ko, .klib, or .kvm). Writes to stdout when omitted.",
     "",
     "Options:",
-    "  --lib file       Load one .klib dependency before compiling.",
+    "  --lib file       Load one .klib or .k library dependency before compiling.",
     "  --export spec    Export a library alias into the source scope. May be repeated.",
     "                   spec is 'name' or 'libname:localname'.",
     "  --format fmt     Output format: ko, klib, or kvm. Overrides extension detection.",
@@ -35,15 +35,15 @@ function helpText() {
     "or .klib extension is reported as a missing file; otherwise it is compiled",
     "as inline k source.",
     "",
-    "When input is .ko and output is .kvm, the object's relations are lowered",
-    "to kVM. A .klib input can only be copied to .klib output.",
+    ".kvm is a polymorphic kVM template artifact (layer: KVM-P).",
+    "A .klib input can only be copied to .klib output.",
     "",
     "Examples:",
     `  ${argv[1]} 'x = |x; x x'`,
     `  ${argv[1]} program.k program.ko`,
     `  ${argv[1]} program.k program.klib`,
     `  ${argv[1]} program.k program.kvm`,
-    `  ${argv[1]} program.ko program.kvm`,
+    `  ${argv[1]} --lib Examples/arithmetics.k --export plus:+ --export succ --export int '{succ int x,int y}+' a.kvm`,
     `  ${argv[1]} --lib core.klib --export add --export mul:times program.k program.ko`
   ].join("\n");
 }
@@ -131,21 +131,8 @@ function buildExportPreamble(exports, libraries) {
   return lines.join("\n") + "\n";
 }
 
-function compileToKVM(source, options) {
-  const defs = annotate(source, options);
-  const kvmProgram = {};
-  for (const [name, relDef] of Object.entries(defs.rels)) {
-    kvmProgram[name] = lowerToKVM(relDef, name);
-  }
-  return JSON.stringify(kvmProgram, null, 2) + "\n";
-}
-
 function objectToKVM(object) {
-  const kvmProgram = {};
-  for (const [name, relDef] of Object.entries(object.rels)) {
-    kvmProgram[name] = lowerToKVM(relDef, name);
-  }
-  return JSON.stringify(kvmProgram, null, 2) + "\n";
+  return JSON.stringify(objectToKVMArtifact(object), null, 2) + "\n";
 }
 
 try {
@@ -169,7 +156,12 @@ try {
       const libPath = args.shift();
       if (!libPath) throw new Error("--lib requires a file argument");
       if (libraries.length > 0) throw new Error("--lib may be specified at most once");
-      libraries.push(loadLibrary(decodeObject(fs.readFileSync(libPath))));
+      const ext = path.extname(libPath).toLowerCase();
+      if (ext === ".k") {
+        libraries.push(loadLibrary(compileLibrary(fs.readFileSync(libPath, "utf8"), { source: libPath })));
+      } else {
+        libraries.push(loadLibrary(decodeObject(fs.readFileSync(libPath))));
+      }
     } else if (args[0] === "--export") {
       args.shift();
       const spec = args.shift();
@@ -241,7 +233,8 @@ try {
     } else if (outputFormat === "klib") {
       output = compileLibraryBuffer(source, opts);
     } else if (outputFormat === "kvm") {
-      output = compileToKVM(source, opts);
+      const object = decodeObject(compileObjectBuffer(source, opts));
+      output = objectToKVM(object);
     }
   }
 

package/objects/inspect.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit, stdin, stdout } from "node:process";
+import { decodeObject } from "../object.mjs";
+import { objectToKIRP } from "../kir.mjs";
+
+function helpText() {
+  return [
+    "Inspect a k .ko or .klib object.",
+    "",
+    `Usage: ${argv[1]} [options] [object-file]`,
+    "",
+    "Arguments:",
+    "  object-file    Input .ko or .klib file. Reads from stdin when omitted.",
+    "",
+    "Options:",
+    "  --kir          Print the KIR-P JSON view.",
+    "  --summary      Print a compact section summary. This is the default.",
+    "  -h, --help     Show this help.",
+    "",
+    "KIR-P is an inspection/export view; it does not change the stored object format."
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
+}
+
+async function readStdinBytes() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+function inspectSummary(object) {
+  const relationEntries = Object.entries(object.rels || {});
+  const codeCount = Object.keys(object.codes || {}).length;
+  const aliasCount = Object.keys(object.relAlias || {}).length;
+  const metaCount = Object.keys(object.meta || {}).length;
+  const statuses = new Map();
+  for (const [, rel] of relationEntries) {
+    const status = rel.typeDerivation?.status || "unknown";
+    statuses.set(status, (statuses.get(status) || 0) + 1);
+  }
+
+  return [
+    `format: ${object.format}`,
+    `kind: ${object.main == null ? "library" : "executable"}`,
+    `main: ${object.main ?? "null"}`,
+    `codes: ${codeCount}`,
+    `relations: ${relationEntries.length}`,
+    `aliases: ${aliasCount}`,
+    `metadata entries: ${metaCount}`,
+    `type derivation: ${[...statuses.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`
+  ].join("\n") + "\n";
+}
+
+try {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
+  let mode = "summary";
+  while (args.length > 0 && args[0].startsWith("--")) {
+    const option = args.shift();
+    if (option === "--kir") {
+      mode = "kir";
+    } else if (option === "--summary") {
+      mode = "summary";
+    } else {
+      throw new Error(`Unknown option: ${option}`);
+    }
+  }
+
+  const inputPath = args.shift() || null;
+  if (args.length > 0) {
+    throw new Error(`Unexpected argument: ${args[0]}`);
+  }
+
+  const buffer = inputPath == null ? await readStdinBytes() : fs.readFileSync(inputPath);
+  const object = decodeObject(buffer);
+  if (mode === "kir") {
+    stdout.write(JSON.stringify(objectToKIRP(object), null, 2) + "\n");
+  } else {
+    stdout.write(inspectSummary(object));
+  }
+} catch (error) {
+  console.error(error.message || String(error));
+  usage();
+  exit(1);
+}

package/objects/validate.mjs

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit, stdin, stdout } from "node:process";
+import { decodeObject } from "../object.mjs";
+import { KIR_FORMAT, KIR_VERSION, objectToKIRP } from "../kir.mjs";
+import { isIntrinsic } from "../intrinsics.mjs";
+
+const TYPE_DERIVATION_STATUSES = new Set(["converged", "not-converged", "unknown"]);
+const KIR_PATTERN_KINDS = new Set([
+  "any",
+  "open-product",
+  "closed-product",
+  "open-union",
+  "closed-union",
+  "type"
+]);
+const KIR_OPS = new Set([
+  "identity",
+  "empty",
+  "dot",
+  "div",
+  "vid",
+  "code",
+  "filter",
+  "ref",
+  "comp",
+  "union",
+  "product"
+]);
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertObject(value, path) {
+  if (!isObject(value)) fail(`${path} must be an object`);
+}
+
+function assertString(value, path) {
+  if (typeof value !== "string") fail(`${path} must be a string`);
+}
+
+function assertArray(value, path) {
+  if (!Array.isArray(value)) fail(`${path} must be an array`);
+}
+
+function assertInteger(value, path) {
+  if (!Number.isInteger(value)) fail(`${path} must be an integer`);
+}
+
+function validateStatus(status, path) {
+  if (!TYPE_DERIVATION_STATUSES.has(status)) {
+    fail(`${path} must be one of ${[...TYPE_DERIVATION_STATUSES].join(", ")}`);
+  }
+}
+
+function validateObjectExp(exp, path, relNames, codeNames) {
+  assertObject(exp, path);
+  assertString(exp.op, `${path}.op`);
+
+  if (exp.patterns != null) {
+    assertArray(exp.patterns, `${path}.patterns`);
+    exp.patterns.forEach((id, index) => assertInteger(id, `${path}.patterns[${index}]`));
+  }
+
+  switch (exp.op) {
+    case "identity":
+    case "empty":
+      break;
+    case "dot":
+      assertString(exp.dot, `${path}.dot`);
+      break;
+    case "div":
+      assertString(exp.div, `${path}.div`);
+      break;
+    case "vid":
+      assertString(exp.vid, `${path}.vid`);
+      break;
+    case "code":
+      assertString(exp.code, `${path}.code`);
+      if (!codeNames.has(exp.code)) fail(`${path}.code references missing code ${exp.code}`);
+      break;
+    case "filter":
+      validateObjectFilter(exp.filter, `${path}.filter`, codeNames);
+      break;
+    case "ref":
+      assertString(exp.ref, `${path}.ref`);
+      if (!isIntrinsic(exp.ref) && !relNames.has(exp.ref)) {
+        fail(`${path}.ref references missing relation ${exp.ref}`);
+      }
+      break;
+    case "comp":
+      assertArray(exp.comp, `${path}.comp`);
+      exp.comp.forEach((child, index) => validateObjectExp(child, `${path}.comp[${index}]`, relNames, codeNames));
+      break;
+    case "union":
+      assertArray(exp.union, `${path}.union`);
+      exp.union.forEach((child, index) => validateObjectExp(child, `${path}.union[${index}]`, relNames, codeNames));
+      break;
+    case "product":
+      assertArray(exp.product, `${path}.product`);
+      exp.product.forEach((field, index) => {
+        assertObject(field, `${path}.product[${index}]`);
+        assertString(field.label, `${path}.product[${index}].label`);
+        validateObjectExp(field.exp, `${path}.product[${index}].exp`, relNames, codeNames);
+      });
+      break;
+    default:
+      fail(`${path}.op has unsupported value ${exp.op}`);
+  }
+}
+
+function validateObjectFilter(filter, path, codeNames) {
+  assertObject(filter, path);
+  if (filter.type === "code") {
+    assertString(filter.code, `${path}.code`);
+    if (!codeNames.has(filter.code)) fail(`${path}.code references missing code ${filter.code}`);
+  }
+  if (filter.fields != null) {
+    assertObject(filter.fields, `${path}.fields`);
+    for (const [label, child] of Object.entries(filter.fields)) {
+      validateObjectFilter(child, `${path}.fields.${label}`, codeNames);
+    }
+  }
+}
+
+function validateTypePatternGraph(graph, path, codeNames) {
+  assertObject(graph, path);
+  const nodes = graph.patterns?.nodes;
+  const parent = graph.patterns?.parent;
+  assertArray(nodes, `${path}.patterns.nodes`);
+  assertArray(parent, `${path}.patterns.parent`);
+  if (parent.length > nodes.length) {
+    fail(`${path}.patterns.parent length must not exceed nodes length`);
+  }
+
+  nodes.forEach((node, index) => {
+    assertObject(node, `${path}.patterns.nodes[${index}]`);
+    assertString(node.pattern, `${path}.patterns.nodes[${index}].pattern`);
+    if (node.pattern === "type") {
+      assertString(node.type, `${path}.patterns.nodes[${index}].type`);
+      if (!codeNames.has(node.type)) fail(`${path}.patterns.nodes[${index}].type references missing code ${node.type}`);
+    }
+  });
+
+  parent.forEach((parentId, index) => {
+    if (parentId == null) return;
+    assertInteger(parentId, `${path}.patterns.parent[${index}]`);
+    if (parentId < 0 || parentId >= nodes.length) fail(`${path}.patterns.parent[${index}] is out of range`);
+  });
+
+  assertArray(graph.edges, `${path}.edges`);
+  if (graph.edges.length > nodes.length) {
+    fail(`${path}.edges length must not exceed nodes length`);
+  }
+  graph.edges.forEach((edges, source) => {
+    if (edges == null) return;
+    assertObject(edges, `${path}.edges[${source}]`);
+    for (const [label, dests] of Object.entries(edges)) {
+      assertString(label, `${path}.edges[${source}] label`);
+      assertArray(dests, `${path}.edges[${source}].${label}`);
+      dests.forEach((target, index) => {
+        assertInteger(target, `${path}.edges[${source}].${label}[${index}]`);
+        if (target < 0 || target >= nodes.length) fail(`${path}.edges[${source}].${label}[${index}] is out of range`);
+      });
+    }
+  });
+
+  assertObject(graph.codeId || {}, `${path}.codeId`);
+  for (const [code, id] of Object.entries(graph.codeId || {})) {
+    if (!codeNames.has(code)) fail(`${path}.codeId references missing code ${code}`);
+    assertInteger(id, `${path}.codeId.${code}`);
+    if (id < 0 || id >= nodes.length) fail(`${path}.codeId.${code} is out of range`);
+  }
+}
+
+export function validateObjectPayload(object) {
+  assertObject(object, "object");
+  if (object.format !== "k-object") fail("object.format must be k-object");
+  assertObject(object.codes || {}, "object.codes");
+  assertObject(object.rels || {}, "object.rels");
+  assertObject(object.relAlias || {}, "object.relAlias");
+  assertObject(object.meta || {}, "object.meta");
+  assertObject(object.compileStats || {}, "object.compileStats");
+
+  if (object.main != null) {
+    assertString(object.main, "object.main");
+    if (!(object.main in object.rels)) fail(`object.main references missing relation ${object.main}`);
+  }
+
+  const codeNames = new Set(Object.keys(object.codes || {}));
+  const relNames = new Set(Object.keys(object.rels || {}));
+
+  for (const [name, hash] of Object.entries(object.relAlias || {})) {
+    assertString(name, `object.relAlias key ${name}`);
+    assertString(hash, `object.relAlias.${name}`);
+    if (!relNames.has(hash) && !relNames.has(name) && !hash.startsWith("@")) {
+      fail(`object.relAlias.${name} references missing relation ${hash}`);
+    }
+  }
+
+  for (const [name, rel] of Object.entries(object.rels || {})) {
+    assertObject(rel, `object.rels.${name}`);
+    validateObjectExp(rel.def, `object.rels.${name}.def`, relNames, codeNames);
+    assertObject(rel.typeDerivation || {}, `object.rels.${name}.typeDerivation`);
+    validateStatus(rel.typeDerivation?.status || "unknown", `object.rels.${name}.typeDerivation.status`);
+    validateTypePatternGraph(rel.typePatternGraph, `object.rels.${name}.typePatternGraph`, codeNames);
+  }
+
+  for (const [hash, entry] of Object.entries(object.meta || {})) {
+    assertObject(entry, `object.meta.${hash}`);
+    if (entry.type !== "code" && entry.type !== "rel") fail(`object.meta.${hash}.type must be code or rel`);
+    assertArray(entry.origins || [], `object.meta.${hash}.origins`);
+  }
+
+  return object;
+}
+
+function validateKirPatterns(patterns, path, nodeCount) {
+  if (patterns == null) return;
+  assertArray(patterns, path);
+  patterns.forEach((id, index) => {
+    assertInteger(id, `${path}[${index}]`);
+    if (id < 0 || id >= nodeCount) fail(`${path}[${index}] is out of range`);
+  });
+}
+
+function validateKIRExp(exp, path, nodeCount, relNames, codeNames) {
+  assertObject(exp, path);
+  assertString(exp.op, `${path}.op`);
+  if (!KIR_OPS.has(exp.op)) fail(`${path}.op has unsupported value ${exp.op}`);
+  validateKirPatterns(exp.patterns, `${path}.patterns`, nodeCount);
+
+  switch (exp.op) {
+    case "identity":
+    case "empty":
+      break;
+    case "dot":
+      assertString(exp.label, `${path}.label`);
+      break;
+    case "div":
+    case "vid":
+      assertString(exp.tag, `${path}.tag`);
+      break;
+    case "code":
+      assertString(exp.code, `${path}.code`);
+      if (!codeNames.has(exp.code)) fail(`${path}.code references missing code ${exp.code}`);
+      break;
+    case "filter":
+      assertObject(exp.filter, `${path}.filter`);
+      break;
+    case "ref":
+      assertString(exp.ref, `${path}.ref`);
+      if (!isIntrinsic(exp.ref) && !relNames.has(exp.ref)) fail(`${path}.ref references missing relation ${exp.ref}`);
+      break;
+    case "comp":
+    case "union":
+      assertArray(exp.items, `${path}.items`);
+      exp.items.forEach((child, index) => validateKIRExp(child, `${path}.items[${index}]`, nodeCount, relNames, codeNames));
+      break;
+    case "product":
+      assertArray(exp.fields, `${path}.fields`);
+      exp.fields.forEach((field, index) => {
+        assertObject(field, `${path}.fields[${index}]`);
+        assertString(field.label, `${path}.fields[${index}].label`);
+        validateKIRExp(field.expr, `${path}.fields[${index}].expr`, nodeCount, relNames, codeNames);
+      });
+      break;
+  }
+}
+
+function validateKIRPatternGraph(patternGraph, path, codeNames) {
+  assertObject(patternGraph, path);
+  assertArray(patternGraph.nodes, `${path}.nodes`);
+  const nodeCount = patternGraph.nodes.length;
+  patternGraph.nodes.forEach((node, index) => {
+    assertObject(node, `${path}.nodes[${index}]`);
+    if (node.id !== index) fail(`${path}.nodes[${index}].id must be ${index}`);
+    if (!KIR_PATTERN_KINDS.has(node.kind)) fail(`${path}.nodes[${index}].kind is unsupported`);
+    if (node.kind === "type") {
+      assertString(node.code, `${path}.nodes[${index}].code`);
+      if (!codeNames.has(node.code)) fail(`${path}.nodes[${index}].code references missing code ${node.code}`);
+    }
+    if (node.edges != null) {
+      assertArray(node.edges, `${path}.nodes[${index}].edges`);
+      node.edges.forEach((edge, edgeIndex) => {
+        assertObject(edge, `${path}.nodes[${index}].edges[${edgeIndex}]`);
+        assertString(edge.label, `${path}.nodes[${index}].edges[${edgeIndex}].label`);
+        assertInteger(edge.target, `${path}.nodes[${index}].edges[${edgeIndex}].target`);
+        if (edge.target < 0 || edge.target >= nodeCount) {
+          fail(`${path}.nodes[${index}].edges[${edgeIndex}].target is out of range`);
+        }
+      });
+    }
+  });
+
+  assertObject(patternGraph.sourceNodeMap || {}, `${path}.sourceNodeMap`);
+  for (const [sourceId, kirId] of Object.entries(patternGraph.sourceNodeMap || {})) {
+    if (!/^\d+$/.test(sourceId)) fail(`${path}.sourceNodeMap key ${sourceId} must be an integer string`);
+    assertInteger(kirId, `${path}.sourceNodeMap.${sourceId}`);
+    if (kirId < 0 || kirId >= nodeCount) fail(`${path}.sourceNodeMap.${sourceId} is out of range`);
+  }
+}
+
+export function validateKIRP(kir) {
+  assertObject(kir, "kir");
+  if (kir.format !== KIR_FORMAT) fail(`kir.format must be ${KIR_FORMAT}`);
+  if (kir.version !== KIR_VERSION) fail(`kir.version must be ${KIR_VERSION}`);
+  if (kir.layer !== "KIR-P") fail("kir.layer must be KIR-P");
+  if (kir.kind !== "executable" && kir.kind !== "library") fail("kir.kind must be executable or library");
+  assertObject(kir.codes || {}, "kir.codes");
+  assertObject(kir.rels || {}, "kir.rels");
+  assertObject(kir.relAlias || {}, "kir.relAlias");
+  assertObject(kir.compileStats || {}, "kir.compileStats");
+  assertObject(kir.meta || {}, "kir.meta");
+
+  if (kir.kind === "executable") {
+    assertString(kir.main, "kir.main");
+    if (!(kir.main in kir.rels)) fail(`kir.main references missing relation ${kir.main}`);
+  } else if (kir.main !== null) {
+    fail("library KIR must have main: null");
+  }
+
+  const codeNames = new Set(Object.keys(kir.codes || {}));
+  const relNames = new Set(Object.keys(kir.rels || {}));
+
+  for (const [name, rel] of Object.entries(kir.rels || {})) {
+    assertObject(rel, `kir.rels.${name}`);
+    validateStatus(rel.typeDerivation?.status || "unknown", `kir.rels.${name}.typeDerivation.status`);
+    validateKIRPatternGraph(rel.patternGraph, `kir.rels.${name}.patternGraph`, codeNames);
+    const nodeCount = rel.patternGraph.nodes.length;
+    for (const field of ["inputPattern", "outputPattern"]) {
+      if (rel[field] == null) continue;
+      assertInteger(rel[field], `kir.rels.${name}.${field}`);
+      if (rel[field] < 0 || rel[field] >= nodeCount) fail(`kir.rels.${name}.${field} is out of range`);
+    }
+    validateKIRExp(rel.body, `kir.rels.${name}.body`, nodeCount, relNames, codeNames);
+  }
+
+  return kir;
+}
+
+function helpText() {
+  return [
+    "Validate a k .ko/.klib object or KIR-P JSON file.",
+    "",
+    `Usage: ${argv[1]} [options] [input-file]`,
+    "",
+    "Arguments:",
+    "  input-file     Input .ko/.klib file, or KIR JSON with --kir. Reads stdin when omitted.",
+    "",
+    "Options:",
+    "  --kir          Validate input as KIR-P JSON instead of a k object.",
+    "  -h, --help     Show this help.",
+    "",
+    "Object validation also validates the derived KIR-P export view."
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
+}
+
+async function readStdinBytes() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+async function main() {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
+  let mode = "object";
+  while (args.length > 0 && args[0].startsWith("--")) {
+    const option = args.shift();
+    if (option === "--kir") {
+      mode = "kir";
+    } else {
+      throw new Error(`Unknown option: ${option}`);
+    }
+  }
+
+  const inputPath = args.shift() || null;
+  if (args.length > 0) throw new Error(`Unexpected argument: ${args[0]}`);
+
+  const input = inputPath == null ? await readStdinBytes() : fs.readFileSync(inputPath);
+  if (mode === "kir") {
+    validateKIRP(JSON.parse(input.toString("utf8")));
+    stdout.write("OK KIR-P\n");
+    return;
+  }
+
+  const object = validateObjectPayload(decodeObject(input));
+  validateKIRP(objectToKIRP(object));
+  stdout.write(`OK ${object.main == null ? "library" : "object"}\n`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.message || String(error));
+    usage();
+    exit(1);
+  });
+}