percolation-inversion-compiler-ts 0.4.4

package/dist/io/schema.d.ts

@@ -0,0 +1,16 @@
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+declare function schemaNames(): string[];
+declare function schemaByType(typeName?: string): Record<string, unknown>;
+declare function schemaBundle(): {
+    bundle_id: string;
+    schemas: Record<string, Record<string, unknown>>;
+};
+declare function validateData(data: unknown, schema: Record<string, unknown>): ValidationResult;
+declare function validateByType(data: unknown, typeName: string): ValidationResult;
+declare function writeSchema(typeName: string, outputPath: string): void;
+declare function writeAllSchemas(outputDir: string): string[];
+
+export { type ValidationResult, schemaBundle, schemaByType, schemaNames, validateByType, validateData, writeAllSchemas, writeSchema };

package/dist/io/schema.js

@@ -0,0 +1,153 @@
+// src/io/schema.ts
+import {
+  cpSync,
+  existsSync as existsSync2,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { basename, join as join2 } from "path";
+import Ajv2020Module from "ajv/dist/2020.js";
+
+// src/core/json.ts
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJson(item));
+  }
+  if (value && typeof value === "object") {
+    const input = value;
+    const output = {};
+    for (const key of Object.keys(input).sort()) {
+      const child = input[key];
+      if (child !== void 0) {
+        output[key] = sortJson(child);
+      }
+    }
+    return output;
+  }
+  return value;
+}
+function stableStringify(value) {
+  return `${JSON.stringify(sortJson(value), null, 2)}
+`;
+}
+function parseJsonObject(text, label = "JSON") {
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object`);
+  }
+  return parsed;
+}
+
+// src/io/paths.ts
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+function packageRoot() {
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(join(current, "package.json")) && existsSync(join(current, "schemas"))) {
+      return current;
+    }
+    const next = dirname(current);
+    if (next === current) {
+      break;
+    }
+    current = next;
+  }
+  return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+}
+function schemaDir() {
+  return join(packageRoot(), "schemas");
+}
+
+// src/io/schema.ts
+var PUBLIC_SCHEMA_NAME = /^[A-Za-z][A-Za-z0-9]*$/;
+function assertSchemaTypeName(typeName) {
+  if (!PUBLIC_SCHEMA_NAME.test(typeName)) {
+    throw new Error(`unknown schema type ${JSON.stringify(typeName)}`);
+  }
+}
+function schemaPath(typeName) {
+  assertSchemaTypeName(typeName);
+  return join2(schemaDir(), `${typeName}.schema.json`);
+}
+function schemaNames() {
+  return readdirSync(schemaDir()).filter(
+    (name) => name.endsWith(".schema.json") && name !== "bundle.schema.json"
+  ).map((name) => name.slice(0, -".schema.json".length)).sort();
+}
+function schemaByType(typeName = "Registry") {
+  const path = schemaPath(typeName);
+  if (!existsSync2(path)) {
+    throw new Error(`unknown schema type ${JSON.stringify(typeName)}`);
+  }
+  return parseJsonObject(readFileSync(path, "utf8"), `${typeName} schema`);
+}
+function schemaBundle() {
+  const bundlePath = join2(schemaDir(), "bundle.schema.json");
+  if (existsSync2(bundlePath)) {
+    const bundle = parseJsonObject(
+      readFileSync(bundlePath, "utf8"),
+      "schema bundle"
+    );
+    if (bundle.bundle_id && bundle.schemas && typeof bundle.schemas === "object" && !Array.isArray(bundle.schemas)) {
+      return bundle;
+    }
+  }
+  const schemas = {};
+  for (const name of schemaNames()) {
+    schemas[name] = schemaByType(name);
+  }
+  return {
+    bundle_id: "percolation-inversion-compiler-portability",
+    schemas
+  };
+}
+function validateData(data, schema) {
+  const Ajv2020 = Ajv2020Module;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  const validate = ajv.compile(schema);
+  const valid = Boolean(validate(data));
+  return {
+    valid,
+    errors: valid ? [] : (validate.errors ?? []).map(
+      (error) => `${error.instancePath || "/"} ${error.message ?? "is invalid"}`
+    )
+  };
+}
+function validateByType(data, typeName) {
+  return validateData(data, schemaByType(typeName));
+}
+function writeSchema(typeName, outputPath) {
+  writeFileSync(outputPath, stableStringify(schemaByType(typeName)), "utf8");
+}
+function writeAllSchemas(outputDir) {
+  mkdirSync(outputDir, { recursive: true });
+  const written = [];
+  const files = [
+    ...schemaNames().map((name) => `${name}.schema.json`),
+    "bundle.schema.json",
+    "schema-digest.json"
+  ];
+  for (const file of files) {
+    const source = join2(schemaDir(), file);
+    if (!existsSync2(source)) {
+      continue;
+    }
+    const target = join2(outputDir, file);
+    cpSync(source, target);
+    written.push(basename(target));
+  }
+  return written.sort();
+}
+export {
+  schemaBundle,
+  schemaByType,
+  schemaNames,
+  validateByType,
+  validateData,
+  writeAllSchemas,
+  writeSchema
+};

package/dist/packet/index.d.ts

@@ -0,0 +1,10 @@
+declare function packetEnvelopeFromRuntimeReport(report: Record<string, unknown>): Record<string, unknown>;
+declare function packetEnvelopeFromPath(path: string): Record<string, unknown>;
+declare function readPacketEnvelope(path: string): Record<string, unknown>;
+declare function readPacketOrMerge(path: string): Record<string, unknown>;
+declare function inspectPacketEnvelope(envelope: Record<string, unknown>): Record<string, unknown>;
+declare function mergePacketEnvelopes(envelopes: Array<Record<string, unknown>>): Record<string, unknown>;
+declare function packetLineageDigest(packetOrMerge: Record<string, unknown>): Record<string, unknown>;
+declare function packetToJson(packet: Record<string, unknown>): string;
+
+export { inspectPacketEnvelope, mergePacketEnvelopes, packetEnvelopeFromPath, packetEnvelopeFromRuntimeReport, packetLineageDigest, packetToJson, readPacketEnvelope, readPacketOrMerge };

package/dist/packet/index.js

@@ -0,0 +1,385 @@
+// src/packet/index.ts
+import { createHash } from "crypto";
+import { readFileSync as readFileSync2 } from "fs";
+
+// src/core/json.ts
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJson(item));
+  }
+  if (value && typeof value === "object") {
+    const input = value;
+    const output = {};
+    for (const key of Object.keys(input).sort()) {
+      const child = input[key];
+      if (child !== void 0) {
+        output[key] = sortJson(child);
+      }
+    }
+    return output;
+  }
+  return value;
+}
+function stableStringify(value) {
+  return `${JSON.stringify(sortJson(value), null, 2)}
+`;
+}
+function parseJsonObject(text, label = "JSON") {
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object`);
+  }
+  return parsed;
+}
+
+// src/core/ledger.ts
+function summarizeLedger(ledger) {
+  const summary = {};
+  if (!ledger) {
+    return summary;
+  }
+  for (const coordinate of Object.values(ledger.coordinates ?? {})) {
+    const kind = coordinate.kind ?? "residual";
+    summary[kind] = (summary[kind] ?? 0) + Number(coordinate.value ?? 0);
+  }
+  return Object.fromEntries(
+    Object.entries(summary).sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+
+// src/io/schema.ts
+import {
+  cpSync,
+  existsSync as existsSync2,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { basename, join as join2 } from "path";
+import Ajv2020Module from "ajv/dist/2020.js";
+
+// src/io/paths.ts
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+function packageRoot() {
+  let current = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(join(current, "package.json")) && existsSync(join(current, "schemas"))) {
+      return current;
+    }
+    const next = dirname(current);
+    if (next === current) {
+      break;
+    }
+    current = next;
+  }
+  return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+}
+function schemaDir() {
+  return join(packageRoot(), "schemas");
+}
+
+// src/io/schema.ts
+var PUBLIC_SCHEMA_NAME = /^[A-Za-z][A-Za-z0-9]*$/;
+function assertSchemaTypeName(typeName) {
+  if (!PUBLIC_SCHEMA_NAME.test(typeName)) {
+    throw new Error(`unknown schema type ${JSON.stringify(typeName)}`);
+  }
+}
+function schemaPath(typeName) {
+  assertSchemaTypeName(typeName);
+  return join2(schemaDir(), `${typeName}.schema.json`);
+}
+function schemaByType(typeName = "Registry") {
+  const path = schemaPath(typeName);
+  if (!existsSync2(path)) {
+    throw new Error(`unknown schema type ${JSON.stringify(typeName)}`);
+  }
+  return parseJsonObject(readFileSync(path, "utf8"), `${typeName} schema`);
+}
+function validateData(data, schema) {
+  const Ajv2020 = Ajv2020Module;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  const validate = ajv.compile(schema);
+  const valid = Boolean(validate(data));
+  return {
+    valid,
+    errors: valid ? [] : (validate.errors ?? []).map(
+      (error) => `${error.instancePath || "/"} ${error.message ?? "is invalid"}`
+    )
+  };
+}
+function validateByType(data, typeName) {
+  return validateData(data, schemaByType(typeName));
+}
+
+// src/packet/index.ts
+var COMMAND_MARKERS = [
+  "cmd.exe",
+  "powershell",
+  "bash ",
+  "sh ",
+  "wsl ",
+  "git ",
+  "pip install",
+  "python -m pip",
+  "uv run",
+  "rm -rf",
+  "curl ",
+  "wget "
+];
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function stableDigest(data) {
+  return sha256(JSON.stringify(sortJson(data)));
+}
+function sortedUnique(values) {
+  return [
+    ...new Set(values.filter((value) => Boolean(value)))
+  ].sort();
+}
+function commandLikeStrings(data) {
+  if (typeof data === "string") {
+    const lower = data.toLowerCase();
+    return COMMAND_MARKERS.some((marker) => lower.includes(marker)) ? [data] : [];
+  }
+  if (Array.isArray(data)) {
+    return data.flatMap((item) => commandLikeStrings(item));
+  }
+  if (data && typeof data === "object") {
+    return Object.values(data).flatMap((value) => commandLikeStrings(value));
+  }
+  return [];
+}
+function readTypedJson(path, schema) {
+  const data = parseJsonObject(readFileSync2(path, "utf8"), schema);
+  const validation = validateByType(data, schema);
+  if (!validation.valid) {
+    throw new Error(
+      `${schema} schema-invalid: ${validation.errors.join("; ")}`
+    );
+  }
+  return data;
+}
+function residualCarryForward(reportId, residualSummary, missingObligations, candidateOnlyReasons, settledBlockers, accepted) {
+  return {
+    accepted,
+    candidate_only_reasons: candidateOnlyReasons,
+    missing_obligations: missingObligations,
+    reasons: ["residuals and blockers are preserved during packet export"],
+    report_id: reportId,
+    residual_summary: residualSummary,
+    settled: false,
+    settled_blockers: settledBlockers
+  };
+}
+function packetEnvelopeFromRuntimeReport(report) {
+  const digest = stableDigest(report);
+  const missing = Array.isArray(report.missing_obligations) ? report.missing_obligations.map(String) : [];
+  const residualSummary = summarizeLedger(report.residual_ledger);
+  const candidateOnlyReasons = [
+    "runtime report is exported as diagnostic packet-exchange data",
+    "packet exchange does not route promotion checks"
+  ];
+  const settledBlockers = sortedUnique([
+    "packet exchange is sidecar-only and cannot settle claims",
+    report.settled === true ? null : "source runtime report settled=false",
+    ...missing
+  ]);
+  const reportId = String(report.report_id ?? "runtime-report");
+  return {
+    accepted: report.accepted === true,
+    candidate_only_reasons: candidateOnlyReasons,
+    content: report,
+    content_digest: digest,
+    created_timestamp: "not-recorded",
+    identity_context_summary: {
+      accepted_agent_context_present: false,
+      accepted_public_key_context_present: false
+    },
+    issuer_agent_id: null,
+    issuer_public_key_id: null,
+    lineage_parents: [reportId],
+    missing_obligations: missing,
+    packet_id: `packet-exchange:${reportId}:${digest.slice(0, 12)}`,
+    provenance_summary: {
+      source_report_id: reportId,
+      state_id: String(report.state_id ?? ""),
+      input_id: String(report.input_id ?? "")
+    },
+    reasons: ["exported packet is diagnostic data and is not promoted"],
+    residual_carry_forward: residualCarryForward(
+      `residual-carry-forward:${reportId}`,
+      residualSummary,
+      missing,
+      candidateOnlyReasons,
+      settledBlockers,
+      report.accepted === true
+    ),
+    residual_ledger_summary: residualSummary,
+    safety_invariants: [
+      "packet exchange treats content as inert data",
+      "packet exchange does not execute embedded commands",
+      "packet exchange does not promote packets to settled"
+    ],
+    schema_version: "pic-packet-exchange-v1",
+    settled: false,
+    settled_blockers: settledBlockers,
+    source_kind: "runtime-report",
+    workflow_usable: report.accepted === true
+  };
+}
+function packetEnvelopeFromPath(path) {
+  return packetEnvelopeFromRuntimeReport(
+    readTypedJson(path, "RuntimeStepReport")
+  );
+}
+function readPacketEnvelope(path) {
+  return readTypedJson(path, "PacketExchangeEnvelope");
+}
+function readPacketOrMerge(path) {
+  const data = parseJsonObject(
+    readFileSync2(path, "utf8"),
+    "packet or merge report"
+  );
+  if (Array.isArray(data.packets)) {
+    const validation2 = validateByType(data, "PacketMergeReport");
+    if (!validation2.valid) {
+      throw new Error(
+        `PacketMergeReport schema-invalid: ${validation2.errors.join("; ")}`
+      );
+    }
+    return data;
+  }
+  const validation = validateByType(data, "PacketExchangeEnvelope");
+  if (!validation.valid) {
+    throw new Error(
+      `PacketExchangeEnvelope schema-invalid: ${validation.errors.join("; ")}`
+    );
+  }
+  return data;
+}
+function inspectPacketEnvelope(envelope) {
+  return {
+    accepted: envelope.accepted === true,
+    candidate_only: true,
+    content_digest: String(envelope.content_digest ?? ""),
+    content_treated_as_data: true,
+    embedded_command_like_values: sortedUnique(commandLikeStrings(envelope)),
+    executed_command_count: 0,
+    packet_id: String(envelope.packet_id ?? ""),
+    reasons: [
+      "packet content was inspected as inert data",
+      "embedded command-like strings are not execution authority"
+    ],
+    report_id: `packet-inspection:${String(envelope.packet_id ?? "")}`,
+    settled: false,
+    workflow_usable: envelope.workflow_usable === true
+  };
+}
+function mergePacketEnvelopes(envelopes) {
+  const byDigest = /* @__PURE__ */ new Map();
+  const duplicateIds = [];
+  const duplicateDigests = [];
+  const residualSummary = {};
+  const missing = [];
+  const candidateOnly = [];
+  const blockers = [];
+  for (const envelope of envelopes) {
+    const digest = String(envelope.content_digest ?? "");
+    if (byDigest.has(digest)) {
+      duplicateIds.push(String(envelope.packet_id ?? ""));
+      duplicateDigests.push(digest);
+    } else {
+      byDigest.set(digest, envelope);
+    }
+    for (const [key, value] of Object.entries(
+      envelope.residual_ledger_summary ?? {}
+    )) {
+      residualSummary[key] = (residualSummary[key] ?? 0) + Number(value);
+    }
+    if (Array.isArray(envelope.missing_obligations)) {
+      missing.push(...envelope.missing_obligations.map(String));
+    }
+    if (Array.isArray(envelope.candidate_only_reasons)) {
+      candidateOnly.push(...envelope.candidate_only_reasons.map(String));
+    }
+    if (Array.isArray(envelope.settled_blockers)) {
+      blockers.push(...envelope.settled_blockers.map(String));
+    }
+  }
+  const packets = [...byDigest.values()];
+  return {
+    accepted: packets.length > 0 && packets.every((packet) => packet.accepted === true),
+    candidate_only_preserved: packets.every(
+      (packet) => packet.settled !== true
+    ),
+    duplicate_content_digests: sortedUnique(duplicateDigests),
+    duplicate_packet_ids: sortedUnique(duplicateIds),
+    input_packet_count: envelopes.length,
+    merged_packet_count: packets.length,
+    packets,
+    reasons: ["packet merge is diagnostic-only and does not promote packets"],
+    report_id: "packet-merge-report",
+    residual_carry_forward: residualCarryForward(
+      "residual-carry-forward:packet-merge",
+      Object.fromEntries(Object.entries(residualSummary).sort()),
+      sortedUnique(missing),
+      sortedUnique(candidateOnly),
+      sortedUnique(blockers),
+      packets.length > 0 && packets.every((packet) => packet.accepted === true)
+    ),
+    settled: false,
+    workflow_usable: packets.some((packet) => packet.workflow_usable === true)
+  };
+}
+function packetLineageDigest(packetOrMerge) {
+  const packets = Array.isArray(packetOrMerge.packets) ? packetOrMerge.packets : [packetOrMerge];
+  const residualSummary = {};
+  for (const packet of packets) {
+    for (const [key, value] of Object.entries(
+      packet.residual_ledger_summary ?? {}
+    )) {
+      residualSummary[key] = (residualSummary[key] ?? 0) + Number(value);
+    }
+  }
+  return {
+    accepted: packets.length > 0 && packets.every((packet) => packet.accepted === true),
+    candidate_only: true,
+    content_digests: packets.map(
+      (packet) => String(packet.content_digest ?? "")
+    ),
+    lineage_id: "packet-lineage-digest",
+    packet_ids: packets.map((packet) => String(packet.packet_id ?? "")),
+    parent_edges: Object.fromEntries(
+      packets.map((packet) => [
+        String(packet.packet_id ?? ""),
+        Array.isArray(packet.lineage_parents) ? packet.lineage_parents.map(String) : []
+      ])
+    ),
+    reasons: [
+      "lineage digest is diagnostic-only and preserves candidate status"
+    ],
+    residual_summary: Object.fromEntries(
+      Object.entries(residualSummary).sort()
+    ),
+    settled: false,
+    workflow_usable: packets.some((packet) => packet.workflow_usable === true)
+  };
+}
+function packetToJson(packet) {
+  return stableStringify(packet);
+}
+export {
+  inspectPacketEnvelope,
+  mergePacketEnvelopes,
+  packetEnvelopeFromPath,
+  packetEnvelopeFromRuntimeReport,
+  packetLineageDigest,
+  packetToJson,
+  readPacketEnvelope,
+  readPacketOrMerge
+};

package/fixtures/portability_conformance/README.md

@@ -0,0 +1,17 @@
+# Portability Conformance Pack
+
+This directory contains stable JSON outputs for cross-language implementations.
+Each file is intended to validate against the public schema named in
+`manifest.json`. Manifest SHA-256 values are computed over LF-normalized bytes
+so Windows and Unix checkouts validate the same examples.
+
+The examples are protocol-relative and intentionally keep `settled=false` where
+external or route-level obligations remain. Ports should preserve the separate
+meanings of `accepted`, `operationally_usable`, `finite_checks_passed`, and
+`settled` rather than collapsing them into one success flag.
+
+The phase acceleration examples add the compact planning contract for ports:
+`PhaseAccelerationPlan` ranks finite gaps, bottlenecks, and safe next actions,
+while `PhaseAccelerationBenchmarkReport` checks that candidate-only volume does
+not reduce phase gaps and that planner output does not grant execution
+authority.