feat(provider-contract): compile governed L2 execution plans

2026-07-23 19:27:01 +03:00
parent 6f9da1b677
commit a5a5644dbf
9 changed files with 916 additions and 1 deletions
@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import {
+  L2_EXECUTION_PLAN_SCHEMA_VERSION,
+  L2_MATERIALIZATION_RECEIPT_SCHEMA_VERSION,
+  attestL2ExecutionPlanMaterialization,
+  compileL2ExecutionPlan,
+  instantiateL2Connection,
+  validateL2ExecutionPlan,
+} from "../src/index.mjs";
+import {
+  geliosProviderPackageV8,
+  geliosTelemetryFieldRegistryV1,
+} from "../providers/gelios/v8/index.mjs";
+
+const positionsConnection = instantiateL2Connection(geliosProviderPackageV8, {
+  tenantId: "tenant-compiler-fixture",
+  connectionId: "gelios-compiler-fixture",
+  collectionProfileId: "gelios.positions.current.realtime.v7",
+  providerCredentialRef: "ndc-credref:provider-compiler-fixture-0001",
+});
+const positionsPlan = compileL2ExecutionPlan(
+  geliosProviderPackageV8,
+  positionsConnection,
+  { telemetryFieldRegistry: geliosTelemetryFieldRegistryV1 },
+);
+
+assert.equal(positionsPlan.schemaVersion, L2_EXECUTION_PLAN_SCHEMA_VERSION);
+assert.deepEqual(validateL2ExecutionPlan(positionsPlan), { ok: true, errors: [] });
+assert.match(positionsPlan.executionPlanDigest, /^sha256:[a-f0-9]{64}$/);
+assert.match(positionsPlan.artifacts.packageDigest, /^sha256:[a-f0-9]{64}$/);
+assert.match(positionsPlan.artifacts.mappingContractDigest, /^sha256:[a-f0-9]{64}$/);
+assert.match(positionsPlan.artifacts.telemetryRegistryDigest, /^sha256:[a-f0-9]{64}$/);
+assert.deepEqual(positionsPlan.steps.map((step) => step.kind), [
+  "collection_trigger",
+  "provider_request",
+  "provider_request",
+  "extract_items",
+  "semantic_mapping",
+  "data_product_publish",
+]);
+const unitsRequest = positionsPlan.steps.find(
+  (step) => step.kind === "provider_request" && step.config.capabilityId === "gelios.units.current.read",
+);
+assert.deepEqual(unitsRequest.config.request.query, {
+  incltrip: "true",
+  inclcntrs: "true",
+  inclsnsrs: "true",
+  incllsv: "true",
+});
+const semanticMapping = positionsPlan.steps.find((step) => step.kind === "semantic_mapping");
+assert.deepEqual(
+  semanticMapping.config.telemetryProjection.entries.map((entry) => entry.reading.id),
+  ["sensor.param.in0", "sensor.param.in1"],
+);
+assert.equal(Object.isFrozen(positionsPlan), true);
+assert.equal(Object.isFrozen(positionsPlan.steps), true);
+
+const clonedPlan = compileL2ExecutionPlan(
+  structuredClone(geliosProviderPackageV8),
+  structuredClone(positionsConnection),
+  { telemetryFieldRegistry: structuredClone(geliosTelemetryFieldRegistryV1) },
+);
+assert.equal(clonedPlan.executionPlanDigest, positionsPlan.executionPlanDigest);
+
+assert.throws(
+  () => compileL2ExecutionPlan(geliosProviderPackageV8, positionsConnection),
+  /telemetry_registry_required/,
+);
+
+const profileConnection = instantiateL2Connection(geliosProviderPackageV8, {
+  tenantId: "tenant-compiler-fixture",
+  connectionId: "gelios-profile-compiler-fixture",
+  collectionProfileId: "gelios.units.profile.cold.v1",
+  providerCredentialRef: "ndc-credref:provider-compiler-fixture-0001",
+});
+const profilePlan = compileL2ExecutionPlan(geliosProviderPackageV8, profileConnection);
+assert.deepEqual(validateL2ExecutionPlan(profilePlan), { ok: true, errors: [] });
+assert.equal(profilePlan.artifacts.telemetryRegistryDigest, undefined);
+assert.notEqual(profilePlan.executionPlanDigest, positionsPlan.executionPlanDigest);
+
+const secondConnection = instantiateL2Connection(geliosProviderPackageV8, {
+  tenantId: "tenant-compiler-fixture",
+  connectionId: "gelios-compiler-fixture-two",
+  collectionProfileId: "gelios.positions.current.realtime.v7",
+  providerCredentialRef: "ndc-credref:provider-compiler-fixture-0002",
+});
+const secondPlan = compileL2ExecutionPlan(
+  geliosProviderPackageV8,
+  secondConnection,
+  { telemetryFieldRegistry: geliosTelemetryFieldRegistryV1 },
+);
+assert.notEqual(secondPlan.executionPlanDigest, positionsPlan.executionPlanDigest);
+
+const receipt = attestL2ExecutionPlanMaterialization(positionsPlan, {
+  graphRevision: "engine-revision-fixture-0001",
+  graphDigest: "a".repeat(64),
+  materializedStepIds: positionsPlan.steps.map((step) => step.id),
+});
+assert.equal(receipt.schemaVersion, L2_MATERIALIZATION_RECEIPT_SCHEMA_VERSION);
+assert.equal(receipt.executionPlanDigest, positionsPlan.executionPlanDigest);
+assert.equal(receipt.graphDigest, `sha256:${"a".repeat(64)}`);
+assert.match(receipt.receiptDigest, /^sha256:[a-f0-9]{64}$/);
+assert.equal(Object.isFrozen(receipt), true);
+
+assert.throws(() => attestL2ExecutionPlanMaterialization(positionsPlan, {
+  graphRevision: "engine-revision-fixture-0001",
+  graphDigest: "a".repeat(64),
+  materializedStepIds: positionsPlan.steps.slice(1).map((step) => step.id),
+}), /materializedStepIds_must_exactly_match/);
+
+const tamperedPlan = structuredClone(positionsPlan);
+tamperedPlan.steps[0].config.mode = "history";
+assert.equal(
+  validateL2ExecutionPlan(tamperedPlan).errors.includes("executionPlan.executionPlanDigest_mismatch"),
+  true,
+);
+
+const serialized = JSON.stringify(positionsPlan);
+assert.equal(serialized.includes("Bearer "), false);
+assert.equal(serialized.includes("access_token"), false);
+assert.equal(serialized.includes("refresh_token"), false);
@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import {
+  TELEMETRY_FIELD_PROJECTION_SCHEMA_VERSION,
+  compileTelemetryFieldProjection,
+  digestTelemetryFieldRegistry,
+  validateTelemetryFieldRegistry,
+} from "../src/index.mjs";
+import {
+  geliosTelemetryFieldRegistryV1,
+} from "../providers/gelios/v8/index.mjs";
+
+assert.deepEqual(validateTelemetryFieldRegistry(geliosTelemetryFieldRegistryV1), {
+  ok: true,
+  errors: [],
+});
+assert.match(digestTelemetryFieldRegistry(geliosTelemetryFieldRegistryV1), /^sha256:[a-f0-9]{64}$/);
+
+const projection = compileTelemetryFieldProjection(geliosTelemetryFieldRegistryV1, {
+  providerPackageId: "gelios.provider.v8",
+  providerPackageVersion: "8.0.0",
+  dataProductId: "fleet.positions.current.v5",
+  surface: "data_product",
+});
+assert.equal(projection.schemaVersion, TELEMETRY_FIELD_PROJECTION_SCHEMA_VERSION);
+assert.deepEqual(projection.entries.map((entry) => entry.sourceKey), ["in0", "in1"]);
+assert.deepEqual(projection.entries.map((entry) => entry.reading.id), [
+  "sensor.param.in0",
+  "sensor.param.in1",
+]);
+assert.equal(projection.entries.some((entry) => entry.sourceKey === "in_0"), false);
+assert.equal(Object.isFrozen(projection), true);
+assert.equal(Object.isFrozen(projection.entries), true);
+
+const observedExposed = structuredClone(geliosTelemetryFieldRegistryV1);
+observedExposed.entries.find((entry) => entry.sourceKey === "in_0").allowedSurfaces.push("foundry");
+assert.equal(
+  validateTelemetryFieldRegistry(observedExposed).errors.includes(
+    "registry.entries[2].nonapproved_surface_must_be_audit_only",
+  ),
+  true,
+);
+
+const approvedUnclassified = structuredClone(geliosTelemetryFieldRegistryV1);
+approvedUnclassified.entries[0].sensitivity = "unclassified";
+assert.equal(
+  validateTelemetryFieldRegistry(approvedUnclassified).errors.includes(
+    "registry.entries[0].approved_must_be_operational",
+  ),
+  true,
+);
+
+const wildcardSource = structuredClone(geliosTelemetryFieldRegistryV1);
+wildcardSource.entries[0].sourceKey = "*";
+assert.equal(
+  validateTelemetryFieldRegistry(wildcardSource).errors.includes(
+    "registry.entries[0].sourceKey_invalid",
+  ),
+  true,
+);
+
+const duplicateReading = structuredClone(geliosTelemetryFieldRegistryV1);
+duplicateReading.entries[1].semanticReading.id = duplicateReading.entries[0].semanticReading.id;
+assert.equal(
+  validateTelemetryFieldRegistry(duplicateReading).errors.includes(
+    "registry.entries[1].semanticReading.id_must_be_unique",
+  ),
+  true,
+);
+
+assert.throws(() => compileTelemetryFieldProjection(geliosTelemetryFieldRegistryV1, {
+  providerPackageId: "another.provider.v1",
+  providerPackageVersion: "8.0.0",
+  dataProductId: "fleet.positions.current.v5",
+  surface: "data_product",
+}), /providerPackageId_mismatch/);
+
+const serialized = JSON.stringify(geliosTelemetryFieldRegistryV1);
+for (const forbidden of ["phone", "imei", "commands", "access_token", "refresh_token"]) {
+  assert.equal(serialized.toLowerCase().includes(forbidden), false);
+}