@voltro/runtime 0.67.0 → 0.69.0

package/dist/index.d.ts

@@ -163,6 +163,11 @@ export declare interface ActivitySignals {
     readonly activeWorkflowExecutions: () => number;
 }
 
+/** The framework's universal audit-subject table (`@voltro/database`'s core
+ *  `actors`). An issued key gets a row here so `audit()`'s `createdBy` foreign
+ *  key resolves for a key-authenticated caller. */
+export declare const ACTORS_TABLE = "actors";
+
 /**
  * Adopt a detached subscription for a resuming client at `fromRevision`.
  * Undefined — identity unknown, entry dead (an error/revocation while
@@ -949,6 +954,28 @@ export declare interface ApiKeyStore {
     readonly findById: (id: string) => Promise<ApiKeyRow | null>;
     readonly listByTenant: (tenantId: string | null) => Promise<ReadonlyArray<ApiKeyRow>>;
     readonly patch: (id: string, fields: Partial<ApiKeyRow>) => Promise<void>;
+    /**
+     * Plant the key's row in `actors` — the audit subject every `createdBy` /
+     * `updatedBy` / `deletedBy` points at.
+     *
+     * REQUIRED, not optional, and that is the whole point. `actors.kind` is
+     * declared by the framework as `'user' | 'serviceAccount' | 'apiKey' |
+     * 'system'`, so an API key is explicitly an audit subject — and issuing wrote
+     * only `_voltro_api_keys`, so the row never existed. Measured in a consumer's
+     * database: `actors with kind='apiKey': 0`. The first audit-stamped insert by
+     * a key-authenticated caller then died on the foreign key, which means
+     * `apiKeys:` and `audit()` were not combinable and both are on by default.
+     *
+     * An optional hook would have been the same defect with a nicer name — the
+     * mistake was omission, and an optional field is omissible. Same reasoning as
+     * `startOutboxRunner`'s required `onShutdown`.
+     *
+     * Idempotent by contract: it is called on every issue, including a rotation.
+     */
+    readonly ensureActor: (actor: {
+        readonly id: string;
+        readonly displayName: string | null;
+    }) => Promise<void>;
 }
 
 export declare interface ApiKeyUsageBuffer {
@@ -4758,6 +4785,12 @@ export declare interface FleetMergeResult<T> {
      *
      * Empty when no membership is wired: with no roster there is no evidence of
      * departure, and assuming it would empty a single-process answer.
+     *
+     * A row is departed only when it is BOTH unrostered AND older than the
+     * freshness window. Roster-absence alone is not evidence — a membership view
+     * is per-process, so replicas sharing a database but no bus each hold a roster
+     * of one, and the earlier rule had two live replicas calling each other gone
+     * while reporting an age of under two seconds.
      */
     readonly departed: ReadonlyArray<{
         readonly replicaId: string;
@@ -6280,8 +6313,18 @@ export declare interface MemberSnapshot {
     readonly self: boolean;
 }
 
-/** In-memory store (tests + single-process dev). */
-export declare const memoryApiKeyStore: () => ApiKeyStore;
+/** The planted audit-subject row, as the memory store records it. */
+export declare interface MemoryActorRow {
+    readonly id: string;
+    readonly kind: 'apiKey';
+    readonly displayName: string | null;
+}
+
+/** In-memory store (tests + single-process dev). The `actors` map is EXPOSED so
+ *  a test can assert the row was planted — see `ApiKeyStore.ensureActor`. */
+export declare const memoryApiKeyStore: () => ApiKeyStore & {
+    readonly actors: ReadonlyMap<string, MemoryActorRow>;
+};
 
 /**
  * Adapter for in-memory testing. The "position" is a monotonically-
@@ -6814,6 +6857,43 @@ export declare interface OrchestratorTickDeps {
     readonly log?: WakeOrchestratorLogger;
 }
 
+/**
+ * Referrer policies that make a browser send `Origin: null` on a SAME-ORIGIN
+ * state-changing request — which `classifyRequestOrigin` refuses as opaque.
+ *
+ * This is not a lint about tidiness. `no-referrer` was the default here, and
+ * under it every no-JS `<form method="post">` in every Voltro app answered 403,
+ * on both boot paths, for every user. Two security defaults, each defensible
+ * alone, cancelling each other: we asked the browser to withhold provenance and
+ * then refused the request for lacking it.
+ *
+ * Measured in a real headless chromium against a bare `node:http` server —
+ * ONE header changed between the rows, nothing else:
+ *
+ *   Referrer-Policy: (none)                          → Origin: http://127.0.0.1:45412
+ *   Referrer-Policy: no-referrer                     → Origin: null        ← and no Referer
+ *   Referrer-Policy: strict-origin-when-cross-origin → Origin: http://127.0.0.1:45412
+ *   Referrer-Policy: same-origin                     → Origin: http://127.0.0.1:45412
+ *
+ * It is the Fetch spec's behaviour, not a chromium quirk: when appending the
+ * `Origin` header, a request whose referrer policy is `no-referrer` serialises
+ * its origin as `null`. `origin-when-cross-origin`'s sibling `unsafe-url` does
+ * not, so the set below is exactly the two that null it unconditionally.
+ *
+ * `same-origin` is NOT in the set — it preserves the Origin for same-origin
+ * requests — but it is also not the default, because it nulls the Origin for a
+ * legitimate CROSS-origin post to an allowlisted api, which is precisely the
+ * split-deployment `VOLTRO_ALLOWED_ORIGINS` exists to permit.
+ * `strict-origin-when-cross-origin` nulls it only on an https→http downgrade,
+ * which is the one case where withholding it is the point. It is also what every
+ * current browser does with no header at all, so it surprises nobody.
+ *
+ * The second casualty of `no-referrer` is in the same request: the Referer is
+ * gone too, and `/form/*` reads it to decide where the PRG redirect and the 422
+ * re-render go back to.
+ */
+export declare const ORIGIN_NULLING_REFERRER_POLICIES: ReadonlySet<string>;
+
 export declare type OriginDecision = {
     readonly allowed: true;
     readonly reason: 'guard-off' | 'same-origin' | 'loopback' | 'allowlisted' | 'no-browser-origin';
@@ -6945,7 +7025,7 @@ export declare interface OutboxFacade {
 export declare interface OutboxFacadeDeps {
     /** The REQUEST's store. Inside a mutation this is the transactional view —
      *  which is what makes the enqueue atomic with the domain write. */
-    readonly store: Pick<DataStore, 'insert' | 'query' | 'update'>;
+    readonly store: Pick<DataStore, 'insert' | 'query' | 'updateMany'>;
     readonly subject: Subject;
     readonly traceId: string | null;
     /** Nudge the drain worker once the transaction commits. Optional: without
@@ -7108,6 +7188,15 @@ export declare type PluginScheduleCoordinated = (name: string, intervalMs: numbe
 
 export declare const powerOfTwoSelector: (options?: P2COptions) => ReplicaSelector;
 
+/**
+ * Whether a `Referrer-Policy` value leaves the `Origin` header intact on a
+ * same-origin state-changing request.
+ *
+ * Reads the LAST supported token, which is what a browser honours: the header
+ * is a fallback list, and every token after a supported one still overrides it.
+ */
+export declare const preservesSameOriginHeader: (value: string | false) => boolean;
+
 export declare interface PreviewDiff {
     readonly rows: ReadonlyArray<RowDiff>;
     readonly summary: {
@@ -9042,6 +9131,20 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
      * runtime capability so clients replay only when the deployed server proves
      * the same key will be deduplicated. */
     readonly mutationReplay?: boolean;
+    /**
+     * Publish per-rpc-tag SCHEMA SHAPE digests alongside the capabilities, so a
+     * connecting client can tell whether the copy of the api client it loaded is
+     * the one this server binds.
+     *
+     * Dev only, and set by `voltro dev` alone. The staleness it detects is a
+     * pre-bundled browser chunk that Vite did not re-optimize; `voltro serve`
+     * ships a built bundle where that cannot arise, and there a rolling deploy
+     * would make a transient mismatch NORMAL — reporting it would be noise on
+     * exactly the path where noise is expensive. So this is a deliberate
+     * dev/serve asymmetry rather than an oversight, which is the distinction the
+     * boot-path parity rule asks for.
+     */
+    readonly publishSurfaceDigest?: boolean;
     /** Non-sensitive fleet identity written on the rpc WebSocket open/close
      *  records. Defaults to the process identity resolver (POD_NAME/HOSTNAME).
      *  Embedders may state it explicitly when they own process identity. */