@forgezero/runtime 0.1.25 → 0.1.27

package/README.md

@@ -7,7 +7,7 @@
 
 # Platform runtime
 
-The machinery behind a request handler — jobs, queues, an outbox, a hash-chained audit trail, mail, backups, schema validation and exact money. 32 public modules, each imported on its own.
+The machinery behind a request handler — jobs, queues, an outbox, a hash-chained audit trail, mail, backups, schema validation and exact money. 33 public modules, each imported on its own.
 
 ## Package overview
 
@@ -62,6 +62,7 @@ These are supported consumer entry points, not every internal module shipped for
 | @forgezero/runtime/finance/tax | Which jurisdiction may tax a sale, who accounts for it, and the three ways to be zero that report differently. Rates are data. | portable | [Reference + usage](#forgezero-runtime-finance-tax) |
 | @forgezero/runtime/finance/storage | Write an amount so it is both exact and sortable: an authoritative string, and a number that is only an index. | portable | [Reference + usage](#forgezero-runtime-finance-storage) |
 | @forgezero/runtime/realtime | Provider-neutral realtime audience, shard, event and delivery contracts. | portable | [Reference + usage](#forgezero-runtime-realtime) |
+| @forgezero/runtime/operation | Revisioned surface, operation-state and bounded redacted operation-log contracts. | portable | [Reference + usage](#forgezero-runtime-operation) |
 | @forgezero/runtime/passkey-hybrid | Versioned WebAuthn PRF plus ML-DSA companion proof construction and verification. | portable | [Reference + usage](#forgezero-runtime-passkey-hybrid) |
 | @forgezero/runtime/otpauth | Parse and render otpauth URIs without binding enrolment to a UI framework. | portable | [Reference + usage](#forgezero-runtime-otpauth) |
 | @forgezero/runtime/pipeline | Typed ordered application-pipeline execution with explicit evidence. | portable | [Reference + usage](#forgezero-runtime-pipeline) |
@@ -722,7 +723,7 @@ Provider-neutral realtime audience, shard, event and delivery contracts. This is
 
 ```text
 import {
-  REALTIME_MAX_BATCH_BYTES,
+  REALTIME_FLUSH_BATCH_BYTES,
 } from '@forgezero/runtime/realtime';
 ```
 
@@ -732,10 +733,33 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  REALTIME_MAX_BATCH_BYTES,
+  REALTIME_FLUSH_BATCH_BYTES,
 } from '@forgezero/runtime/realtime';
 
-export const selectedCapability = REALTIME_MAX_BATCH_BYTES;
+export const selectedCapability = REALTIME_FLUSH_BATCH_BYTES;
+```
+
+<a id="forgezero-runtime-operation"></a>
+## @forgezero/runtime/operation
+
+Revisioned surface, operation-state and bounded redacted operation-log contracts. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
+
+```text
+import {
+  OPERATION_MAX_EVENTS,
+} from '@forgezero/runtime/operation';
+```
+
+## @forgezero/runtime/operation — Use this entry point
+
+This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
+
+```text
+import {
+  OPERATION_MAX_EVENTS,
+} from '@forgezero/runtime/operation';
+
+export const selectedCapability = OPERATION_MAX_EVENTS;
 ```
 
 <a id="forgezero-runtime-passkey-hybrid"></a>

package/dist/operation.d.ts

@@ -0,0 +1,64 @@
+/** A revisioned read model returned by one bounded application surface. */
+export interface SurfaceSnapshot<T> {
+    revision: string;
+    generatedAtTs: number;
+    data: T;
+}
+export declare const OPERATION_STATUSES: readonly ["queued", "running", "stalled", "failed", "succeeded", "cancelled", "compensating", "compensated"];
+export type OperationStatus = (typeof OPERATION_STATUSES)[number];
+export type OperationEventOrigin = 'platform-api' | 'bootstrap-runner' | 'metal-agent' | 'compute-agent' | 'worker';
+export interface OperationFailure {
+    code: string;
+    detail: string;
+    retryable: boolean;
+}
+export interface OperationEvent {
+    sequence: number;
+    stage: string;
+    status: OperationStatus;
+    atTs: number;
+    attempt: number;
+    origin: OperationEventOrigin;
+    nodeKey?: string;
+    failure?: OperationFailure;
+}
+export interface OperationSnapshot {
+    operationKey: string;
+    kind: string;
+    correlationId: string;
+    parentOperationKey?: string;
+    childOperationKeys: readonly string[];
+    stage: string;
+    status: OperationStatus;
+    attempt: number;
+    revision: number;
+    createdAtTs: number;
+    updatedAtTs: number;
+    lastHeartbeatAtTs?: number;
+    deadlineAtTs?: number;
+    leaseOwner?: string;
+    failure?: OperationFailure;
+    events: readonly OperationEvent[];
+}
+export interface OperationLogLine {
+    sequence: number;
+    atTs: number;
+    stream: 'stdout' | 'stderr' | 'system';
+    text: string;
+}
+export interface OperationLogBatch {
+    operationKey: string;
+    fromSequence: number;
+    toSequence: number;
+    terminal: boolean;
+    lines: readonly OperationLogLine[];
+}
+export declare const OPERATION_MAX_EVENTS = 128;
+export declare const OPERATION_MAX_LOG_LINES = 100;
+export declare const OPERATION_MAX_LOG_TEXT_BYTES: number;
+/** Redact common credential forms before an operation line reaches storage or a socket. */
+export declare function redactOperationLogText(input: string): string;
+export declare function validateSurfaceSnapshot<T>(input: unknown, validateData: (value: unknown) => value is T): SurfaceSnapshot<T>;
+export declare function validateOperationFailure(input: unknown): OperationFailure;
+export declare function validateOperationSnapshot(input: unknown): OperationSnapshot;
+export declare function validateOperationLogBatch(input: unknown): OperationLogBatch;

package/dist/operation.js

@@ -0,0 +1,107 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/operation.ts
+var OPERATION_STATUSES = [
+  "queued",
+  "running",
+  "stalled",
+  "failed",
+  "succeeded",
+  "cancelled",
+  "compensating",
+  "compensated"
+];
+var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;
+var FAILURE_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+var OPERATION_MAX_EVENTS = 128;
+var OPERATION_MAX_LOG_LINES = 100;
+var OPERATION_MAX_LOG_TEXT_BYTES = 8 * 1024;
+function redactOperationLogText(input) {
+  return input.replace(/-----BEGIN [^-]+PRIVATE KEY-----[\s\S]*?-----END [^-]+PRIVATE KEY-----/gi, "[REDACTED_PRIVATE_KEY]").replace(/\b(?:Bearer\s+)?(?:gh[opsu]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|fze_[A-Za-z0-9_-]{16,})\b/gi, "[REDACTED_TOKEN]").replace(/\b(password|secret|token|api[_-]?key)\s*[:=]\s*([^\s,;]+)/gi, "$1=[REDACTED]").slice(0, OPERATION_MAX_LOG_TEXT_BYTES);
+}
+var finiteEpoch = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+var atom = (value) => typeof value === "string" && ATOM.test(value);
+function validateSurfaceSnapshot(input, validateData) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Surface snapshot must be an object.");
+  const row = input;
+  if (!atom(row.revision) || !finiteEpoch(row.generatedAtTs) || !validateData(row.data)) {
+    throw new Error("Surface snapshot is invalid.");
+  }
+  return { revision: row.revision, generatedAtTs: row.generatedAtTs, data: row.data };
+}
+function validateOperationFailure(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Operation failure must be an object.");
+  const row = input;
+  if (typeof row.code !== "string" || !FAILURE_CODE.test(row.code) || typeof row.detail !== "string" || !row.detail.trim() || new TextEncoder().encode(row.detail).byteLength > 2000 || typeof row.retryable !== "boolean") {
+    throw new Error("Operation failure is invalid.");
+  }
+  return { code: row.code, detail: row.detail.trim(), retryable: row.retryable };
+}
+function validateOperationSnapshot(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Operation snapshot must be an object.");
+  const row = input;
+  if (!atom(row.operationKey) || !atom(row.kind) || !atom(row.correlationId) || row.parentOperationKey !== undefined && !atom(row.parentOperationKey) || !Array.isArray(row.childOperationKeys) || row.childOperationKeys.length > 128 || row.childOperationKeys.some((key) => !atom(key)) || !atom(row.stage) || !OPERATION_STATUSES.includes(row.status) || !Number.isSafeInteger(row.attempt) || row.attempt < 1 || !Number.isSafeInteger(row.revision) || row.revision < 1 || !finiteEpoch(row.createdAtTs) || !finiteEpoch(row.updatedAtTs) || row.updatedAtTs < row.createdAtTs || row.lastHeartbeatAtTs !== undefined && !finiteEpoch(row.lastHeartbeatAtTs) || row.deadlineAtTs !== undefined && !finiteEpoch(row.deadlineAtTs) || row.leaseOwner !== undefined && !atom(row.leaseOwner) || !Array.isArray(row.events) || row.events.length < 1 || row.events.length > OPERATION_MAX_EVENTS) {
+    throw new Error("Operation snapshot coordinates are invalid.");
+  }
+  const events = row.events.map((event, index) => {
+    if (!event || typeof event !== "object" || Array.isArray(event))
+      throw new Error("Operation event is invalid.");
+    const value = event;
+    if (value.sequence !== index + 1 || !atom(value.stage) || !OPERATION_STATUSES.includes(value.status) || !finiteEpoch(value.atTs) || !Number.isSafeInteger(value.attempt) || value.attempt < 1 || !["platform-api", "bootstrap-runner", "metal-agent", "compute-agent", "worker"].includes(String(value.origin)) || value.nodeKey !== undefined && !atom(value.nodeKey))
+      throw new Error("Operation event is invalid.");
+    return { ...value, ...value.failure ? { failure: validateOperationFailure(value.failure) } : {} };
+  });
+  return {
+    ...row,
+    childOperationKeys: [...row.childOperationKeys],
+    ...row.failure ? { failure: validateOperationFailure(row.failure) } : {},
+    events
+  };
+}
+function validateOperationLogBatch(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Operation log batch must be an object.");
+  const row = input;
+  if (!atom(row.operationKey) || !Number.isSafeInteger(row.fromSequence) || !Number.isSafeInteger(row.toSequence) || row.fromSequence < 1 || row.toSequence < row.fromSequence || typeof row.terminal !== "boolean" || !Array.isArray(row.lines) || row.lines.length < 1 || row.lines.length > OPERATION_MAX_LOG_LINES) {
+    throw new Error("Operation log batch coordinates are invalid.");
+  }
+  const lines = row.lines.map((line, index) => {
+    if (!line || typeof line !== "object" || Array.isArray(line))
+      throw new Error("Operation log line is invalid.");
+    const value = line;
+    const expected = row.fromSequence + index;
+    if (value.sequence !== expected || !finiteEpoch(value.atTs) || !["stdout", "stderr", "system"].includes(String(value.stream)) || typeof value.text !== "string" || !value.text || new TextEncoder().encode(value.text).byteLength > OPERATION_MAX_LOG_TEXT_BYTES) {
+      throw new Error("Operation log line is invalid or non-contiguous.");
+    }
+    return { sequence: value.sequence, atTs: value.atTs, stream: value.stream, text: redactOperationLogText(value.text) };
+  });
+  if (lines.at(-1).sequence !== row.toSequence)
+    throw new Error("Operation log range does not match its lines.");
+  return {
+    operationKey: row.operationKey,
+    fromSequence: row.fromSequence,
+    toSequence: row.toSequence,
+    terminal: row.terminal,
+    lines
+  };
+}
+export {
+  validateSurfaceSnapshot,
+  validateOperationSnapshot,
+  validateOperationLogBatch,
+  validateOperationFailure,
+  redactOperationLogText,
+  OPERATION_STATUSES,
+  OPERATION_MAX_LOG_TEXT_BYTES,
+  OPERATION_MAX_LOG_LINES,
+  OPERATION_MAX_EVENTS
+};

package/dist/realtime.d.ts

@@ -1,13 +1,80 @@
 export declare const REALTIME_MAX_EVENTS = 100;
 export declare const REALTIME_MAX_EVENT_BYTES: number;
 export declare const REALTIME_MAX_BATCH_BYTES: number;
+export declare const REALTIME_FLUSH_BATCH_BYTES: number;
 export declare const REALTIME_MAX_SOCKETS_PER_SHARD = 1000;
 export declare const REALTIME_MAX_SHARDS_PER_TOPIC = 1024;
-export interface RealtimeEvent {
+export type RealtimeResourceScope = Readonly<{
+    realmId: string;
+    projectKey?: string;
+}>;
+export type RealtimeEvent = Readonly<{
+    id: string;
+    type: 'resource.patch';
+    payload: {
+        scope: RealtimeResourceScope;
+        resourceKind: string;
+        resourceKey: string;
+        previousRevision?: string;
+        revision: string;
+        projection: unknown;
+    };
+}> | Readonly<{
+    id: string;
+    type: 'operation.state';
+    payload: {
+        operationKey: string;
+        parentOperationKey?: string;
+        kind: string;
+        stage: string;
+        status: string;
+        attempt: number;
+        revision: number;
+        updatedAtTs: number;
+        failure?: {
+            code: string;
+            detail: string;
+            retryable: boolean;
+        };
+    };
+}> | Readonly<{
+    id: string;
+    type: 'operation.log';
+    payload: {
+        operationKey: string;
+        fromSequence: number;
+        toSequence: number;
+        terminal: boolean;
+        lines: readonly {
+            sequence: number;
+            atTs: number;
+            stream: 'stdout' | 'stderr' | 'system';
+            text: string;
+        }[];
+    };
+}> | Readonly<{
+    id: string;
+    type: 'notification.summary';
+    payload: {
+        unread: number;
+        latest?: {
+            key: string;
+            title: string;
+            message: string;
+            tone: 'warning' | 'error' | 'info';
+        };
+    };
+}> | Readonly<{
+    id: string;
+    type: 'session.changed';
+    payload: {
+        revision: string;
+    };
+}> | Readonly<{
     id: string;
     type: string;
     payload: unknown;
-}
+}>;
 export type RealtimePrincipalKind = 'user' | 'node' | 'api-key' | 'service' | 'header';
 export type RealtimeAudience = Readonly<{
     kind: 'public';
@@ -29,7 +96,7 @@ export type RealtimeAudience = Readonly<{
     capability: string;
 }>;
 export interface RealtimeBatch {
-    version: 2;
+    version: 2 | 3;
     batchId: string;
     topic: string;
     audience: RealtimeAudience;
@@ -40,7 +107,7 @@ export declare function validateRealtimeAudience(input: unknown): RealtimeAudien
 export declare function validateRealtimeBatch(input: unknown): RealtimeBatch;
 export declare const realtimeBatchBytes: (input: unknown) => string;
 export interface RealtimeSubscriptionTicket {
-    version: 2;
+    version: 2 | 3;
     topic: string;
     principal: Readonly<{
         kind: RealtimePrincipalKind;
@@ -50,9 +117,20 @@ export interface RealtimeSubscriptionTicket {
     projectKeys: readonly string[];
     groups: readonly string[];
     capabilities: readonly string[];
+    subscriptions?: readonly RealtimeSubscription[];
     expiresAtSec: number;
     nonce: string;
 }
+export type RealtimeSubscription = Readonly<{
+    kind: 'notifications';
+}> | Readonly<{
+    kind: 'project';
+    projectKey: string;
+}> | Readonly<{
+    kind: 'operation';
+    operationKey: string;
+    logs: boolean;
+}>;
 export declare function validateRealtimeSubscriptionTicket(input: unknown, nowSec?: number): RealtimeSubscriptionTicket;
 /**
  * The edge has no database authority. It may deliver only when the short-lived,
@@ -61,7 +139,11 @@ export declare function validateRealtimeSubscriptionTicket(input: unknown, nowSe
  * decision.
  */
 export declare function canReceiveRealtimeAudience(ticket: RealtimeSubscriptionTicket, audience: RealtimeAudience): boolean;
+/** v3 tickets authorize the logical stream in addition to its audience. */
+export declare function canReceiveRealtimeEvent(ticket: RealtimeSubscriptionTicket, event: RealtimeEvent): boolean;
 export declare const realtimeShardKey: (topic: string, shard: number) => string;
+/** Stable principal bucket. No directory read is needed to route a principal event. */
+export declare function realtimePrincipalTopic(realmId: string, principalKey: string, buckets?: number): string;
 export declare function realtimeHmac(secret: string, message: string): Promise<string>;
 export declare function verifyRealtimeHmac(secret: string, message: string, signature: string): Promise<boolean>;
 export declare function issueRealtimeSubscriptionTicket(secret: string, ticket: RealtimeSubscriptionTicket, nowSec?: number): Promise<string>;

package/dist/realtime.js

@@ -6,15 +6,105 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/operation.ts
+var OPERATION_STATUSES = [
+  "queued",
+  "running",
+  "stalled",
+  "failed",
+  "succeeded",
+  "cancelled",
+  "compensating",
+  "compensated"
+];
+var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;
+var FAILURE_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+var OPERATION_MAX_EVENTS = 128;
+var OPERATION_MAX_LOG_LINES = 100;
+var OPERATION_MAX_LOG_TEXT_BYTES = 8 * 1024;
+function redactOperationLogText(input) {
+  return input.replace(/-----BEGIN [^-]+PRIVATE KEY-----[\s\S]*?-----END [^-]+PRIVATE KEY-----/gi, "[REDACTED_PRIVATE_KEY]").replace(/\b(?:Bearer\s+)?(?:gh[opsu]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|fze_[A-Za-z0-9_-]{16,})\b/gi, "[REDACTED_TOKEN]").replace(/\b(password|secret|token|api[_-]?key)\s*[:=]\s*([^\s,;]+)/gi, "$1=[REDACTED]").slice(0, OPERATION_MAX_LOG_TEXT_BYTES);
+}
+var finiteEpoch = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+var atom = (value) => typeof value === "string" && ATOM.test(value);
+function validateSurfaceSnapshot(input, validateData) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Surface snapshot must be an object.");
+  const row = input;
+  if (!atom(row.revision) || !finiteEpoch(row.generatedAtTs) || !validateData(row.data)) {
+    throw new Error("Surface snapshot is invalid.");
+  }
+  return { revision: row.revision, generatedAtTs: row.generatedAtTs, data: row.data };
+}
+function validateOperationFailure(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Operation failure must be an object.");
+  const row = input;
+  if (typeof row.code !== "string" || !FAILURE_CODE.test(row.code) || typeof row.detail !== "string" || !row.detail.trim() || new TextEncoder().encode(row.detail).byteLength > 2000 || typeof row.retryable !== "boolean") {
+    throw new Error("Operation failure is invalid.");
+  }
+  return { code: row.code, detail: row.detail.trim(), retryable: row.retryable };
+}
+function validateOperationSnapshot(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Operation snapshot must be an object.");
+  const row = input;
+  if (!atom(row.operationKey) || !atom(row.kind) || !atom(row.correlationId) || row.parentOperationKey !== undefined && !atom(row.parentOperationKey) || !Array.isArray(row.childOperationKeys) || row.childOperationKeys.length > 128 || row.childOperationKeys.some((key) => !atom(key)) || !atom(row.stage) || !OPERATION_STATUSES.includes(row.status) || !Number.isSafeInteger(row.attempt) || row.attempt < 1 || !Number.isSafeInteger(row.revision) || row.revision < 1 || !finiteEpoch(row.createdAtTs) || !finiteEpoch(row.updatedAtTs) || row.updatedAtTs < row.createdAtTs || row.lastHeartbeatAtTs !== undefined && !finiteEpoch(row.lastHeartbeatAtTs) || row.deadlineAtTs !== undefined && !finiteEpoch(row.deadlineAtTs) || row.leaseOwner !== undefined && !atom(row.leaseOwner) || !Array.isArray(row.events) || row.events.length < 1 || row.events.length > OPERATION_MAX_EVENTS) {
+    throw new Error("Operation snapshot coordinates are invalid.");
+  }
+  const events = row.events.map((event, index) => {
+    if (!event || typeof event !== "object" || Array.isArray(event))
+      throw new Error("Operation event is invalid.");
+    const value = event;
+    if (value.sequence !== index + 1 || !atom(value.stage) || !OPERATION_STATUSES.includes(value.status) || !finiteEpoch(value.atTs) || !Number.isSafeInteger(value.attempt) || value.attempt < 1 || !["platform-api", "bootstrap-runner", "metal-agent", "compute-agent", "worker"].includes(String(value.origin)) || value.nodeKey !== undefined && !atom(value.nodeKey))
+      throw new Error("Operation event is invalid.");
+    return { ...value, ...value.failure ? { failure: validateOperationFailure(value.failure) } : {} };
+  });
+  return {
+    ...row,
+    childOperationKeys: [...row.childOperationKeys],
+    ...row.failure ? { failure: validateOperationFailure(row.failure) } : {},
+    events
+  };
+}
+function validateOperationLogBatch(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Operation log batch must be an object.");
+  const row = input;
+  if (!atom(row.operationKey) || !Number.isSafeInteger(row.fromSequence) || !Number.isSafeInteger(row.toSequence) || row.fromSequence < 1 || row.toSequence < row.fromSequence || typeof row.terminal !== "boolean" || !Array.isArray(row.lines) || row.lines.length < 1 || row.lines.length > OPERATION_MAX_LOG_LINES) {
+    throw new Error("Operation log batch coordinates are invalid.");
+  }
+  const lines = row.lines.map((line, index) => {
+    if (!line || typeof line !== "object" || Array.isArray(line))
+      throw new Error("Operation log line is invalid.");
+    const value = line;
+    const expected = row.fromSequence + index;
+    if (value.sequence !== expected || !finiteEpoch(value.atTs) || !["stdout", "stderr", "system"].includes(String(value.stream)) || typeof value.text !== "string" || !value.text || new TextEncoder().encode(value.text).byteLength > OPERATION_MAX_LOG_TEXT_BYTES) {
+      throw new Error("Operation log line is invalid or non-contiguous.");
+    }
+    return { sequence: value.sequence, atTs: value.atTs, stream: value.stream, text: redactOperationLogText(value.text) };
+  });
+  if (lines.at(-1).sequence !== row.toSequence)
+    throw new Error("Operation log range does not match its lines.");
+  return {
+    operationKey: row.operationKey,
+    fromSequence: row.fromSequence,
+    toSequence: row.toSequence,
+    terminal: row.terminal,
+    lines
+  };
+}
+
 // src/realtime.ts
 var REALTIME_MAX_EVENTS = 100;
 var REALTIME_MAX_EVENT_BYTES = 64 * 1024;
 var REALTIME_MAX_BATCH_BYTES = 512 * 1024;
+var REALTIME_FLUSH_BATCH_BYTES = 256 * 1024;
 var REALTIME_MAX_SOCKETS_PER_SHARD = 1000;
 var REALTIME_MAX_SHARDS_PER_TOPIC = 1024;
-var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;
+var ATOM2 = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;
 var PRINCIPAL_KINDS = new Set(["user", "node", "api-key", "service", "header"]);
-var atom = (value) => typeof value === "string" && ATOM.test(value);
+var atom2 = (value) => typeof value === "string" && ATOM2.test(value);
 function validateRealtimeAudience(input) {
   if (!input || typeof input !== "object" || Array.isArray(input))
     throw new Error("Realtime audience must be an object.");
@@ -24,9 +114,9 @@ function validateRealtimeAudience(input) {
       throw new Error("Public realtime audience has no additional coordinates.");
     return { kind: "public" };
   }
-  if (!atom(row.realmId) || !atom(row.capability))
+  if (!atom2(row.realmId) || !atom2(row.capability))
     throw new Error("Realtime audience scope is invalid.");
-  if (row.kind === "principal" && PRINCIPAL_KINDS.has(row.principalKind) && atom(row.principalKey)) {
+  if (row.kind === "principal" && PRINCIPAL_KINDS.has(row.principalKind) && atom2(row.principalKey)) {
     return {
       kind: "principal",
       realmId: row.realmId,
@@ -35,10 +125,10 @@ function validateRealtimeAudience(input) {
       capability: row.capability
     };
   }
-  if (row.kind === "project" && atom(row.projectKey)) {
+  if (row.kind === "project" && atom2(row.projectKey)) {
     return { kind: "project", realmId: row.realmId, projectKey: row.projectKey, capability: row.capability };
   }
-  if (row.kind === "group" && atom(row.group)) {
+  if (row.kind === "group" && atom2(row.group)) {
     return { kind: "group", realmId: row.realmId, group: row.group, capability: row.capability };
   }
   throw new Error("Realtime audience coordinates are invalid.");
@@ -47,25 +137,34 @@ function validateRealtimeBatch(input) {
   if (!input || typeof input !== "object" || Array.isArray(input))
     throw new Error("Realtime batch must be an object.");
   const row = input;
-  if (row.version !== 2 || !ATOM.test(row.batchId ?? "") || !ATOM.test(row.topic ?? "") || !Number.isSafeInteger(row.publishedAtMs) || row.publishedAtMs < 0 || !Array.isArray(row.events) || row.events.length < 1 || row.events.length > REALTIME_MAX_EVENTS)
+  if (row.version !== 2 && row.version !== 3 || !ATOM2.test(row.batchId ?? "") || !ATOM2.test(row.topic ?? "") || !Number.isSafeInteger(row.publishedAtMs) || row.publishedAtMs < 0 || !Array.isArray(row.events) || row.events.length < 1 || row.events.length > REALTIME_MAX_EVENTS)
     throw new Error("Realtime batch coordinates are invalid.");
   const audience = validateRealtimeAudience(row.audience);
   const events = row.events.map((event) => {
     if (!event || typeof event !== "object" || Array.isArray(event))
       throw new Error("Realtime event must be an object.");
     const value = event;
-    if (!ATOM.test(value.id ?? "") || !ATOM.test(value.type ?? ""))
+    if (!ATOM2.test(value.id ?? "") || !ATOM2.test(value.type ?? ""))
       throw new Error("Realtime event id/type is invalid.");
     const encoded = JSON.stringify(value.payload);
     if (encoded === undefined || new TextEncoder().encode(encoded).byteLength > REALTIME_MAX_EVENT_BYTES) {
       throw new Error("Realtime event payload is too large or not JSON serializable.");
     }
+    if (row.version === 3 && value.type === "operation.log")
+      validateOperationLogBatch(value.payload);
+    if (row.version === 3 && value.type === "resource.patch") {
+      const payload = value.payload;
+      const scope = payload.scope;
+      if (!scope || !atom2(scope.realmId) || scope.projectKey !== undefined && !atom2(scope.projectKey) || !atom2(payload.resourceKind) || !atom2(payload.resourceKey) || !atom2(payload.revision) || payload.previousRevision !== undefined && !atom2(payload.previousRevision)) {
+        throw new Error("Realtime resource patch is invalid.");
+      }
+    }
     return { id: value.id, type: value.type, payload: value.payload };
   });
   if (new Set(events.map(({ id }) => id)).size !== events.length)
     throw new Error("Realtime event ids must be unique in a batch.");
   const batch = {
-    version: 2,
+    version: row.version,
     batchId: row.batchId,
     topic: row.topic,
     audience,
@@ -78,8 +177,26 @@ function validateRealtimeBatch(input) {
   return batch;
 }
 var realtimeBatchBytes = (input) => JSON.stringify(validateRealtimeBatch(input));
+function validateSubscriptions(value) {
+  if (!Array.isArray(value) || value.length > 64)
+    throw new Error("Realtime ticket subscriptions are invalid.");
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      throw new Error("Realtime subscription is invalid.");
+    const row = item;
+    if (row.kind === "notifications" && Object.keys(row).length === 1)
+      return { kind: "notifications" };
+    if (row.kind === "project" && atom2(row.projectKey) && Object.keys(row).length === 2) {
+      return { kind: "project", projectKey: row.projectKey };
+    }
+    if (row.kind === "operation" && atom2(row.operationKey) && typeof row.logs === "boolean" && Object.keys(row).length === 3) {
+      return { kind: "operation", operationKey: row.operationKey, logs: row.logs };
+    }
+    throw new Error("Realtime subscription is invalid.");
+  });
+}
 function boundedUniqueAtoms(value, maximum, label) {
-  if (!Array.isArray(value) || value.length > maximum || value.some((item) => !atom(item)) || new Set(value).size !== value.length)
+  if (!Array.isArray(value) || value.length > maximum || value.some((item) => !atom2(item)) || new Set(value).size !== value.length)
     throw new Error(`Realtime ticket ${label} are invalid.`);
   return [...value];
 }
@@ -87,16 +204,17 @@ function validateRealtimeSubscriptionTicket(input, nowSec = Math.floor(Date.now(
   if (!input || typeof input !== "object" || Array.isArray(input))
     throw new Error("Realtime ticket must be an object.");
   const row = input;
-  if (row.version !== 2 || !atom(row.topic) || !atom(row.realmId) || !atom(row.nonce) || !row.principal || !PRINCIPAL_KINDS.has(row.principal.kind) || !atom(row.principal.key) || !Number.isSafeInteger(row.expiresAtSec) || row.expiresAtSec <= nowSec || row.expiresAtSec > nowSec + 300)
+  if (row.version !== 2 && row.version !== 3 || !atom2(row.topic) || !atom2(row.realmId) || !atom2(row.nonce) || !row.principal || !PRINCIPAL_KINDS.has(row.principal.kind) || !atom2(row.principal.key) || !Number.isSafeInteger(row.expiresAtSec) || row.expiresAtSec <= nowSec || row.expiresAtSec > nowSec + 300 || row.version === 3 && !Array.isArray(row.subscriptions))
     throw new Error("Realtime ticket is invalid or expired.");
   return {
-    version: 2,
+    version: row.version,
     topic: row.topic,
     principal: { kind: row.principal.kind, key: row.principal.key },
     realmId: row.realmId,
     projectKeys: boundedUniqueAtoms(row.projectKeys, 32, "project keys"),
     groups: boundedUniqueAtoms(row.groups, 16, "groups"),
     capabilities: boundedUniqueAtoms(row.capabilities, 64, "capabilities"),
+    ...row.version === 3 ? { subscriptions: validateSubscriptions(row.subscriptions) } : {},
     expiresAtSec: row.expiresAtSec,
     nonce: row.nonce
   };
@@ -113,12 +231,40 @@ function canReceiveRealtimeAudience(ticket, audience) {
     return ticket.projectKeys.includes(audience.projectKey);
   return ticket.groups.includes(audience.group);
 }
+function canReceiveRealtimeEvent(ticket, event) {
+  if (ticket.version === 2)
+    return true;
+  const subscriptions = ticket.subscriptions ?? [];
+  if (event.type === "notification.summary") {
+    return subscriptions.some(({ kind }) => kind === "notifications");
+  }
+  if (event.type === "operation.state" || event.type === "operation.log") {
+    const operationKey = event.payload.operationKey;
+    return typeof operationKey === "string" && subscriptions.some((subscription) => subscription.kind === "operation" && subscription.operationKey === operationKey && (event.type !== "operation.log" || subscription.logs));
+  }
+  if (event.type === "resource.patch") {
+    const projectKey = event.payload.scope?.projectKey;
+    return typeof projectKey !== "string" || subscriptions.some((subscription) => subscription.kind === "project" && subscription.projectKey === projectKey);
+  }
+  return true;
+}
 var realtimeShardKey = (topic, shard) => {
-  if (!ATOM.test(topic) || !Number.isSafeInteger(shard) || shard < 0 || shard >= REALTIME_MAX_SHARDS_PER_TOPIC) {
+  if (!ATOM2.test(topic) || !Number.isSafeInteger(shard) || shard < 0 || shard >= REALTIME_MAX_SHARDS_PER_TOPIC) {
     throw new Error("Realtime shard coordinates are invalid.");
   }
   return `rt:${topic}:${shard.toString().padStart(4, "0")}`;
 };
+function realtimePrincipalTopic(realmId, principalKey, buckets = 256) {
+  if (!atom2(realmId) || !atom2(principalKey) || !Number.isSafeInteger(buckets) || buckets < 1 || buckets > 4096) {
+    throw new Error("Realtime principal partition coordinates are invalid.");
+  }
+  let hash = 2166136261;
+  for (const byte of new TextEncoder().encode(`${realmId}\x00${principalKey}`)) {
+    hash ^= byte;
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return `principal:${realmId}:${hash % buckets}`;
+}
 var bytesToHex = (bytes) => [...bytes].map((value) => value.toString(16).padStart(2, "0")).join("");
 var timingEqual = (left, right) => {
   if (left.length !== right.length)
@@ -172,13 +318,16 @@ export {
   validateRealtimeBatch,
   validateRealtimeAudience,
   realtimeShardKey,
+  realtimePrincipalTopic,
   realtimeHmac,
   realtimeBatchBytes,
   issueRealtimeSubscriptionTicket,
+  canReceiveRealtimeEvent,
   canReceiveRealtimeAudience,
   REALTIME_MAX_SOCKETS_PER_SHARD,
   REALTIME_MAX_SHARDS_PER_TOPIC,
   REALTIME_MAX_EVENT_BYTES,
   REALTIME_MAX_EVENTS,
-  REALTIME_MAX_BATCH_BYTES
+  REALTIME_MAX_BATCH_BYTES,
+  REALTIME_FLUSH_BATCH_BYTES
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/runtime",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -51,6 +51,10 @@
       "types": "./dist/realtime.d.ts",
       "default": "./dist/realtime.js"
     },
+    "./operation": {
+      "types": "./dist/operation.d.ts",
+      "default": "./dist/operation.js"
+    },
     "./lifecycle": {
       "types": "./dist/lifecycle.d.ts",
       "default": "./dist/lifecycle.js"
@@ -142,7 +146,7 @@
     "prepublishOnly": "bun ../tools/package-task.ts prepublish runtime"
   },
   "dependencies": {
-    "@forgezero/access": "^0.1.14"
+    "@forgezero/access": "^0.1.15"
   },
   "peerDependencies": {
     "@noble/ciphers": "^2.2.0",