@voltro/protocol 0.79.1 → 0.81.0

package/dist/index.d.ts

@@ -37,6 +37,9 @@ export declare interface ActionProcedureDescriptor<Name extends string, Input ex
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this action into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this action into the auto-synthesized agent toolset (innovation/07). */
@@ -89,9 +92,9 @@ export declare interface AnyApprovalPolicy {
     readonly reason?: string;
 }
 
-/** A guard entry is a scope check, a relationship check, an identity check, or
- *  a declared no-check-needed decision. */
-export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec | AuthenticatedCheckSpec | OpenAccessSpec;
+/** A guard entry is a scope check, a relationship check, an identity check, a
+ *  declared no-check-needed decision, or a service-only decision. */
+export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec | AuthenticatedCheckSpec | OpenAccessSpec | ServiceAccessSpec;
 
 /** Any declared event, with the generics erased — for registries and audits. */
 export declare type AnyEventDescriptor = EventDescriptor<string, Schema.Schema.Any, Schema.Schema.Any>;
@@ -130,6 +133,21 @@ export declare const APIKEY_ISSUE_OTHER_SCOPE = "apikeys:issue:other";
  */
 export declare const APIKEY_ISSUE_SELF_SCOPE = "apikeys:issue:self";
 
+export declare class ApiUnavailable extends ApiUnavailable_base {
+}
+
+declare const ApiUnavailable_base: Schema.TaggedErrorClass<ApiUnavailable, "ApiUnavailable", {
+    readonly _tag: Schema.tag<"ApiUnavailable">;
+} & {
+    /** The binding name on the caller (`apis.<name>`). */
+    api: typeof Schema.String;
+    /** The rpc tag that was called. */
+    tag: typeof Schema.String;
+    /** Why no answer arrived. */
+    reason: Schema.Literal<["timeout", "transport", "closed"]>;
+    message: typeof Schema.String;
+}>;
+
 /** The subject a decision produces, plus what the decision took away. `removed`
  *  is never non-empty for a `grant`. */
 export declare interface AppliedScopes {
@@ -677,7 +695,7 @@ export declare type AuthSubjectGuardVerdict = {
  * `fresh` the caller runs the handler then calls `finish`/`fail`; on
  * `replay`/`conflict` it returns immediately without touching the handler.
  */
-export declare const beginIdempotent: (store: IdempotencyStore, scope: string, key: string, ttlMs: number, now: number) => Promise<IdempotencyOutcome>;
+export declare const beginIdempotent: (store: IdempotencyStore, scope: string, key: string, ttlMs: number, now: number, inFlightLeaseMs?: number) => Promise<IdempotencyOutcome>;
 
 /**
  * A cross-table business rule was violated inside a mutation's transaction; the
@@ -1379,11 +1397,25 @@ export declare interface CoordinatedTickOutcome {
  * because that is where the normalised decision lands, and because every
  * enforcement path reads the descriptor's array and nothing else.
  */
-export declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec>;
+export declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec | ServiceAccessSpec>;
 
 /** Every channel declared in this process, by routing key. */
 export declare const declaredReactivityChannelKeys: () => ReadonlySet<string>;
 
+/**
+ * How long a RUNNING claim holds without renewal.
+ *
+ * A claim used to go stale only after the replay window — 24 hours by default —
+ * so a process that died inside a handler left its key `in_flight` for a day:
+ * every retry was refused as "still in flight", including the retry of a
+ * workflow step whose callee had simply restarted. A live handler renews its
+ * claim every third of this (`holdIdempotentClaim`); a dead one stops, and the
+ * next retry takes over after at most this long. A handler that blocks its event
+ * loop longer than this can be taken over while still running — the same bound
+ * every lease has.
+ */
+export declare const DEFAULT_IN_FLIGHT_LEASE_MS = 30000;
+
 /** Default cap on cached subjects before the cache sweeps + trims. */
 export declare const DEFAULT_SCOPE_CACHE_MAX_ENTRIES = 10000;
 
@@ -1418,6 +1450,26 @@ export declare const defineAction: <const Name extends string, Input extends Sch
      *     openAccess: 'public pricing page — reads no caller data'
      */
     readonly openAccess?: string;
+    /**
+     * Make this a SERVICE procedure: callable only by the listed apps of this
+     * project, and by nobody else — no browser session, no API key, no admin.
+     *
+     *     service: { callers: ['worker'] }
+     *
+     * The caller is another app that binds this one under `apis:` and calls it as
+     * `ctx.apis.<name>.<tag>(input)`; it authenticates with the service credential
+     * this app accepts under `serviceCallers`. It is its own access decision, so it
+     * satisfies `security.defaultDeny` and cannot sit beside `guards:` or
+     * `openAccess:`.
+     *
+     * The handler runs as the calling SERVICE: it reads across tenants and must
+     * name a tenant to write into one — `ctx.storeForTenant(input.tenantId)` is the
+     * shape for per-tenant work.
+     *
+     * Codegen emits it into `serviceGroup.generated.ts`, never into the browser's
+     * `rpcGroup.generated.ts`.
+     */
+    readonly service?: ServiceSpec;
     /** Table(s) this action READS. Declaring it is what lets `voltro check` know
      *  the table is alive — without it, a table only an action touches reads as
      *  an orphan. See `ActionProcedureDescriptor.source`. */
@@ -1631,6 +1683,26 @@ export declare const defineMutation: <const Name extends string, Input extends S
      *     openAccess: 'public pricing page — reads no caller data'
      */
     readonly openAccess?: string;
+    /**
+     * Make this a SERVICE procedure: callable only by the listed apps of this
+     * project, and by nobody else — no browser session, no API key, no admin.
+     *
+     *     service: { callers: ['worker'] }
+     *
+     * The caller is another app that binds this one under `apis:` and calls it as
+     * `ctx.apis.<name>.<tag>(input)`; it authenticates with the service credential
+     * this app accepts under `serviceCallers`. It is its own access decision, so it
+     * satisfies `security.defaultDeny` and cannot sit beside `guards:` or
+     * `openAccess:`.
+     *
+     * The handler runs as the calling SERVICE: it reads across tenants and must
+     * name a tenant to write into one — `ctx.storeForTenant(input.tenantId)` is the
+     * shape for per-tenant work.
+     *
+     * Codegen emits it into `serviceGroup.generated.ts`, never into the browser's
+     * `rpcGroup.generated.ts`.
+     */
+    readonly service?: ServiceSpec;
     /** Project this mutation as a public REST endpoint (innovation/11). */
     readonly publicApi?: PublicApiSpec;
     /** Expose this mutation as an agent tool (innovation/07). */
@@ -1764,6 +1836,26 @@ export declare const defineQuery: <const Name extends string, Input extends Sche
      *     openAccess: 'public pricing page — reads no caller data'
      */
     readonly openAccess?: string;
+    /**
+     * Make this a SERVICE procedure: callable only by the listed apps of this
+     * project, and by nobody else — no browser session, no API key, no admin.
+     *
+     *     service: { callers: ['worker'] }
+     *
+     * The caller is another app that binds this one under `apis:` and calls it as
+     * `ctx.apis.<name>.<tag>(input)`; it authenticates with the service credential
+     * this app accepts under `serviceCallers`. It is its own access decision, so it
+     * satisfies `security.defaultDeny` and cannot sit beside `guards:` or
+     * `openAccess:`.
+     *
+     * The handler runs as the calling SERVICE: it reads across tenants and must
+     * name a tenant to write into one — `ctx.storeForTenant(input.tenantId)` is the
+     * shape for per-tenant work.
+     *
+     * Codegen emits it into `serviceGroup.generated.ts`, never into the browser's
+     * `rpcGroup.generated.ts`.
+     */
+    readonly service?: ServiceSpec;
     /** Project this query as a public REST endpoint (innovation/11). */
     readonly publicApi?: PublicApiSpec;
     /** Expose this query as an agent tool (innovation/07). */
@@ -2302,9 +2394,34 @@ export declare const findAdvisoryResourceGuards: (procedures: ReadonlyArray<{
 /** Record a completed response for replay. */
 export declare const finishIdempotent: (store: IdempotencyStore, scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
 
+/**
+ * The value a ONE-SHOT read of an rpc resolves to, given the first value it
+ * delivered.
+ *
+ * A query's success type is the three-member union above, and a one-shot read
+ * takes only its first event: a `snapshot` resolves to its `data`; an `error`
+ * REJECTS — with the typed error on `cause` and `voltroError`, so a caller can
+ * still branch on its `_tag` — exactly as a failed exit would; a `delta` cannot
+ * be first and says so. Anything else is a mutation or action's own result and
+ * passes through, which may legitimately be a tagged object of the app's.
+ *
+ * Shared because there are two such reads — the server loader's `ctx.query`
+ * over `POST /rpc` and the browser loader's over the page's socket — and an
+ * unwrap written twice is how an authorization answer once reached a loader as
+ * its return value on one transport and as a rejection on the other.
+ *
+ * `label` prefixes every message (`[loader.query]`), naming the surface that
+ * made the read.
+ */
+export declare const firstEventValue: (tag: string, value: unknown, label: string) => unknown;
+
 /** A route rendered for humans — logs, the inspect surface, the dashboard. */
 export declare const formatEventRoute: (route: string) => string;
 
+/** How long a record of this status stays fresh — the replay window for a
+ *  completed response, the lease for a running one (never longer than the window). */
+export declare const freshFor: (status: IdempotencyRecord["status"], ttlMs: number, inFlightLeaseMs: number) => number;
+
 /** Close code a gateway connection receives when its credential expires —
  *  the same session-expiry contract the rpc socket has (SEC-16), spelled as
  *  an application close code so foreign clients can reauth + reconnect. */
@@ -2427,6 +2544,9 @@ export declare const hasEnforcedGuard: (guards: DeclaredAccess | undefined) => b
  *  the RAW subject scopes — use `hasEffectiveScope` to include rbac roles. */
 export declare const hasScope: (subject: Subject, scope: string) => boolean;
 
+/** Renew a fresh claim's lease while its handler runs; returns the stop. */
+export declare const holdIdempotentClaim: (store: IdempotencyStore, scope: string, key: string, inFlightLeaseMs?: number, now?: () => number) => (() => void);
+
 /**
  * Short-circuit response shape. Returning a `HttpInterceptResponse`
  * from the interceptor halts the pipeline — the framework sends the
@@ -2526,14 +2646,24 @@ export declare interface IdempotencyStore {
     /** Current record for (scope, key), or null. Read-side (inspect/dashboard). */
     readonly get: (scope: string, key: string) => Promise<IdempotencyRecord | null>;
     /**
-     * Atomically claim (scope, key) IF absent OR stale (older than `ttlMs`):
+     * Atomically claim (scope, key) IF absent OR stale — a COMPLETED record older
+     * than `ttlMs` (the replay window), or an IN-FLIGHT one whose lease
+     * (`inFlightLeaseMs`, renewed by the live handler) lapsed:
      * write a fresh `in_flight` row and return `'claimed'`. Otherwise return the
      * EXISTING (still-fresh) record. The atomicity here is the whole game — two
      * concurrent same-key requests both hit this, exactly one gets `'claimed'`,
      * the loser reads the winner's record. In SQL this is one
      * `INSERT … ON CONFLICT DO UPDATE … WHERE existing.createdAt < now - ttl`.
      */
-    readonly claim: (scope: string, key: string, now: number, ttlMs: number) => Promise<'claimed' | IdempotencyRecord>;
+    readonly claim: (scope: string, key: string, now: number, ttlMs: number, inFlightLeaseMs: number) => Promise<'claimed' | IdempotencyRecord>;
+    /**
+     * Extend a RUNNING claim's lease: bump its timestamp while it is still
+     * `in_flight` (a completed or released claim is left alone). The server calls
+     * it while the handler runs; a process that dies stops calling it, and its
+     * claim goes stale after `inFlightLeaseMs` instead of after the whole replay
+     * window.
+     */
+    readonly renew: (scope: string, key: string, now: number) => Promise<void>;
     /** Flip the claim to `completed` and store the response. */
     readonly complete: (scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
     /** Drop the claim (handler errored → a retry may re-process). */
@@ -2616,12 +2746,21 @@ export declare interface InsertTarget<Input = unknown, Row = unknown, Item = Rec
     readonly shapeItem?: ((input: Input, optimisticId: string) => Item) | undefined;
 }
 
+/** Is this failure a missing answer (retry it) rather than an answer (do not)? */
+export declare const isApiUnavailable: (error: unknown) => error is ApiUnavailable;
+
 /** Runtime narrowing for the identity variant. */
 export declare const isAuthenticatedCheck: (g: AnyCheckSpec) => g is AuthenticatedCheckSpec;
 
 /** Narrow a guard entry to the identity variant. */
 export declare const isAuthenticatedGuard: <I>(g: AnyGuardSpec<I>) => g is AuthenticatedGuardSpec;
 
+/** Belongs in the app's own client group (`rpcGroup.generated.ts`). */
+export declare const isClientReachable: (descriptor: {
+    readonly internal?: boolean | undefined;
+    readonly service?: ServiceSpec | undefined;
+}) => boolean;
+
 export declare const isEventDescriptor: (value: unknown) => value is AnyEventDescriptor;
 
 /** True when every row in the set carries an `id`. The dispatcher uses
@@ -2630,6 +2769,17 @@ export declare const isEventDescriptor: (value: unknown) => value is AnyEventDes
  *  diffed by id and falls back to shipping the full data. */
 export declare const isIdKeyed: (rows: ReadonlyArray<Readonly<Record<string, unknown>>>) => rows is ReadonlyArray<PatchRow>;
 
+/**
+ * A machine actor that works ACROSS tenants: the framework acting as itself
+ * (`system`) or another app of the project calling in (`service`).
+ *
+ * This is a statement about DATA placement only — no row filter, no implicit
+ * tenant, an explicit tenant for writes. It says nothing about authority: a
+ * service holds no scopes, and every place that lets `system` bypass a check
+ * keeps asking `isSystemSubject`.
+ */
+export declare const isMachineSubject: (subject: Subject) => boolean;
+
 /** Runtime narrowing for the declared-open variant. */
 export declare const isOpenAccess: (g: AnyCheckSpec) => g is OpenAccessSpec;
 
@@ -2655,6 +2805,20 @@ export declare const isReactivityChannel: (value: unknown) => value is Reactivit
  */
 export declare const isReactivityChannelKey: (key: string) => boolean;
 
+/** Runtime narrowing for the service-only variant. */
+export declare const isServiceAccess: (g: AnyCheckSpec) => g is ServiceAccessSpec;
+
+/** Belongs in the group other apps call (`serviceGroup.generated.ts`). */
+export declare const isServiceReachable: (descriptor: {
+    readonly internal?: boolean | undefined;
+    readonly service?: ServiceSpec | undefined;
+}) => boolean;
+
+/** Is this caller another app of the project, and which one? */
+export declare const isServiceSubject: (subject: Subject) => subject is Extract<Subject, {
+    readonly type: "service";
+}>;
+
 export declare const isSystemSubject: (subject: Subject) => boolean;
 
 export declare const isTenantSelectable: (subject: Subject) => subject is TenantSelectableSubject;
@@ -2786,6 +2950,9 @@ export declare interface MutationProcedureDescriptor<Name extends string, Input
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this mutation into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this mutation into the auto-synthesized agent toolset (innovation/07). */
@@ -3431,11 +3598,17 @@ export declare interface PluginErrorSchema {
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 export declare interface PluginHttpRoute {
-    /** HTTP method, or `'*'` for any (the handler decides). PATCH/HEAD/OPTIONS
-     *  are first-class — the REST desugar used to mount `'*'` partly BECAUSE
-     *  this union lacked PATCH; that reason is gone (the `'*'` mount remains
-     *  for its other job: one dispatcher per shared path + a precise 405). */
+    /** HTTP method, or `'*'` for any (the handler decides). The server mounts the
+     *  path for exactly the methods its routes declare; `'*'` mounts it for every
+     *  method the router knows (34), so keep that for a route that really serves
+     *  them — see `answersOtherMethods` for one that only wants to refuse them. */
     readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    /** `true`: the handler gates its own method, so a request with a method the
+     *  path does not declare is still handed to it — to answer with a precise
+     *  `405` and `Allow` instead of the router's `404`. The path is still mounted
+     *  only for `method`. A REST route sets it. Without it, a route that declares
+     *  one method never sees another. */
+    readonly answersOtherMethods?: boolean | undefined;
     /** Absolute path, e.g. `/_voltro/storage`. Matched byte for byte: the
      *  router folds case and a trailing slash to FIND the route, the dispatcher
      *  then asks whether the request's path is one the route declared — so
@@ -4491,6 +4664,9 @@ export declare interface QueryProcedureDescriptor<Name extends string, Input ext
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this query into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this query into the auto-synthesized agent toolset (innovation/07). */
@@ -4847,6 +5023,9 @@ declare interface RestRouteContext {
      *  REST handlers on the same capability surface as query/mutation/action
      *  handlers without creating a protocol-to-runtime package dependency. */
     readonly app?: unknown;
+    /** The caller's address, resolved through `security.trustedProxies` — the
+     *  value the listener's per-IP shield counts. Absent when unknown. */
+    readonly remoteAddr?: string;
 }
 
 declare interface RestRouteDescriptor<I, O> {
@@ -5149,6 +5328,16 @@ export declare interface RpcInterceptorContext {
     readonly surface?: 'rest';
     /** The descriptor's `publicApi` spec, on a projected call. */
     readonly publicApi?: PublicApiSpec;
+    /**
+     * The caller's address — the same value the pre-auth IP shield counts, resolved
+     * by the listener through `security.trustedProxies` (and
+     * `security.clientAddressHeader`). A client cannot set it: the listener
+     * writes it, and any copy the client sends is discarded.
+     *
+     * Absent when the call did not arrive over the network (a workflow step, a
+     * schedule, an in-process invocation) or the socket address is unknown.
+     */
+    readonly remoteAddr?: string;
 }
 
 /**
@@ -5371,6 +5560,118 @@ declare const ServerOnlyColumnWrite_base: Schema.TaggedErrorClass<ServerOnlyColu
     columns: Schema.Array$<typeof Schema.String>;
 }>;
 
+/** A service (app) name: what `serviceCallers`, `service.callers` and a service
+ *  credential all spell the same way. At most 56 characters: the caller writes
+ *  as `service:<name>`, which is an `actors.id` — an `id()` column, VARCHAR(64)
+ *  on three dialects — so a longer name would fail its first audited write. */
+export declare const SERVICE_NAME_PATTERN: RegExp;
+
+/**
+ * The runtime-erased form of a procedure's `service: { callers }` — "only these
+ * apps of the project may call this, and nobody else".
+ *
+ * A guard entry for the reason `OpenAccessSpec` is one: every enforcement path
+ * is handed the `guards` array and nothing else, so a decision that lived on a
+ * separate descriptor field would be enforced by the paths somebody remembered
+ * and skipped by the rest.
+ *
+ * It admits exactly a `service` subject whose name is listed. `admin:full` does
+ * NOT bypass it: a service procedure is a machine contract between two apps,
+ * and a browser session holding the admin scope is not one of the parties.
+ */
+export declare interface ServiceAccessSpec {
+    /** The calling apps' names, as the callee declares them in `serviceCallers`.
+     *  Non-empty by construction — the definers refuse an empty list. */
+    readonly service: ReadonlyArray<string>;
+}
+
+/** Build the erased `service:` entry. The definers call this. */
+export declare const serviceAccessSpec: (callers: ReadonlyArray<string>) => ServiceAccessSpec;
+
+/**
+ * A procedure map (`ServiceProcedures`) turned into the nested object a caller
+ * writes: `'deployments.activate'` becomes `.deployments.activate(...)`. A tag
+ * that is both a procedure and a namespace prefix is both.
+ */
+export declare type ServiceApi<P> = 0 extends (1 & P) ? any : ServiceApiOf<P>;
+
+declare type ServiceApiOf<P> = {
+    readonly [H in ServiceTagHead<keyof P & string>]: (H extends keyof P ? ServiceCall<P[H]> : unknown) & ServiceApiOf<{
+        [K in keyof P & string as K extends `${H}.${infer R}` ? R : never]: P[K];
+    }>;
+};
+
+/** One procedure as the caller sees it — callable, `.effect`, and `.subscribe` for a query. */
+export declare type ServiceCall<D> = D extends ServiceDescriptorShape ? ((input: ServiceDecoded<D['input']>, options?: ServiceCallOptions) => Promise<ServiceDecoded<D['output']>>) & {
+    /** The same call as an Effect. Inside a workflow step its write key is
+     *  derived from the step, so a re-sent step replays instead of writing twice. */
+    readonly effect: (input: ServiceDecoded<D['input']>, options?: ServiceCallOptions) => Effect.Effect<ServiceDecoded<D['output']>, unknown>;
+} & (D extends {
+    readonly kind: 'query';
+} ? {
+    /** Hold the live query open; `onValue` gets each materialized value. */
+    readonly subscribe: (input: ServiceDecoded<D['input']>, handlers: ServiceSubscribeHandlers<ServiceDecoded<D['output']>>) => ServiceSubscription;
+} : unknown) : never;
+
+/** The apps a guard array admits as service callers, or `undefined` when the
+ *  procedure is not a service procedure. */
+export declare const serviceCallersOf: (guards: ReadonlyArray<AnyCheckSpec> | undefined) => ReadonlyArray<string> | undefined;
+
+export declare interface ServiceCallOptions {
+    /** Deadline for this call. Default 10 seconds. */
+    readonly timeoutMs?: number;
+    /** Explicit idempotency key for a write. Overrides the ambient and the fresh one. */
+    readonly idempotencyKey?: string;
+    /** Interrupts the call when aborted. */
+    readonly signal?: AbortSignal;
+}
+
+/** The decoded (application-side) type of a schema slot. */
+export declare type ServiceDecoded<S> = S extends {
+    readonly Type: infer T;
+} ? T : never;
+
+/** What a service procedure's descriptor type carries that the facade reads. */
+export declare interface ServiceDescriptorShape {
+    readonly kind: string;
+    readonly input: unknown;
+    readonly output: unknown;
+}
+
+/**
+ * A service procedure's declaration: which apps of the project may call it.
+ *
+ *     service: { callers: ['worker'] }
+ *
+ * The names are the CALLING apps' names as this app lists them in
+ * `serviceCallers` — the same name the caller's credential resolves to.
+ */
+export declare interface ServiceSpec {
+    readonly callers: ReadonlyArray<string>;
+}
+
+/**
+ * The subject a verified service credential resolves to. Built by the service
+ * strategy only — an app never constructs one, and nothing grants it scopes.
+ */
+export declare const serviceSubject: (service: string) => Extract<Subject, {
+    readonly type: "service";
+}>;
+
+export declare interface ServiceSubscribeHandlers<T> {
+    /** Every materialized value of the live query, starting with the first snapshot. */
+    readonly onValue: (value: T) => void;
+    /** The subscription's own in-band error (e.g. an access refusal). */
+    readonly onError?: (error: unknown) => void;
+}
+
+export declare interface ServiceSubscription {
+    readonly unsubscribe: () => void;
+}
+
+/** The first segment of a dotted rpc tag. */
+export declare type ServiceTagHead<K extends string> = K extends `${infer H}.${string}` ? H : K;
+
 /**
  * Publish the caller's fully-resolved scope set for this request (raw subject
  * scopes ∪ role-derived scopes ∪ any extra grants). Called by the rbac
@@ -5583,6 +5884,14 @@ export declare const Subject: Schema.Union<[Schema.Struct<{
     tenantId: typeof Schema.Null;
     scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["service"]>;
+    id: typeof Schema.String;
+    /** The calling app's name, as the callee lists it in `serviceCallers`. */
+    service: typeof Schema.String;
+    tenantId: typeof Schema.Null;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>]>;
 
 export declare type Subject = typeof Subject.Type;
@@ -5636,6 +5945,12 @@ export declare const SubjectIdentity: Schema.Union<[Schema.Struct<{
     id: typeof Schema.String;
     tenantId: typeof Schema.Null;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["service"]>;
+    id: typeof Schema.String;
+    tenantId: typeof Schema.Null;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    service: typeof Schema.String;
 }>]>;
 
 export declare type SubjectIdentity = typeof SubjectIdentity.Type;
@@ -5708,6 +6023,15 @@ declare const SubjectService_base: Context.TagClass<SubjectService, "@voltro/Sub
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
+} | {
+    readonly type: "service";
+    readonly id: string;
+    readonly tenantId: null;
+    readonly scopes?: readonly string[] | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+    readonly service: string;
 }>;
 
 /** Subscribe to server-primitive errors. Returns an unsubscribe fn. */
@@ -6632,6 +6956,29 @@ export declare interface VoltroPlugin {
      * specific permission name in the error.
      */
     readonly extendSchema?: PluginSchemaContribution;
+    /**
+     * A directory of APP-SHAPED primitives this plugin brings with it — the same
+     * file conventions an app uses (`*.query.ts` + `.server.ts`, `*.mutation.ts`,
+     * `*.workflow.tsx`, `*.cron.tsx`, `*.subscribe.ts`, `*.reaction.ts`,
+     * `schema.ts` / `*.entity.ts`, …).
+     *
+     *     sources: fileURLToPath(new URL('./app', import.meta.url))
+     *
+     * Every app that installs the plugin discovers those files exactly as it
+     * discovers its own: the same codegen, browser-safety guard, access gate,
+     * migrations and boot paths. That is what makes a reusable BUILDING BLOCK — a
+     * ledger, an approval flow, an audit trail — shareable between apps of a
+     * project without copying it.
+     *
+     * It shares CODE, never data: each installing app gets its own copy of the
+     * block's tables, in its own database. Two apps that need each other's data
+     * call each other (`apis:` + `service:` procedures).
+     *
+     * The block's procedures keep the names their descriptors declare; a name
+     * that collides with the app's own is refused at codegen, as any collision is.
+     * An absolute path to a directory; a missing one refuses the boot.
+     */
+    readonly sources?: string;
     /**
      * Cross-cutting error schemas merged into every procedure's wire error
      * union. Lets a plugin interceptor fail with a typed error (e.g.
@@ -6800,6 +7147,24 @@ export declare interface WebSocketGatewayRoute {
     readonly onConnection: (connection: WebSocketGatewayConnection) => void | (() => void) | Promise<void | (() => void)>;
 }
 
+/**
+ * Who may call a procedure over the wire: the app's own clients, or only other
+ * apps of the project.
+ *
+ * A `service:` procedure IS on the wire — the server routes it on the same
+ * socket — but it belongs to a different client group. Codegen emits it into
+ * `serviceGroup.generated.ts` (imported by server processes of other apps) and
+ * never into `rpcGroup.generated.ts` (imported by browsers), so no browser
+ * bundle names a machine contract. The server refuses every non-service caller
+ * regardless; keeping it out of the browser group is what keeps it out of the
+ * code people ship.
+ */
+export declare type WireAudience = 'client' | 'service';
+
+export declare const wireAudienceOf: (descriptor: {
+    readonly service?: ServiceSpec | undefined;
+}) => WireAudience;
+
 /**
  * The error union a procedure ACTUALLY puts on the wire — `descriptor.error`
  * plus everything the framework can produce for it before or around the
@@ -7506,7 +7871,12 @@ export declare const WorkflowRunHandleSchema: Schema.Struct<{
     status: Schema.Literal<["running", "succeeded", "queued", "dropped", "skipped", "replayed"]>;
     deferral: Schema.optional<Schema.Struct<{
         /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
-         *  `rateLimit` | `singleton`. */
+         *  `rateLimit` | `singleton` | `delayed` | `transaction` | `unacknowledged`.
+         *
+         *  `unacknowledged` — the start was dispatched and no acknowledgement came
+         *  back. The engine may have it; recovery retries the dispatch and binds the
+         *  receipt (`id`) to whatever run results. It is not a failure: do not
+         *  report one to a user, follow the receipt. */
         mode: typeof Schema.String;
         /** Epoch ms this may first be admitted. Null for a drop or a skip. */
         dueAt: Schema.NullOr<typeof Schema.Number>;
@@ -7694,7 +8064,12 @@ export declare type WorkflowStartDeferral = Schema.Schema.Type<typeof WorkflowSt
  */
 export declare const WorkflowStartDeferralSchema: Schema.Struct<{
     /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
-     *  `rateLimit` | `singleton`. */
+     *  `rateLimit` | `singleton` | `delayed` | `transaction` | `unacknowledged`.
+     *
+     *  `unacknowledged` — the start was dispatched and no acknowledgement came
+     *  back. The engine may have it; recovery retries the dispatch and binds the
+     *  receipt (`id`) to whatever run results. It is not a failure: do not
+     *  report one to a user, follow the receipt. */
     mode: typeof Schema.String;
     /** Epoch ms this may first be admitted. Null for a drop or a skip. */
     dueAt: Schema.NullOr<typeof Schema.Number>;
@@ -7812,7 +8187,12 @@ export declare const workflowToRpc: <const Name extends string, Payload extends
     status: Schema.Literal<["running", "succeeded", "queued", "dropped", "skipped", "replayed"]>;
     deferral: Schema.optional<Schema.Struct<{
         /** `debounce` | `batch` | `throttle` | `concurrency` | `paused` |
-         *  `rateLimit` | `singleton`. */
+         *  `rateLimit` | `singleton` | `delayed` | `transaction` | `unacknowledged`.
+         *
+         *  `unacknowledged` — the start was dispatched and no acknowledgement came
+         *  back. The engine may have it; recovery retries the dispatch and binds the
+         *  receipt (`id`) to whatever run results. It is not a failure: do not
+         *  report one to a user, follow the receipt. */
         mode: typeof Schema.String;
         /** Epoch ms this may first be admitted. Null for a drop or a skip. */
         dueAt: Schema.NullOr<typeof Schema.Number>;