@zaip-ai/cli 6.3.0 → 7.6.0

package/templates/.agents/skills/zaip-skill-lead-measurement/scripts/delivery-v2-case-fixtures.mjs

@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+
+export const value = (run) => {
+  let result;
+  assert.doesNotThrow(() => {
+    result = run();
+  });
+  return result;
+};
+export const target = (destination_id = "a_meta", extra = {}) => ({
+  schema_version: 2,
+  tenant: "tenant_a",
+  environment: "staging",
+  provider: "meta_capi",
+  resource: "dataset_a",
+  mode: "test",
+  destination_id,
+  ...extra,
+});
+export const destinations = () => [
+  target(),
+  target("b_meta", { tenant: "tenant_b" }),
+  target("a_other", { resource: "dataset_b" }),
+  target("a_prod", { mode: "production" }),
+  target("a_ga4", { provider: "ga4_mp", resource: "property_a" }),
+  target("a_kommo", { provider: "kommo", resource: "crm_a" }),
+];
+export const event = () => ({
+  schema_version: 1,
+  event_id: "evt_synthetic_delivery",
+  event_name: "lead_accepted",
+  occurred_at: "2026-10-29T12:00:00Z",
+  acceptance: { persisted: true, receipt_id: "receipt_synthetic_delivery" },
+  classification: { service: "renovation", budget_band: "medium", qualification: "new" },
+  consent: {
+    analytics_storage: "granted",
+    ad_storage: "granted",
+    ad_user_data: "granted",
+    ad_personalization: "granted",
+    meta_measurement: "granted",
+  },
+});
+export const config = () => ({
+  schema_version: 1,
+  catalog_version: "synthetic-v1",
+  mapping_version: "synthetic-v1",
+  classification_catalog: {
+    service: ["renovation", "painting"],
+    budget_band: ["medium"],
+    qualification: ["new", "qualified"],
+  },
+  events: {
+    lead_accepted: { ga4: "generate_lead", meta: "Lead" },
+    lead_qualified: { ga4: "lead_qualified", meta: "QualifiedLead" },
+  },
+  google_ads: {
+    primary_source: "ga4_import",
+    sources: { ga4_import: { primary: true }, direct: { primary: false } },
+  },
+  required_consent: {
+    ga4: ["analytics_storage"],
+    google_ads: ["analytics_storage", "ad_storage", "ad_user_data"],
+    meta: ["meta_measurement"],
+  },
+  retry: { max_attempts: 3, base_delay_ms: 1000, max_delay_ms: 60000 },
+});
+export const granted = () =>
+  ["contact", "terms", "analytics", "google_ads", "meta_measurement"].map((purpose, index) => ({
+    purpose,
+    state: "granted",
+    sequence: index + 1,
+  }));
+export const response = (status = 200, body = { events_received: 1 }, extra = {}) => ({
+  status,
+  error: null,
+  effect: "possible",
+  body,
+  ...extra,
+});
+export function fixture(api, initial = granted()) {
+  let history = initial;
+  const manifest = destinations(),
+    reads = [];
+  const model = value(() =>
+    api.createDeliveryV2({
+      destinations: manifest,
+      readCurrent: (scope) => {
+        reads.push(scope);
+        if (history instanceof Error) throw history;
+        return history;
+      },
+    }),
+  );
+  const enqueue = (id = "a_meta", e = event(), c = config()) =>
+    value(() => model.enqueue(id, e, c));
+  const start = (key, at = 100, duration = 1000) => {
+    const lease = value(() => model.claim(key, at, duration));
+    assert.equal(lease.allowed, true);
+    const effects = [];
+    assert.equal(
+      value(() => model.authorize(key, lease.token, at, (payload) => effects.push(payload)))
+        .allowed,
+      true,
+    );
+    assert.equal(effects.length, 1);
+    return lease.token;
+  };
+  return {
+    model,
+    enqueue,
+    start,
+    reads,
+    manifest,
+    set: (next) => {
+      history = next;
+    },
+  };
+}

package/templates/.agents/skills/zaip-skill-lead-measurement/scripts/delivery-v2-cases.mjs

@@ -0,0 +1,6 @@
+import { deliveryV2ContractCases } from "./delivery-v2-contract-cases.mjs";
+import { deliveryV2StateCases } from "./delivery-v2-state-cases.mjs";
+
+export function deliveryV2Cases(api) {
+  return [...deliveryV2ContractCases(api), ...deliveryV2StateCases(api)];
+}

package/templates/.agents/skills/zaip-skill-lead-measurement/scripts/delivery-v2-contract-cases.mjs

@@ -0,0 +1,218 @@
+import assert from "node:assert/strict";
+import { config, event, fixture, response, value } from "./delivery-v2-case-fixtures.mjs";
+
+export function deliveryV2ContractCases(api) {
+  return [
+    [
+      "C051-v1-shape-preserved-model-only",
+      () => {
+        const f = fixture(api),
+          { job } = f.enqueue();
+        assert.equal(f.model.model_only, true);
+        assert.equal(job.schema_version, 2);
+        assert.equal(job.payload.event_id, event().event_id);
+        assert.equal(job.payload.event_name, "Lead");
+        assert.equal(job.payload.occurred_at, event().occurred_at);
+        assert.equal(job.confirmed, false);
+        assert.equal(job.attributed, false);
+        assert.doesNotMatch(
+          JSON.stringify(job.payload),
+          /receipt|acceptance|email|phone|contact_hash/,
+        );
+      },
+    ],
+    [
+      "C052-semantic-positive-and-malformed",
+      () => {
+        for (const body of [
+          { events_received: 0 },
+          { events_received: 2 },
+          { events_received: "1" },
+          {},
+          { events_received: 1, email: "synthetic@example.invalid" },
+        ]) {
+          const f = fixture(api),
+            { key } = f.enqueue(),
+            token = f.start(key);
+          const result = value(() => f.model.record(key, token, response(200, body), 101));
+          assert.equal(result.state, "uncertain");
+          assert.equal(result.confirmed, false);
+        }
+        const f = fixture(api),
+          { key } = f.enqueue(),
+          token = f.start(key);
+        const result = value(() => f.model.record(key, token, response(), 101));
+        assert.equal(result.state, "confirmed");
+        assert.equal(result.semantic_acceptance, "accepted");
+        assert.deepEqual(result.transport, { status: 200, error: null });
+        assert.equal(result.attributed, false);
+        assert.equal(f.model.claim(key, 200).allowed, false);
+      },
+    ],
+    [
+      "C052-queued-needs-reconciliation",
+      () => {
+        const f = fixture(api),
+          { key } = f.enqueue(),
+          token = f.start(key);
+        const result = value(() => f.model.record(key, token, response(202, {}), 101));
+        assert.equal(result.state, "queued");
+        assert.equal(result.confirmed, false);
+        assert.equal(result.semantic_acceptance, "unverified");
+        assert.equal(f.model.claim(key, 200).allowed, false);
+        assert.equal(
+          value(() =>
+            f.model.reconcile(
+              key,
+              { decision: "confirmed_effect", reference: "synthetic_review" },
+              200,
+            ),
+          ).confirmed,
+          true,
+        );
+      },
+    ],
+    [
+      "C052-ga4-collect-2xx-not-ingestion",
+      () => {
+        for (const status of [200, 204]) {
+          const f = fixture(api),
+            { key } = f.enqueue("a_ga4"),
+            token = f.start(key);
+          const result = value(() => f.model.record(key, token, response(status, {}), 101));
+          assert.equal(result.state, "uncertain");
+          assert.equal(result.semantic_acceptance, "not_available");
+          assert.equal(result.confirmed, false);
+          assert.equal(result.attributed, false);
+        }
+      },
+    ],
+    [
+      "C052-kommo-normalized-receipt",
+      () => {
+        for (const [body, expected] of [
+          [{ entity_id: "123", checkpoint: "complete" }, "confirmed"],
+          [{ entity_id: 123, checkpoint: "complete" }, "uncertain"],
+          [{ entity_id: "123", checkpoint: "partial" }, "uncertain"],
+        ]) {
+          const f = fixture(api),
+            { key } = f.enqueue("a_kommo"),
+            token = f.start(key);
+          assert.equal(
+            value(() => f.model.record(key, token, response(200, body), 101)).state,
+            expected,
+          );
+        }
+      },
+    ],
+    [
+      "C053-tenant-resource-mode-isolation",
+      () => {
+        const f = fixture(api);
+        const keys = ["a_meta", "b_meta", "a_other", "a_prod"].map((id) => f.enqueue(id).key);
+        assert.equal(new Set(keys).size, 4);
+        for (const key of keys) f.start(key);
+        assert.deepEqual(
+          f.reads.map((item) => item.tenant),
+          [
+            "tenant_a",
+            "tenant_a",
+            "tenant_b",
+            "tenant_b",
+            "tenant_a",
+            "tenant_a",
+            "tenant_a",
+            "tenant_a",
+          ],
+        );
+      },
+    ],
+    [
+      "C053-canonical-json-types-arrays",
+      () => {
+        assert.equal(
+          api.digest({ a: 1, b: { c: 2, d: 3 } }),
+          api.digest({ b: { d: 3, c: 2 }, a: 1 }),
+        );
+        assert.notEqual(api.digest([1, "1"]), api.digest(["1", 1]));
+        assert.notEqual(api.digest({ a: null }), api.digest({}));
+        const f = fixture(api),
+          queued = f.enqueue();
+        const e = event(),
+          reordered = Object.fromEntries(Object.entries(e).reverse());
+        assert.equal(value(() => f.model.enqueue("a_meta", reordered, config())).status, "replay");
+        assert.equal(f.model.get(queued.key).fingerprint, queued.job.fingerprint);
+      },
+    ],
+    [
+      "C053-mapping-payload-destination-conflict",
+      () => {
+        const f = fixture(api),
+          queued = f.enqueue(),
+          token = f.start(queued.key);
+        value(() => f.model.record(queued.key, token, response(), 101));
+        const changed = config();
+        changed.mapping_version = "synthetic-v2";
+        assert.throws(() => f.model.enqueue("a_meta", event(), changed), /conflict/);
+        const altered = event();
+        altered.classification.service = "painting";
+        assert.throws(() => f.model.enqueue("a_meta", altered, config()), /conflict/);
+        assert.throws(() => f.model.enqueue("new_destination", event(), config()), /unapproved/);
+        const replay = value(() => f.model.enqueue("a_meta", event(), config()));
+        assert.equal(replay.status, "replay");
+        assert.equal(replay.job.state, "confirmed");
+        assert.equal(replay.job.attempts, 1);
+      },
+    ],
+    [
+      "C053-strict-records-no-PII-effects",
+      () => {
+        let getters = 0;
+        const malicious = event();
+        Object.defineProperty(malicious, "event_id", {
+          enumerable: true,
+          get() {
+            getters++;
+            return "evt_synthetic_delivery";
+          },
+        });
+        const f = fixture(api);
+        assert.throws(() => f.model.enqueue("a_meta", malicious, config()));
+        assert.equal(getters, 0);
+        for (const change of [
+          (e) => {
+            e.email = "synthetic@example.invalid";
+          },
+          (e) => {
+            Object.defineProperty(e.classification, "service", {
+              value: "renovation",
+              enumerable: false,
+            });
+          },
+          (e) => {
+            e[Symbol("private")] = "hidden";
+          },
+        ]) {
+          const e = event();
+          change(e);
+          assert.throws(() => f.model.enqueue("a_meta", e, config()));
+        }
+        const { key } = f.enqueue(),
+          token = f.start(key);
+        const body = {};
+        Object.defineProperty(body, "events_received", {
+          enumerable: true,
+          get() {
+            getters++;
+            return 1;
+          },
+        });
+        assert.equal(
+          value(() => f.model.record(key, token, response(200, body), 101)).confirmed,
+          false,
+        );
+        assert.equal(getters, 0);
+      },
+    ],
+  ];
+}

package/templates/.agents/skills/zaip-skill-lead-measurement/scripts/delivery-v2-contract.mjs

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { projectMeasurement, validateConfig, validateEnvelope } from "./lead-measurement.mjs";
+
+export function fail(code) {
+  throw new TypeError(code);
+}
+export function fields(value, allowed, required = allowed) {
+  if (!value || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    fail("record_required");
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (
+    Reflect.ownKeys(value).some(
+      (key) =>
+        typeof key !== "string" ||
+        !allowed.includes(key) ||
+        !Object.hasOwn(descriptors[key], "value") ||
+        descriptors[key].enumerable !== true,
+    )
+  )
+    fail("unsafe_field");
+  if (required.some((key) => !Object.hasOwn(value, key))) fail("missing_field");
+}
+export function canonical(value, seen = new Set(), depth = 0) {
+  if (depth > 12) fail("json_too_deep");
+  if (value === null || typeof value === "boolean" || typeof value === "string")
+    return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || Object.is(value, -0) || !Number.isSafeInteger(value))
+      fail("unsafe_number");
+    return JSON.stringify(value);
+  }
+  if (typeof value !== "object" || seen.has(value)) fail("unsafe_json");
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) {
+    if (value.length > 1000) fail("array_too_large");
+    const expected = Array.from({ length: value.length }, (_, index) => String(index));
+    const keys = Reflect.ownKeys(value);
+    if (
+      keys.length !== expected.length + 1 ||
+      !keys.includes("length") ||
+      expected.some((key) => !Object.hasOwn(value, key))
+    )
+      fail("unsafe_array");
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    for (const key of expected)
+      if (!Object.hasOwn(descriptors[key], "value") || !descriptors[key].enumerable)
+        fail("unsafe_array");
+    result = `[${expected.map((key) => canonical(descriptors[key].value, seen, depth + 1)).join(",")}]`;
+  } else {
+    fields(value, Object.getOwnPropertyNames(value));
+    const keys = Object.keys(value).sort(); // MUT_CANONICAL
+    if (keys.length > 100) fail("record_too_large");
+    result = `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key], seen, depth + 1)}`).join(",")}}`;
+  }
+  seen.delete(value);
+  if (result.length > 65536) fail("json_too_large");
+  return result;
+}
+export const clone = (value) => JSON.parse(canonical(value));
+export const digest = (value) => createHash("sha256").update(canonical(value)).digest("hex");
+export function freeze(value) {
+  for (const item of Object.values(value)) if (item && typeof item === "object") freeze(item);
+  return Object.freeze(value);
+}
+export function integer(value, min, max) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) fail("invalid_integer");
+}
+export function scope(input) {
+  fields(input, [
+    "schema_version",
+    "tenant",
+    "environment",
+    "provider",
+    "resource",
+    "mode",
+    "destination_id",
+  ]);
+  if (
+    input.schema_version !== 2 ||
+    !["test", "staging", "production"].includes(input.environment) ||
+    !["test", "production"].includes(input.mode) ||
+    !["meta_capi", "ga4_mp", "kommo"].includes(input.provider)
+  )
+    fail("invalid_scope");
+  for (const key of ["tenant", "resource", "destination_id"])
+    if (typeof input[key] !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(input[key]))
+      fail("invalid_scope_identity");
+  return freeze(clone(input));
+}
+export function deliveryKey(target, eventId) {
+  return canonical([
+    target.tenant,
+    target.environment,
+    target.provider,
+    target.resource,
+    target.mode,
+    eventId,
+  ]); // MUT_KEY
+}
+export function eventProjection(event, configuration, provider) {
+  // Reject active/non-enumerable/non-JSON data before calling the legacy validators.
+  const config = validateConfig(clone(configuration));
+  const accepted = validateEnvelope(clone(event), config);
+  const projections = projectMeasurement(accepted, config);
+  let payload =
+    provider === "meta_capi"
+      ? projections.meta_capi
+      : provider === "ga4_mp"
+        ? projections.ga4
+        : {
+            event_id: accepted.event_id,
+            event_name: accepted.event_name,
+            occurred_at: accepted.occurred_at,
+            mapping_version: config.mapping_version,
+            parameters: { ...accepted.classification },
+          };
+  if (!payload) fail("snapshot_ineligible");
+  payload = clone(payload);
+  return {
+    event: accepted,
+    config,
+    payload,
+    fingerprint: digest({ event: accepted, config, payload }),
+  };
+}
+
+export function classify(provider, input) {
+  const response = clone(input);
+  fields(
+    response,
+    ["status", "error", "effect", "body", "retry_after_ms"],
+    ["status", "error", "effect", "body"],
+  );
+  if (
+    (response.status !== null &&
+      (!Number.isInteger(response.status) || response.status < 100 || response.status > 599)) ||
+    ![null, "before_send", "timeout_after_effect"].includes(response.error) ||
+    !["none", "possible"].includes(response.effect)
+  )
+    fail("invalid_response");
+  if (response.retry_after_ms !== undefined) integer(response.retry_after_ms, 0, 86400000);
+  if (response.error !== null && response.status !== null) fail("conflicting_transport");
+  if (response.status === null && response.error === null) fail("missing_transport");
+  const transport = { status: response.status, error: response.error };
+  if (response.error === "timeout_after_effect")
+    return { state: "uncertain", semantic: "unverified", transport }; // MUT_TIMEOUT
+  if (response.status === 202) return { state: "queued", semantic: "unverified", transport }; // MUT_QUEUED
+  if (response.status >= 200 && response.status < 300) {
+    if (provider === "ga4_mp") return { state: "uncertain", semantic: "not_available", transport };
+    let accepted = false;
+    if (provider === "meta_capi") {
+      fields(response.body, ["events_received"]);
+      accepted = response.body.events_received === 1; // MUT_ACCEPTANCE
+    } else if (provider === "kommo") {
+      fields(response.body, ["entity_id", "checkpoint"]);
+      accepted =
+        typeof response.body.entity_id === "string" &&
+        /^[0-9]{1,30}$/.test(response.body.entity_id) &&
+        response.body.checkpoint === "complete";
+    }
+    return {
+      state: accepted ? "confirmed" : "uncertain",
+      semantic: accepted ? "accepted" : "rejected",
+      transport,
+    };
+  }
+  const retryable =
+    response.error === "before_send" || response.status === 429 || response.status >= 500;
+  if (retryable && response.effect === "none")
+    return {
+      state: "retry",
+      semantic: "rejected",
+      transport,
+      retry_after_ms: response.retry_after_ms ?? 0,
+    };
+  return {
+    state: response.effect === "possible" ? "uncertain" : "terminal",
+    semantic: "rejected",
+    transport,
+  };
+}

package/templates/.agents/skills/zaip-skill-lead-measurement/scripts/delivery-v2-proof-support.mjs

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { access, lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+export const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+export async function temporary() {
+  const parent = await realpath(tmpdir());
+  return { parent, path: await mkdtemp(join(parent, "zaip-delivery-v2-")) };
+}
+export async function removeTemporary(owned) {
+  assert.equal(dirname(owned.path), owned.parent);
+  assert.ok(basename(owned.path).startsWith("zaip-delivery-v2-"));
+  assert.equal((await lstat(owned.path)).isSymbolicLink(), false);
+  assert.equal(await realpath(owned.path), owned.path);
+  await rm(owned.path, { recursive: true });
+  await assert.rejects(access(owned.path), { code: "ENOENT" });
+}
+export function rollbackFixture(base, candidate, runGit, create) {
+  assert.match(base ?? "", /^[a-f0-9]{40}$/);
+  assert.match(candidate, /^[a-f0-9]{40}$/);
+  const existing = runGit(["cat-file", "-e", `${base}^{commit}`]);
+  if (existing.error || existing.signal || existing.status !== 0)
+    throw new Error("base_unverified");
+  if (base === candidate) throw new Error("base_must_differ");
+  const ancestry = runGit(["merge-base", "--is-ancestor", base, candidate]);
+  if (ancestry.error || ancestry.signal || ancestry.status !== 0)
+    throw new Error("ancestry_unverified");
+  return create();
+}
+export async function deliveryRollback(root, paths, base) {
+  const runGit = (args) =>
+    spawnSync("git", args, { cwd: root, windowsHide: true, maxBuffer: 2000000 });
+  const git = (args) => {
+    const result = runGit(args);
+    if (result.error || result.status !== 0) throw new Error("git_failure");
+    return result.stdout;
+  };
+  const candidate = git(["rev-parse", "HEAD"]).toString().trim();
+  const owned = await rollbackFixture(base, candidate, runGit, temporary);
+  let report;
+  try {
+    const before = new Map(),
+      after = new Map(),
+      principal = new Map();
+    const normal = (bytes) => bytes.toString("utf8").replace(/\r\n/g, "\n");
+    for (const path of paths) {
+      assert.ok(path.startsWith(".agents/") && !path.includes("..") && !path.includes("\\"));
+      const blob = git(["show", `${candidate}:${path}`]),
+        current = await readFile(resolve(root, path));
+      assert.equal(normal(current), normal(blob));
+      principal.set(path, current);
+      after.set(path, blob);
+      before.set(
+        path,
+        git(["ls-tree", "-z", base, "--", path]).length ? git(["show", `${base}:${path}`]) : null,
+      );
+    }
+    const sentinel = join(owned.path, "records-history.sentinel"),
+      saved = Buffer.from("synthetic ledger/history preserved\n");
+    await writeFile(sentinel, saved);
+    async function apply(snapshot) {
+      for (const [path, bytes] of snapshot) {
+        const target = resolve(owned.path, path);
+        assert.ok(target.startsWith(owned.path + sep));
+        await mkdir(dirname(target), { recursive: true });
+        if (bytes === null) await rm(target, { force: true });
+        else await writeFile(target, bytes);
+      }
+      for (const [path, bytes] of snapshot) {
+        if (bytes === null)
+          await assert.rejects(access(resolve(owned.path, path)), { code: "ENOENT" });
+        else assert.deepEqual(await readFile(resolve(owned.path, path)), bytes);
+      }
+      assert.deepEqual(await readFile(sentinel), saved);
+    }
+    await apply(before);
+    await apply(after);
+    await apply(before);
+    await apply(after);
+    for (const [path, bytes] of principal)
+      assert.deepEqual(await readFile(resolve(root, path)), bytes);
+    report = {
+      kind: "delivery_rollback",
+      passed: true,
+      base_sha: base,
+      candidate_sha: candidate,
+      principal_unchanged: true,
+      records_history_preserved: true,
+      files: paths.map((path) => ({
+        path,
+        base_present: before.get(path) !== null,
+        base_sha256: before.get(path) === null ? null : sha256(before.get(path)),
+        candidate_sha256: sha256(after.get(path)),
+        reverted: true,
+        reapplied: true,
+      })),
+    };
+  } finally {
+    await removeTemporary(owned);
+  }
+  return { ...report, temporary_removed: true };
+}