@vivix-labs/event-statistics 0.0.0-stage → 1.0.0-beta

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+import { ServerContext } from 'vivix-studio/sdk/server';
+import { z } from 'vivix-studio/sdk/shared';
+import { Config } from './shared.js';
+export { dependencies } from './shared.js';
+
+declare function activate(ctx: ServerContext<z.infer<typeof Config>>): Promise<void>;
+
+export { Config, activate as default };

package/dist/server.js

@@ -0,0 +1,331 @@
+// packages/event-statistics/src/server.ts
+import { createHash } from "crypto";
+import { defineOperation } from "vivix-studio/sdk/server";
+import { z as z4 } from "vivix-studio/sdk/shared";
+
+// packages/project-studio/src/events.ts
+import { z as z2 } from "vivix-studio/sdk/shared";
+
+// packages/vivix-api/src/billing.ts
+import { z } from "vivix-studio/sdk/shared";
+var taskBilling = z.object({
+  status: z.enum(["pending", "settled", "released", "unavailable"]),
+  credits: z.string().regex(/^\d+(?:\.\d+)?$/).nullable()
+}).strict().refine(
+  (value) => value.status === "settled" ? value.credits !== null : value.status === "released" ? value.credits === "0" : value.credits === null
+);
+function readTaskBilling(response) {
+  const parsed = taskBilling.safeParse(response?.billing);
+  return parsed.success ? parsed.data : { status: "unavailable", credits: null };
+}
+
+// packages/project-studio/src/events.ts
+var taskEventNames = [
+  "project-studio/task.completed",
+  "project-studio/task.failed",
+  "project-studio/task.cancelled",
+  "project-studio/billing.updated"
+];
+var result = z2.object({
+  remoteTaskId: z2.string(),
+  outputIndex: z2.number().int().nonnegative(),
+  assetId: z2.string().optional()
+}).strict();
+var taskNotice = z2.object({
+  taskId: z2.string(),
+  attemptId: z2.string(),
+  revision: z2.number().int().positive(),
+  requestedCount: z2.number().int().positive().nullable(),
+  resultCount: z2.number().int().nonnegative().nullable(),
+  partialResults: z2.boolean().nullable(),
+  results: z2.array(result)
+}).strict();
+var billingNotice = z2.object({
+  taskId: z2.string(),
+  attemptId: z2.string(),
+  billingRecordId: z2.string(),
+  revision: z2.number().int().positive()
+}).strict();
+var eventDefinitions = taskEventNames.map((name) => ({
+  name,
+  version: 1,
+  mode: "notification",
+  schema: name.endsWith("billing.updated") ? "schemas/billing-notice.json" : "schemas/task-notice.json",
+  scope: "project"
+}));
+var stateKey = "project-studio.state";
+function saved(record) {
+  const value = record.metadata?.[stateKey];
+  return value?.format === 1 && value.remote && Number.isSafeInteger(value.remote.revision) ? value : void 0;
+}
+function readableResults(record) {
+  if (typeof record.data.remoteTaskId !== "string" || !record.data.remoteTaskId) return [];
+  return (record.data.remoteOutputs || []).flatMap((value, outputIndex) => {
+    if (!value || typeof value !== "object") return [];
+    const output = value;
+    return ["asset_id", "file_id", "id", "url", "download_url", "content", "text"].some(
+      (k) => typeof output[k] === "string" && Boolean(output[k])
+    ) ? [{ remoteTaskId: record.data.remoteTaskId, outputIndex }] : [];
+  });
+}
+function outcome(record) {
+  const d = record.data;
+  if (d.remoteStatus === "succeeded" && readableResults(record).length) return "succeeded";
+  if (d.remoteStatus === "failed") return "failed";
+  if (["cancelled", "canceled"].includes(d.remoteStatus) || d.state === "canceled" && !d.submittedAt && !d.remoteTaskId && d.attemptCount === 0)
+    return "cancelled";
+  return "unknown";
+}
+function taskState(record) {
+  const old = saved(record), status = outcome(record);
+  const requestedCount = Number.isInteger(record.data.inputSnapshot?.outputCount) ? record.data.inputSnapshot.outputCount : null;
+  const resultSignature = JSON.stringify(readableResults(record));
+  const storedCount = Array.isArray(record.data.remoteOutputs) ? record.data.remoteOutputs.length : null;
+  const unchanged = old?.remote.status === status && old.remote.requestedCount === requestedCount && old.remote.resultSignature === resultSignature && (old.remote.resultCount === null || old.remote.resultCount === storedCount);
+  const resultCount = status === "unknown" ? null : unchanged ? old.remote.resultCount : record.data.remoteOutputs?.length ? record.data.remoteOutputs.length : null;
+  return {
+    format: 1,
+    remote: {
+      status,
+      revision: unchanged ? old.remote.revision : record.revision,
+      requestedCount,
+      resultCount,
+      partialResults: requestedCount !== null && resultCount !== null ? resultCount < requestedCount : null,
+      resultSignature
+    },
+    billing: currentBilling(record, old?.billing)
+  };
+}
+function billingViewFromI4(record, cost, revision) {
+  const { status, credits } = readTaskBilling({
+    billing: { status: cost.status, credits: cost.credits }
+  });
+  return {
+    billingRecordId: JSON.stringify([
+      record.storeId,
+      record.scope?.id,
+      record.objectId,
+      "task.cost"
+    ]),
+    taskId: record.objectId,
+    attemptId: record.objectId,
+    revision,
+    status,
+    amount: status === "settled" || status === "released" ? { value: credits.replace(/^0+(?=\d)/, ""), unit: "credits" } : null
+  };
+}
+function normalizeDecimal(value) {
+  const [whole, fraction = ""] = value.split(".");
+  const trimmed = fraction.replace(/0+$/, "");
+  return whole.replace(/^0+(?=\d)/, "") + (trimmed ? "." + trimmed : "");
+}
+function billingDigest(view) {
+  return JSON.stringify([
+    view.status,
+    view.amount && { ...view.amount, value: normalizeDecimal(view.amount.value) }
+  ]);
+}
+function currentBilling(record, old) {
+  const view = billingViewFromI4(
+    record,
+    record.data.cost ?? { status: "unavailable", credits: null },
+    record.revision
+  );
+  const semanticDigest = billingDigest(view);
+  return {
+    billingRecordId: view.billingRecordId,
+    semanticDigest,
+    revision: old?.semanticDigest === semanticDigest ? old.revision : record.revision
+  };
+}
+function taskBillingView(record) {
+  const state = taskState(record);
+  return billingViewFromI4(
+    record,
+    record.data.cost ?? { status: "unavailable", credits: null },
+    state.billing?.revision ?? record.revision
+  );
+}
+
+// packages/event-statistics/src/shared.ts
+import { z as z3 } from "vivix-studio/sdk/shared";
+var Config = z3.object({
+  studioInstance: z3.string().default("studio"),
+  dataInstance: z3.string().default("user:data")
+}).strict();
+var dependencies = (config) => [
+  config.studioInstance,
+  config.dataInstance
+];
+function billingTotals(values) {
+  const latest = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const old = latest.get(value.billingRecordId);
+    if (!old || value.revision > old.revision) latest.set(value.billingRecordId, value);
+  }
+  const groups = /* @__PURE__ */ new Map();
+  let unknown = 0;
+  for (const bill of latest.values()) {
+    if (!bill.amount || !bill.amount.unit || !/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(bill.amount.value)) {
+      unknown++;
+      continue;
+    }
+    const [whole, fraction = ""] = bill.amount.value.split("."), scale = fraction.length;
+    const old = groups.get(bill.amount.unit) || { value: 0n, scale: 0 };
+    const combined = Math.max(scale, old.scale);
+    groups.set(bill.amount.unit, {
+      value: old.value * 10n ** BigInt(combined - old.scale) + BigInt(whole + fraction) * 10n ** BigInt(combined - scale),
+      scale: combined
+    });
+  }
+  return {
+    unknown,
+    units: Object.fromEntries(
+      [...groups].map(([unit, { value, scale }]) => {
+        const s = value.toString().padStart(scale + 1, "0");
+        return [unit, scale ? s.slice(0, -scale) + "." + s.slice(-scale) : s];
+      })
+    )
+  };
+}
+
+// packages/event-statistics/src/server.ts
+async function activate(ctx) {
+  if (ctx.scope?.kind !== "project") throw Error("Install the statistics example in a project.");
+  const studio = ctx.plugins.get(ctx.config.studioInstance);
+  const data = ctx.plugins.get(ctx.config.dataInstance).bind({
+    scope: ctx.scope,
+    ownerPackage: "@vivix/event-statistics",
+    packageVersion: "0.1.0",
+    actorId: "local",
+    access: ["data.workspace"]
+  });
+  data.register({
+    typeId: "statistics.task",
+    schemaVersion: 1,
+    scopeKinds: ["project"],
+    validate: (value) => z4.object({
+      taskId: z4.string(),
+      attemptId: z4.string(),
+      revision: z4.number(),
+      outcome: z4.string()
+    }).strict().parse(value)
+  });
+  function accept(task) {
+    const state = taskState(task).remote;
+    if (state.status === "unknown") return;
+    const fact = {
+      taskId: task.objectId,
+      attemptId: task.objectId,
+      revision: state.revision,
+      outcome: state.status
+    };
+    const key = createHash("sha256").update(JSON.stringify(["remote", fact])).digest("hex");
+    const object = createHash("sha256").update(task.objectId).digest("hex").slice(0, 32).replace(/^(.{8})(.{4})(.{4})(.{4})(.{12})$/, "$1-$2-$3-$4-$5");
+    data.operation(
+      "statistics.accept",
+      fact,
+      { actor: { kind: "local-user", id: "local" }, requestKey: key },
+      (tx) => {
+        const old = data.list({ typeId: "statistics.task", taskId: task.objectId, limit: 1 }).items[0];
+        if (old && old.data.revision >= fact.revision) return old;
+        return old ? tx.update(old.objectId, old.revision, fact) : tx.create("statistics.task", fact, {}, object);
+      }
+    );
+  }
+  function synchronize() {
+    for (let offset = 0; ; ) {
+      const page = studio.data.list({ typeId: "studio.task", limit: 200, offset });
+      for (const task of page.items) accept(task);
+      if (page.nextOffset === null) break;
+      offset = page.nextOffset;
+    }
+  }
+  let stopped = false, handle, timer, wake;
+  const work = (async () => {
+    let failures = 0;
+    while (!stopped) {
+      let didSynchronize = false;
+      handle = ctx.events.on(
+        {
+          id: "statistics:current",
+          eventNames: [...taskEventNames],
+          versions: [1],
+          filter: { projectIds: [ctx.scope.id] }
+        },
+        (event) => {
+          if (!stopped && event.correlation.taskId)
+            accept(studio.data.get(event.correlation.taskId));
+        }
+      );
+      try {
+        await handle.ready;
+        if (stopped) return;
+        synchronize();
+        failures = 0;
+        didSynchronize = true;
+        const { code } = await handle.closed;
+        if (![
+          "EVENT_CONNECTION_CLOSED",
+          "EVENT_STREAM_DISCONNECTED",
+          "EVENT_STREAM_OVERFLOW"
+        ].includes(code))
+          return;
+      } catch (error) {
+        if (stopped) return;
+        if (![
+          "EVENT_CONNECTION_CLOSED",
+          "EVENT_STREAM_DISCONNECTED",
+          "EVENT_STREAM_OVERFLOW"
+        ].includes(error.code || ""))
+          throw error;
+      } finally {
+        await handle.dispose();
+      }
+      if (!didSynchronize && ++failures > 6)
+        throw Error("Event recovery exhausted. Restart this consumer.");
+      await new Promise((resolve) => {
+        wake = resolve;
+        timer = setTimeout(resolve, Math.min(5e3, 250 * 2 ** Math.max(0, failures - 1)));
+      });
+    }
+  })().catch(() => console.error("EVENT_STATISTICS_UNAVAILABLE"));
+  ctx.onDispose(async () => {
+    stopped = true;
+    clearTimeout(timer);
+    wake?.();
+    await handle?.dispose();
+    await work;
+  });
+  ctx.handle(
+    defineOperation({
+      id: "statistics.current",
+      title: "Read current statistics",
+      description: "Read deduplicated task outcomes and current accepted task costs.",
+      effects: ["read"],
+      input: z4.object({}).strict(),
+      output: z4.any()
+    }),
+    () => {
+      const tasks = [], bills = [];
+      for (let offset = 0; ; ) {
+        const page = data.list({ typeId: "statistics.task", limit: 200, offset });
+        tasks.push(...page.items);
+        if (page.nextOffset === null) break;
+        offset = page.nextOffset;
+      }
+      for (let offset = 0; ; ) {
+        const page = studio.data.list({ typeId: "studio.task", limit: 200, offset });
+        bills.push(...page.items.map(taskBillingView));
+        if (page.nextOffset === null) break;
+        offset = page.nextOffset;
+      }
+      return { tasks, billing: billingTotals(bills) };
+    }
+  );
+}
+export {
+  Config,
+  activate as default,
+  dependencies
+};

package/dist/shared.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'vivix-studio/sdk/shared';
+
+interface BillingView {
+    billingRecordId: string;
+    taskId: string;
+    attemptId: string;
+    revision: number;
+    status: 'pending' | 'settled' | 'released' | 'unavailable';
+    amount: {
+        value: string;
+        unit: string;
+    } | null;
+}
+
+declare const Config: z.ZodObject<{
+    studioInstance: z.ZodDefault<z.ZodString>;
+    dataInstance: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+declare const dependencies: (config: z.infer<typeof Config>) => string[];
+/** Exact decimal sums grouped by explicit unit; missing authority remains unknown. */
+declare function billingTotals(values: readonly BillingView[]): {
+    unknown: number;
+    units: {
+        [k: string]: string;
+    };
+};
+
+export { Config, billingTotals, dependencies };

package/dist/shared.js

@@ -0,0 +1,46 @@
+// packages/event-statistics/src/shared.ts
+import { z } from "vivix-studio/sdk/shared";
+var Config = z.object({
+  studioInstance: z.string().default("studio"),
+  dataInstance: z.string().default("user:data")
+}).strict();
+var dependencies = (config) => [
+  config.studioInstance,
+  config.dataInstance
+];
+function billingTotals(values) {
+  const latest = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const old = latest.get(value.billingRecordId);
+    if (!old || value.revision > old.revision) latest.set(value.billingRecordId, value);
+  }
+  const groups = /* @__PURE__ */ new Map();
+  let unknown = 0;
+  for (const bill of latest.values()) {
+    if (!bill.amount || !bill.amount.unit || !/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(bill.amount.value)) {
+      unknown++;
+      continue;
+    }
+    const [whole, fraction = ""] = bill.amount.value.split("."), scale = fraction.length;
+    const old = groups.get(bill.amount.unit) || { value: 0n, scale: 0 };
+    const combined = Math.max(scale, old.scale);
+    groups.set(bill.amount.unit, {
+      value: old.value * 10n ** BigInt(combined - old.scale) + BigInt(whole + fraction) * 10n ** BigInt(combined - scale),
+      scale: combined
+    });
+  }
+  return {
+    unknown,
+    units: Object.fromEntries(
+      [...groups].map(([unit, { value, scale }]) => {
+        const s = value.toString().padStart(scale + 1, "0");
+        return [unit, scale ? s.slice(0, -scale) + "." + s.slice(-scale) : s];
+      })
+    )
+  };
+}
+export {
+  Config,
+  billingTotals,
+  dependencies
+};

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@vivix-labs/event-statistics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-beta",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "studio-plugin.json",
+    "skills"
+  ],
+  "exports": {
+    "./studio-plugin.json": "./studio-plugin.json",
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./shared": {
+      "types": "./dist/shared.d.ts",
+      "import": "./dist/shared.js"
+    }
+  },
+  "peerDependencies": {
+    "vivix-studio": ">=2.2.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-product-packages.mjs event-statistics"
+  }
 }

package/skills/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: event-statistics
+description: Inspect current task outcomes using best-effort Studio notifications and business receipts.
+---
+
+Install the paired event-capable CLI, project-studio and this package. Enable this
+example in a project with `studioInstance` and `dataInstance` bound to the existing
+project studio and workspace data providers. Grant `events.subscribe` explicitly
+when enabling the package; projects do not need notification-specific grants.
+Read `statistics.current` through the existing operation bridge.
+
+Every new subscription waits for ready and then paginates current tasks. A task,
+attempt, remote semantic revision and outcome form the business request key. The
+existing DataAPI receipt prevents duplicate effects. Counts come from current task
+snapshots, never the number of notifications. Disconnecting loses intermediate
+notices; restarting synchronizes current facts without generating anything.
+
+`statistics.current` reads every page of the project's persisted task costs and
+returns exact decimal totals by unit plus an unknown count. Actual amounts come
+from I4's validated `billing.status` and `billing.credits`, not event payloads.
+Released zero and settled zero stay distinct from unknown costs. Local revisions
+order accepted snapshots; they do not order different confirmed upstream amounts.
+
+Automatic cost recovery uses one persisted 18-second window per original task,
+with at most five serial attempts targeted at 0, 2, 4, 10, and 15 seconds. Confirmation,
+exhaustion, or the deadline stops recovery. Unknown costs can remain unknown.
+`tasks.queryOriginal` retains manual reading without restarting that window.
+Refunds and adjustments are outside this example's contract. Developer fixtures
+and package checks do not prove real settlement or production activation.

package/studio-plugin.json

@@ -0,0 +1,11 @@
+{
+  "manifestVersion": "0.2",
+  "id": "event-statistics",
+  "requirements": {
+    "studioPluginApi": "^0.2.2"
+  },
+  "requestedAccess": ["events.subscribe"],
+  "resources": {
+    "skills": ["skills/SKILL.md"]
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.