@forgezero/runtime 0.1.24 → 0.1.26

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>
@@ -814,7 +838,7 @@ Threshold-share parsing, validation and reconstruction. This is a supported entr
 
 ```text
 import {
-  PROBE_BYTES,
+  CUSTODY_ENVELOPE_SUITE,
 } from '@forgezero/runtime/custody-share';
 ```
 
@@ -824,10 +848,10 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  PROBE_BYTES,
+  CUSTODY_ENVELOPE_SUITE,
 } from '@forgezero/runtime/custody-share';
 
-export const selectedCapability = PROBE_BYTES;
+export const selectedCapability = CUSTODY_ENVELOPE_SUITE;
 ```
 
 <a id="forgezero-runtime-custody-crypto"></a>

package/dist/custody-share.d.ts

@@ -1,8 +1,55 @@
 import { type CipherBox, type SealedToKey } from './custody-crypto';
+export declare const CUSTODY_ENVELOPE_VERSION: 3;
+export declare const CUSTODY_ENVELOPE_SUITE: "ml-kem-768+x25519+hkdf-sha256+aes-256-gcm+ml-dsa-65";
+export declare const CUSTODY_FACTOR_PROOF_VERSION: 1;
+export type CustodyCredentialPurpose = 'custody';
+export type CustodyCredentialLifecycle = 'pending' | 'active' | 'retired';
+export type CustodyFactor = 'ceremony_passkey' | 'recovery_phrase';
+export type CustodyEnvelopeGeneration = number;
+export type CustodyTransactionOutcome = 'completed' | 'factor_mismatch' | 'credential_mismatch' | 'replayed' | 'expired' | 'batch_mismatch' | 'seed_fingerprint_mismatch';
+export interface CustodyFactorBinding {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    realmId: string;
+    ceremonyKey: string;
+    custodianKey: string;
+    factor: CustodyFactor;
+    requestKey: string;
+    method: 'POST';
+    path: string;
+    payloadDigest: string;
+    challenge: string;
+    expiresAtSec: number;
+}
+export interface CustodyPasskeyProofV1 {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    factor: 'ceremony_passkey';
+    credentialId: string;
+    signature: string;
+}
+export interface CustodyPhraseProofV1 {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    factor: 'recovery_phrase';
+    signature: string;
+}
+export type CustodyFactorProof = CustodyPasskeyProofV1 | CustodyPhraseProofV1;
+export interface CustodyActionRequest {
+    _key: string;
+    ceremonyKey: string;
+    ownerUserKey: string;
+    operation: 'seal' | 'verify' | 'reshare' | 'unlock' | 'rotate' | 'verify_rotation';
+    allowedFactors: CustodyFactor[];
+    payloadDigest: string;
+    challenge: string;
+    status: 'open' | 'consumed' | 'expired';
+    expiresAtSec: number;
+    revision: number;
+}
 export interface SealedShare {
     shareIndex: number;
-    /** Account credential whose PRF deterministically derives this passkey key. */
+    /** Dedicated custody credential whose PRF deterministically derives this passkey key. */
     passkeyCredentialId?: string;
+    /** Base64url ceremony salt persisted with that exact custody credential. */
+    passkeyPrfSalt?: string;
     passkeyEnvelope: CipherBox;
     phraseEnvelope: CipherBox;
     /** base64 — the HKDF salt for the phrase key and the verifier. */
@@ -10,6 +57,22 @@ export interface SealedShare {
     /** hex — proves the right phrase without being able to rebuild it. */
     phraseVerifier: string;
 }
+/** New writes use this shape. V2 is retained only for bounded unlock-and-rotate migration. */
+export interface CustodyEnvelopeV3 extends SealedShare {
+    version: typeof CUSTODY_ENVELOPE_VERSION;
+    suite: typeof CUSTODY_ENVELOPE_SUITE;
+    generation: CustodyEnvelopeGeneration;
+    passkeyGeneration?: CustodyEnvelopeGeneration;
+    phraseGeneration?: CustodyEnvelopeGeneration;
+    realmId: string;
+    ceremonyKey: string;
+    custodianKey: string;
+    passkeyCredentialId: string;
+    passkeyPrfSalt: string;
+    passkeyActionPublicKey: string;
+    phraseActionPublicKey: string;
+}
+export declare function isCustodyEnvelopeV3(value: SealedShare): value is CustodyEnvelopeV3;
 type EnvelopeKind = 'passkey' | 'phrase';
 /** The x-coordinate a share was cut at — its custodian-facing share number. */
 export declare function shareIndexOf(share: Uint8Array): number;
@@ -44,12 +107,15 @@ export declare function openShareWithPhrase(sealed: SealedShare, custodianKey: s
  * ever sent.
  */
 export interface WrappingKeys {
-    /** The verified, PRF-capable account credential selected by the browser. */
+    /** The verified, PRF-capable custody credential selected by the browser. */
     passkeyCredentialId: string;
+    passkeyPrfSalt: string;
     passkeyPublicKey: string;
     phrasePublicKey: string;
     phraseSalt: string;
     phraseVerifier: string;
+    passkeyActionPublicKey: string;
+    phraseActionPublicKey: string;
 }
 /** The private half for one factor. Never leaves the machine that made it. */
 export declare function passkeyWrappingKey(custodianKey: string, passkeyPrfOutput: Uint8Array): {
@@ -65,9 +131,25 @@ export declare function phraseWrappingKey(custodianKey: string, phraseWords: str
 export declare function wrappingKeysFor(args: {
     custodianKey: string;
     passkeyCredentialId: string;
+    passkeyPrfSalt: string;
     passkeyPrfOutput: Uint8Array;
     phraseWords: string[];
 }): WrappingKeys;
+export declare function custodyFactorActionPublicKey(factor: CustodyFactor, custodianKey: string, factorMaterial: Uint8Array): string;
+/** Stable browser/API digest used to bind a custody proof to one exact payload. */
+export declare function custodyActionPayloadDigest(value: unknown): string;
+export declare function createCustodyFactorProof(args: {
+    binding: CustodyFactorBinding;
+    factorMaterial: Uint8Array;
+    credentialId?: string;
+}): CustodyFactorProof;
+export declare function createCustodyPasskeyProof(binding: CustodyFactorBinding, passkeyPrfOutput: Uint8Array, credentialId: string): CustodyPasskeyProofV1;
+export declare function createCustodyPhraseProof(binding: CustodyFactorBinding, phraseWords: string[], phraseSalt: string): CustodyPhraseProofV1;
+export declare function verifyCustodyFactorProof(args: {
+    binding: CustodyFactorBinding;
+    proof: CustodyFactorProof;
+    publicKey: string;
+}): boolean;
 /** Open something the server sealed to one of those public keys. */
 export declare function openSealedToFactor(args: {
     custodianKey: string;
@@ -76,9 +158,12 @@ export declare function openSealedToFactor(args: {
     passkeyPrfOutput?: Uint8Array;
     phraseWords?: string[];
     phraseSalt?: string;
+    aad?: string;
 }): Uint8Array;
 /** The aad the server must use when sealing to a custodian's factor key. */
 export declare const factorWrapAad: (custodianKey: string, factor: EnvelopeKind) => string;
+/** Canonical AAD for V3. Length-prefixing prevents ambiguous concatenation. */
+export declare function custodyEnvelopeV3Aad(envelope: Pick<CustodyEnvelopeV3, 'version' | 'suite' | 'realmId' | 'ceremonyKey' | 'custodianKey' | 'shareIndex' | 'passkeyCredentialId' | 'generation' | 'passkeyGeneration' | 'phraseGeneration'>, factor: EnvelopeKind): string;
 /**
  * A share plus a probe, sealed together.
  *

package/dist/custody-share.js

@@ -174,9 +174,18 @@ function phraseVerifier(words, salt) {
 }
 
 // src/custody-share.ts
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { hkdf as hkdf3 } from "@noble/hashes/hkdf.js";
+import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
+var CUSTODY_ENVELOPE_VERSION = 3;
+var CUSTODY_ENVELOPE_SUITE = "ml-kem-768+x25519+hkdf-sha256+aes-256-gcm+ml-dsa-65";
+var CUSTODY_FACTOR_PROOF_VERSION = 1;
 var KEY_BYTES3 = 32;
 var MIN_PRF_BYTES = 32;
 var PASSKEY_KEY_SALT = "forgezero:custodian:passkey:v1";
+function isCustodyEnvelopeV3(value) {
+  return value.version === CUSTODY_ENVELOPE_VERSION && value.suite === CUSTODY_ENVELOPE_SUITE;
+}
 var utf82 = (value) => new TextEncoder().encode(value);
 var toBase642 = (bytes) => {
   let binary = "";
@@ -283,31 +292,167 @@ function phraseWrappingKey(custodianKey, phraseWords, salt) {
 function wrappingKeysFor(args) {
   if (!args.passkeyCredentialId)
     throw new Error("custody-share: passkey credential id is required");
+  if (!/^[A-Za-z0-9_-]{43}$/.test(args.passkeyPrfSalt)) {
+    throw new Error("custody-share: ceremony passkey PRF salt is required");
+  }
   const salt = newSalt();
   const passkey = passkeyWrappingKey(args.custodianKey, args.passkeyPrfOutput);
   const phrase = phraseWrappingKey(args.custodianKey, args.phraseWords, salt);
+  const passkeyAction = custodyFactorActionKeyPair("ceremony_passkey", args.custodianKey, args.passkeyPrfOutput);
+  const phraseMaterial = phraseToKey(args.phraseWords, salt);
+  const phraseAction = custodyFactorActionKeyPair("recovery_phrase", args.custodianKey, phraseMaterial);
   try {
     return {
       passkeyCredentialId: args.passkeyCredentialId,
+      passkeyPrfSalt: args.passkeyPrfSalt,
       passkeyPublicKey: toBase642(passkey.publicKey),
       phrasePublicKey: toBase642(phrase.publicKey),
       phraseSalt: toBase642(salt),
-      phraseVerifier: phraseVerifier(args.phraseWords, salt)
+      phraseVerifier: phraseVerifier(args.phraseWords, salt),
+      passkeyActionPublicKey: toBase642(passkeyAction.publicKey),
+      phraseActionPublicKey: toBase642(phraseAction.publicKey)
     };
   } finally {
     passkey.secretKey.fill(0);
     phrase.secretKey.fill(0);
+    passkeyAction.secretKey.fill(0);
+    phraseAction.secretKey.fill(0);
+    phraseMaterial.fill(0);
+  }
+}
+var actionInfo = (factor, custodianKey) => `forgezero:custody:factor-action:ml-dsa-65:v1:${factor}:${custodianKey.length}:${custodianKey}`;
+function custodyFactorActionKeyPair(factor, custodianKey, factorMaterial) {
+  assertCustodianKey(custodianKey);
+  if (factorMaterial.length < 32)
+    throw new Error("custody-share: action factor must be at least 32 bytes");
+  const seed = hkdf3(sha2563, factorMaterial, utf82("forgezero:custody:factor-action:ml-dsa-65:v1"), utf82(actionInfo(factor, custodianKey)), 32);
+  try {
+    const pair = ml_dsa65.keygen(seed);
+    return { publicKey: Uint8Array.from(pair.publicKey), secretKey: Uint8Array.from(pair.secretKey) };
+  } finally {
+    seed.fill(0);
+  }
+}
+function custodyFactorActionPublicKey(factor, custodianKey, factorMaterial) {
+  const pair = custodyFactorActionKeyPair(factor, custodianKey, factorMaterial);
+  try {
+    return toBase642(pair.publicKey);
+  } finally {
+    pair.secretKey.fill(0);
+  }
+}
+var proofBytes = (binding) => {
+  const values = [
+    "forgezero-custody-factor-proof-v1",
+    String(binding.version),
+    binding.realmId,
+    binding.ceremonyKey,
+    binding.custodianKey,
+    binding.factor,
+    binding.requestKey,
+    binding.method,
+    binding.path,
+    binding.payloadDigest,
+    binding.challenge,
+    String(binding.expiresAtSec)
+  ];
+  return utf82(values.map((value) => `${utf82(value).length}:${value}`).join(`
+`));
+};
+function canonicalJson(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string")
+    return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error("custody-share: non-finite action payload number");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value))
+    return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value === "object") {
+    return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+  }
+  throw new Error("custody-share: unsupported action payload value");
+}
+function custodyActionPayloadDigest(value) {
+  return Array.from(sha2563(utf82(canonicalJson(value))), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createCustodyFactorProof(args) {
+  if (args.binding.version !== CUSTODY_FACTOR_PROOF_VERSION) {
+    throw new Error("custody-share: unsupported factor proof version");
+  }
+  const pair = custodyFactorActionKeyPair(args.binding.factor, args.binding.custodianKey, args.factorMaterial);
+  try {
+    const signature = toBase642(ml_dsa65.sign(proofBytes(args.binding), pair.secretKey));
+    return args.binding.factor === "ceremony_passkey" ? {
+      version: CUSTODY_FACTOR_PROOF_VERSION,
+      factor: "ceremony_passkey",
+      credentialId: args.credentialId ?? "",
+      signature
+    } : { version: CUSTODY_FACTOR_PROOF_VERSION, factor: "recovery_phrase", signature };
+  } finally {
+    pair.secretKey.fill(0);
+  }
+}
+function createCustodyPasskeyProof(binding, passkeyPrfOutput, credentialId) {
+  if (binding.factor !== "ceremony_passkey") {
+    throw new Error("custody-share: passkey proof requires ceremony_passkey binding");
+  }
+  return createCustodyFactorProof({
+    binding,
+    factorMaterial: passkeyPrfOutput,
+    credentialId
+  });
+}
+function createCustodyPhraseProof(binding, phraseWords, phraseSalt) {
+  if (binding.factor !== "recovery_phrase") {
+    throw new Error("custody-share: phrase proof requires recovery_phrase binding");
+  }
+  if (!validatePhrase(phraseWords))
+    throw new Error("INVALID_PHRASE");
+  const material = phraseToKey(phraseWords, fromBase642(phraseSalt));
+  try {
+    return createCustodyFactorProof({ binding, factorMaterial: material });
+  } finally {
+    material.fill(0);
+  }
+}
+function verifyCustodyFactorProof(args) {
+  try {
+    if (args.proof.version !== CUSTODY_FACTOR_PROOF_VERSION || args.proof.factor !== args.binding.factor)
+      return false;
+    const publicKey = fromBase642(args.publicKey);
+    const signature = fromBase642(args.proof.signature);
+    return publicKey.length === ml_dsa65.lengths.publicKey && signature.length === ml_dsa65.lengths.signature && ml_dsa65.verify(signature, proofBytes(args.binding), publicKey);
+  } catch {
+    return false;
   }
 }
 function openSealedToFactor(args) {
   const pair = args.factor === "passkey" ? passkeyWrappingKey(args.custodianKey, args.passkeyPrfOutput) : phraseWrappingKey(args.custodianKey, args.phraseWords, fromBase642(args.phraseSalt));
   try {
-    return openFromKey(pair.secretKey, args.box, wrapInfo(args.custodianKey, args.factor));
+    return openFromKey(pair.secretKey, args.box, args.aad ?? wrapInfo(args.custodianKey, args.factor));
   } finally {
     pair.secretKey.fill(0);
   }
 }
 var factorWrapAad = (custodianKey, factor) => wrapInfo(custodianKey, factor);
+function custodyEnvelopeV3Aad(envelope, factor) {
+  const values = [
+    "forgezero-custody-envelope-aad",
+    String(envelope.version),
+    envelope.suite,
+    envelope.realmId,
+    envelope.ceremonyKey,
+    envelope.custodianKey,
+    String(envelope.shareIndex),
+    factor,
+    factor === "passkey" ? envelope.passkeyCredentialId : "recovery_phrase",
+    String(factor === "passkey" ? envelope.passkeyGeneration ?? envelope.generation : envelope.phraseGeneration ?? envelope.generation)
+  ];
+  return values.map((value) => `${utf82(value).length}:${value}`).join(`
+`);
+}
 var PROBE_BYTES = 32;
 function joinProbeAndShare(probe, share) {
   if (probe.length !== PROBE_BYTES)
@@ -324,17 +469,20 @@ function splitProbeAndShare(opened) {
 }
 function openFactorEnvelope(args) {
   const box = args.factor === "passkey" ? args.sealed.passkeyEnvelope : args.sealed.phraseEnvelope;
+  const aad = isCustodyEnvelopeV3(args.sealed) ? custodyEnvelopeV3Aad(args.sealed, args.factor) : undefined;
   return splitProbeAndShare(openSealedToFactor({
     custodianKey: args.custodianKey,
     factor: args.factor,
     box,
     passkeyPrfOutput: args.passkeyPrfOutput,
     phraseWords: args.phraseWords,
-    phraseSalt: args.sealed.phraseSalt
+    phraseSalt: args.sealed.phraseSalt,
+    aad
   }));
 }
 export {
   wrappingKeysFor,
+  verifyCustodyFactorProof,
   splitProbeAndShare,
   shareIndexOf,
   sealShare,
@@ -345,6 +493,16 @@ export {
   openSealedToFactor,
   openFactorEnvelope,
   joinProbeAndShare,
+  isCustodyEnvelopeV3,
   factorWrapAad,
-  PROBE_BYTES
+  custodyFactorActionPublicKey,
+  custodyEnvelopeV3Aad,
+  custodyActionPayloadDigest,
+  createCustodyPhraseProof,
+  createCustodyPasskeyProof,
+  createCustodyFactorProof,
+  PROBE_BYTES,
+  CUSTODY_FACTOR_PROOF_VERSION,
+  CUSTODY_ENVELOPE_VERSION,
+  CUSTODY_ENVELOPE_SUITE
 };

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.24",
+  "version": "0.1.26",
   "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"