@voltro/protocol 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -39,6 +39,98 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.38.0] — 2026-08-14
+
+### ⚠ BREAKING
+
+- **@voltro/plugin-audit, @voltro/protocol, @voltro/plugin-auth** — An audit row now says when an action was taken through an IMPERSONATED session, on the default settings, and no redactor can take that away.
+
+  `AuditEvent` gained `impersonation`, and the datastore sink a nullable json column of the same name. The mark is lifted out of `subject.metadata` BEFORE the redaction chain runs, so `redactSubject` — including a custom function that erases the subject wholesale — never gets a say.
+
+  **The defect it closes.** `@voltro/plugin-auth` mints the mark into `subject.metadata`, and `auditPlugin`'s default `redactSubject: 'metadata'` replaces that whole bag. That default is right: the bag is where a per-user provider credential lands, and an audit table is the last place a live PAT should be. The consequence was that on defaults an impersonated action was recorded indistinguishably from the user's own — the one distinction an audit trail exists to make. The documented mitigation (`redactSubject: impersonationAuditRedactor()`) worked and was opt-in, and an audit property that depends on somebody wiring it is not a property.
+
+  The alternative fix — a keep-these-keys option on `redactSubject` — was rejected for the same reason: it leaves the default wrong, and "who really did this" is not the app's metadata to configure away. It is a property of the event, so it is now a field of the event.
+
+  **BREAKING: `IMPERSONATION_METADATA_KEY` moved from `@voltro/plugin-auth` to `@voltro/protocol`.** It names the one reserved key in `Subject.metadata`, and `Subject` is protocol's type. Two packages need it — plugin-auth writes the mark, plugin-audit reads it — and a plugin must not depend on another plugin, so spelling the string in both would have made it a second definition no guard is watching. Everything else stays: plugin-auth still exports `impersonationOf`, `isImpersonated`, `ImpersonationMark` and `impersonationAuditRedactor`. The codemod repoints the import, preserving an alias and the type-only form.
+
+  The redactor keeps working and is no longer load-bearing. Set `redactSubject: 'none'` or a custom function for your own reasons; the impersonation mark is recorded either way.
+
+  No migration is needed for the new column — a `_voltro_*` change rides the declarative differ on `voltro db apply` and on a `voltro dev` boot, on every dialect.
+- **@voltro/cli** — A `*.startup.ts` that fails now refuses the boot. It used to warn and let the server come up.
+
+  Measured, on a real `voltro dev` against postgres, while building the row-filter integration test in this same release. A startup reached for `ctx.store.select(...)` — a builder that lives on the request-scoped `MutationStore`, not on the `DataStore` a startup receives — and threw on its first line. The boot printed:
+
+  ```
+  warn   startup: function rejected
+  info   startup: registered      <- next line, same file
+  ```
+
+  and then served every request with no row filter registered. Two lines contradicting each other, the second asserting exactly the thing that had just failed, and an app that looked healthy while its access control was absent.
+
+  **The rule this overturns was right when it was written.** The header of `startupRunner.ts` read "Errors are logged but never fatal — a failing startup MUST NOT block the rest of the app", and for the startups it was written for — an SSE bridge, a sync loop, a metric aggregator — that is the correct call. It stopped being right when a startup became the documented seam for REGISTRATION: `setRowFilter` is installed from one.
+
+  The runner cannot tell a registration from a background loop, and the two failures are not symmetric. "The app refuses to boot" is fixed in seconds and is visible to everyone; "the app serves without its access control" is visible to nobody. So the default is the recoverable one, and an app that genuinely wants best-effort writes the `try`/`catch` inside its own startup — one line, at the site where somebody decided the failure was acceptable, where a reviewer can see it. Deliberately not a flag: a flag moves that decision away from the startup it applies to and makes it one setting for all of them.
+
+  **Two sibling silences went with it**, because fixing only the rejection would have left two more ways to reach the identical state — the per-seam shape this repo keeps paying for. A startup file that cannot be imported, and one with no default-exported function, used to warn and skip. Both refuse now. The second matters more than it sounds: the convention is a DEFAULT-exported function, a named export is discovered and never runs, and that is indistinguishable from a startup that ran and did nothing.
+
+  **And the 2-second race is gone, which is the half that made the rest reliable.** The old code did not wait for a startup to settle — it raced it against 2000 ms and let the boot win. A startup slower than that was reported as fine, so a rejection arriving afterwards had nothing left to refuse. The runner now waits for the startup to SETTLE, so every failure is catchable however slow it is.
+
+  That race existed to protect one shape: a startup that never returns because it holds a fiber until shutdown. Counted before changing it, that shape appears in ZERO of the four startups this framework ships — `warm.startup.tsx` (twice), `searchBackfill.startup.tsx` and the memory fixture's all return. So the race protected the shape we discourage and penalised the shape we teach, and the penalised one includes `searchBackfill`, our own example, which awaits a full-table query plus an index backfill and is the likeliest thing in the box to exceed two seconds. Slow AND failing put a consumer back in exactly the silent state this release removes.
+
+  **So a startup that never returns now refuses the boot too**, after `VOLTRO_STARTUP_TIMEOUT_MS` (60s default), with a message naming the file and showing the `onShutdown` shape to use instead. That makes a previously-documented capability illegal — "a fiber that resolves only on shutdown" — and it is the deliberate half of this change rather than a side effect. A startup that is merely SLOW is unaffected: it is waited for and registers when it finishes.
+
+  `startup: registered` is written only when the function actually returned. The old code printed it for a failed startup and for one still running.
+
+  Verified against a real process in every direction, not only in units: the reintroduced defect exits 1 and never listens; a never-returning startup exits 1 and never listens; a slow-but-successful one still registers; and the healthy fixture boots and serves all eight row-filter assertions. `startupRunner.test.ts` is new — there were no tests on this runner at all, which is part of why the contradiction survived.
+
+  **`voltro update` carries you across this** — codemod `0.38.0/02_startup-failure-refuses-boot`.
+
+### Fixed
+
+- **@voltro/cli** — A table declared through `databaseHandle({ … })` but not exported as a top-level table is now DISCOVERED — so its mixins apply.
+
+  Discovery kept whatever `isTable()` accepted out of a schema module's `Object.values`, which only ever sees tables the file exports DIRECTLY. A schema that builds its tables programmatically exports the builder's result:
+
+  ```ts
+  export const blogEntities = contentTypeToEntities(blogPost)   // { draft, published }
+  export const database = databaseHandle({ …, blogPostDrafts: blogEntities.draft })
+  ```
+
+  `isTable({ draft, published })` is false, so those tables never entered the schema registry — while `databaseHandle` had registered them for by-name lookup perfectly well.
+
+  **Two registries with different populations, read by different things.** `getTable()` found the table, so insert validation knew `tenantId` was NOT NULL. The schema registry is what drives the mixins, so nothing stamped it. Measured against a real `voltro dev` boot of the scaffolded `api-cms` template, over real RPC:
+
+  ```
+  TableValidationFailed: { "table": "blogPost_drafts", "summary":
+    "missing required column 'tenantId' — NOT NULL with no default and not auto-stamped" }
+  ```
+
+  Every `content.saveDraft` in that template, since it shipped. Its own unit test could not see it, because the test builds its schema registry by hand — the one step the running app does not perform.
+
+  **The write failing was the lucky half.** Reads do not announce themselves: `makeQueryFinalizer` AND-merges `tenantId` from this same registry, so a table missing from it is a table nobody scopes. The visible symptom was a broken mutation; the invisible one was tenant isolation quietly not applied to those tables.
+
+  The fix takes the by-name registry's DELTA across each schema module's import, so a handle-declared table is attributed to the file that declared it — rather than reading the whole global registry, which by then also holds framework tables that this set deliberately excludes. It lives in `loadDiscovered`, which `voltro dev` and `voltro serve` both call, so the two cannot disagree about it.
+
+  No app change is needed; the idiomatic `databaseHandle` declaration now works as its documentation always said.
+- **@voltro/database, @voltro/cli** — A migration that fails because `DB_SCHEMA` names a schema that does not exist now says so.
+
+  Postgres answers `3F000 no schema has been selected to create in`, and the only thing that puts a non-default schema on the connection's `search_path` here is `DB_SCHEMA`. The error mentions neither the variable nor the schema, so the FIRST `CREATE TABLE` of the boot fails with a message about SQL and the reader goes looking at the DDL — for a typo in an environment variable.
+
+  Found while building the row-filter integration test below: the boot aborted, the log named `_voltro_migrations` and a postgres routine, and nothing in it pointed at the one line of configuration that caused it. Same shape as a 403 that says nothing about `VOLTRO_INSPECT_TOKEN`, fixed in the same release.
+
+  The remedy also states what the framework will NOT do: Voltro creates tables, never the schema itself. That is a namespace decision, and inventing one from a typo puts a migration somewhere nobody is looking.
+
+  `remedyFor` is deliberately a one-entry map and the test asserts the empty case as well as the full one. A remedy is worth printing only where the mapping from driver code to cause is exact; a list of maybes is how a reader learns to skip the section.
+
+  **Alongside it: the row filter is now driven under `voltro dev` against a real postgres.** Both defects that reached consumers lived between layers that were each individually covered — a module-local `let` that split per instance, then a query producer that built its context from an unscoped request — and three consumer documents carried "we have not run this against a real database" as an honest caveat. `rowFilterDevPostgres.integration.test.ts` boots the fixture twice: handlers with no predicate of their own, a filter registered from a `*.startup.tsx`, and a NEGATIVE CONTROL run with the registration skipped that asserts the same queries return BOTH owners. Without the control, "the caller saw one owner" is equally consistent with a database that only ever held one.
+- **@voltro/cli** — A shard that cannot be released no longer spins a fiber at full speed. Upstream `@effect/cluster` releases shards through `Effect.eventually` — retry until success, zero delay, logged at DEBUG — so a shard whose storage was unreachable retried as fast as the event loop allowed, in the one place nobody watches.
+
+  Our patch replaces it with `Effect.retry(Schedule.exponential(100) ∪ Schedule.spaced(5000))`. `union` takes the MINIMUM of the two delays, so the 5s spacing caps the backoff instead of compounding with it, and both schedules recur forever — attempts stay unbounded, which is what the original intended. The persistence was always correct; only the missing delay was the defect.
+
+  This entry exists because the change would otherwise have shipped undocumented. The patch lives in `packages/cli/templates/patches/`, and the changelog gate requires an entry for `packages/*/src` — so nothing would have demanded one, even though the file is installed into every user project that runs cluster. A rule that cannot see a path is not the same as a path with nothing on it.
+
+---
+
 ## [0.37.0] — 2026-08-13
 
 ### ⚠ BREAKING

package/dist/{auth-B6YZuSBr.js → auth-CKS3UNnf.js}

@@ -21,9 +21,9 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 }, te = (e, n) => p(e, n) ? t.void : t.fail(new c({
 	required: n,
 	message: `missing required scope '${n}'`
-})), m = (e) => typeof e.action == "string" && typeof e.resourceType == "string", h = (e) => typeof e.open == "string", g = (e) => ({ open: e }), _ = (e) => typeof e == "string" ? [e] : e, v, y = (e) => {
-	v = e;
-}, b = (e) => v === void 0 ? e.filter((e) => (e.guards ?? []).some((e) => !m(e) && e.resource !== void 0)).map((e) => e.tag) : [], x = (e) => [
+})), m = (e) => typeof e.action == "string" && typeof e.resourceType == "string", h = (e) => typeof e.open == "string", ne = (e) => ({ open: e }), g = (e) => typeof e == "string" ? [e] : e, _, v = (e) => {
+	_ = e;
+}, y = (e) => _ === void 0 ? e.filter((e) => (e.guards ?? []).some((e) => !m(e) && e.resource !== void 0)).map((e) => e.tag) : [], b = (e) => [
 	`${e.length} procedure${e.length === 1 ? "" : "s"} declare a per-resource guard that nothing enforces:`,
 	...e.slice(0, 10).map((e) => `    ${e}`),
 	...e.length > 10 ? [`    … and ${e.length - 10} more`] : [],
@@ -37,13 +37,13 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 	"    • setResourceScopeResolver((req) => Effect<boolean>) — answers \"does this",
 	"      subject hold `req.scope` on `req.resource`\" from your own tables.",
 	"    • Drop the `resource` extractor if a global scope check is what you meant."
-].join("\n"), S = () => v, C, ne = (e) => {
-	C = e;
-}, w = () => C, T = (e) => new c({
+].join("\n"), x = () => _, S, re = (e) => {
+	S = e;
+}, C = () => S, w = (e) => new c({
 	required: "access-decision",
 	message: `${e ?? "this procedure"} declares no access decision: it has neither \`guards:\` nor \`openAccess:\`, and the app runs with \`security.defaultDeny\`. Add the scope(s) a caller must hold (\`guards: [{ scope: '…' }]\`), or declare it open on purpose with \`openAccess: '<why anyone may call this>'\`.`
-}), E = (e, t, n) => {
-	if (!t || t.length === 0) return n?.defaultDeny === !0 ? T(n.procedure) : null;
+}), T = (e, t, n) => {
+	if (!t || t.length === 0) return n?.defaultDeny === !0 ? w(n.procedure) : null;
 	for (let n of t) {
 		if (h(n)) continue;
 		if (m(n)) {
@@ -53,7 +53,7 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 				message: `relationship guard '${n.action}' on '${n.resourceType}' cannot be checked synchronously`
 			});
 		}
-		let t = _(n.scope);
+		let t = g(n.scope);
 		if (t.length === 0) continue;
 		let r = t.filter((t) => p(e, t));
 		if (!((n.mode ?? "all") === "any" ? r.length > 0 : r.length === t.length)) {
@@ -65,13 +65,13 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 		}
 	}
 	return null;
-}, D = (e, n, r) => {
+}, E = (e, n, r) => {
 	let i = (e) => new c({
 		required: `${n.resourceType}:${n.action}`,
 		message: e
 	});
 	if (p(e, "admin:full")) return t.succeed(null);
-	let a = C;
+	let a = S;
 	if (a === void 0) return t.succeed(i(`no policy resolver registered — cannot authorize '${n.action}' on '${n.resourceType}'`));
 	let o = n.resource(r);
 	return o === void 0 || o === "" ? t.succeed(i(`input does not identify a '${n.resourceType}' to authorize`)) : t.suspend(() => a({
@@ -80,18 +80,18 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 		resourceType: n.resourceType,
 		resourceId: o
 	})).pipe(t.catchAllCause(() => t.succeed(!1)), t.map((e) => e ? null : i(`no '${n.action}' relation on ${n.resourceType}:${o}`)));
-}, O = (e, n, r, i) => {
-	if (!n || n.length === 0) return t.succeed(E(e, n, i));
-	let a = v;
-	return !n.some(m) && (!a || !n.some((e) => e.resource !== void 0)) ? t.succeed(E(e, n, i)) : t.gen(function* () {
+}, D = (e, n, r, i) => {
+	if (!n || n.length === 0) return t.succeed(T(e, n, i));
+	let a = _;
+	return !n.some(m) && (!a || !n.some((e) => e.resource !== void 0)) ? t.succeed(T(e, n, i)) : t.gen(function* () {
 		for (let i of n) {
 			if (h(i)) continue;
 			if (m(i)) {
-				let t = yield* D(e, i, r);
+				let t = yield* E(e, i, r);
 				if (t) return t;
 				continue;
 			}
-			let n = _(i.scope);
+			let n = g(i.scope);
 			if (n.length === 0) continue;
 			let o = i.resource ? i.resource(r) : void 0, s = [];
 			for (let r of n) {
@@ -119,51 +119,51 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 		}
 		return null;
 	});
-}, k = n.Record({
+}, O = n.Record({
 	key: n.String,
 	value: n.Unknown
-}), A = n.optional(n.Array(n.String)), j = n.Struct({
+}), k = n.optional(n.Array(n.String)), A = n.Struct({
 	type: n.Literal("user"),
 	id: n.String,
 	tenantId: n.String,
-	scopes: A,
-	metadata: n.optional(k)
-}), M = n.Struct({
+	scopes: k,
+	metadata: n.optional(O)
+}), j = n.Struct({
 	type: n.Literal("apiKey"),
 	id: n.String,
 	tenantId: n.String,
-	scopes: A,
-	metadata: n.optional(k)
-}), N = n.Struct({
+	scopes: k,
+	metadata: n.optional(O)
+}), M = n.Struct({
 	type: n.Literal("serviceAccount"),
 	id: n.String,
 	tenantId: n.String,
-	scopes: A,
-	metadata: n.optional(k)
-}), P = n.Struct({
+	scopes: k,
+	metadata: n.optional(O)
+}), N = n.Struct({
 	type: n.Literal("anonymous"),
 	id: n.Null,
 	tenantId: n.NullOr(n.String)
-}), F = n.Struct({
+}), P = n.Struct({
 	type: n.Literal("system"),
 	id: n.String,
 	tenantId: n.Null,
-	scopes: A,
-	metadata: n.optional(k)
-}), I = n.Union(j, M, N, P, F), L = n.Union(j.omit("scopes"), M.omit("scopes"), N.omit("scopes"), P, F.omit("scopes")), R = (e) => {
+	scopes: k,
+	metadata: n.optional(O)
+}), F = n.Union(A, j, M, N, P), I = n.Union(A.omit("scopes"), j.omit("scopes"), M.omit("scopes"), N, P.omit("scopes")), L = (e) => {
 	if (e.type === "anonymous") return e;
 	let { scopes: t, ...n } = e;
 	return n;
-}, z = (e) => e.scopes ?? [], B = (e) => ({
+}, R = (e) => e.scopes ?? [], z = (e) => ({
 	type: "anonymous",
 	id: null,
 	tenantId: e
-}), V = (e, t = ["admin:full"]) => ({
+}), B = (e, t = ["admin:full"]) => ({
 	type: "system",
 	id: e,
 	tenantId: null,
 	scopes: t
-}), H = (e, t) => {
+}), V = (e, t) => {
 	let n = e;
 	return {
 		type: "serviceAccount",
@@ -172,7 +172,7 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 		scopes: n.scopes ?? ["admin:full"],
 		...n.metadata === void 0 ? {} : { metadata: n.metadata }
 	};
-}, U = (e) => e.type === "system", W = class extends e.Tag("@voltro/Subject")() {}, G = class extends e.Tag("@voltro/ConnectionInfo")() {}, K = class extends r.Tag()("@voltro/AuthMiddleware", { provides: W }) {}, q = class extends r.Tag()("@voltro/ConnectionInfoMiddleware", { provides: G }) {}, J = (e) => typeof e.mountRoutes == "function", Y = (e) => Array.isArray(e) ? {
+}, H = (e) => e.type === "system", U = "impersonation", W = (e) => e.metadata?.impersonation ?? null, G = class extends e.Tag("@voltro/Subject")() {}, K = class extends e.Tag("@voltro/ConnectionInfo")() {}, q = class extends r.Tag()("@voltro/AuthMiddleware", { provides: G }) {}, J = class extends r.Tag()("@voltro/ConnectionInfoMiddleware", { provides: K }) {}, Y = (e) => typeof e.mountRoutes == "function", ie = (e) => Array.isArray(e) ? {
 	kind: "grant",
 	scopes: e
 } : e, X = (e, t) => {
@@ -180,7 +180,7 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 		subject: e,
 		removed: []
 	};
-	let n = z(e);
+	let n = R(e);
 	if (t.kind === "grant") {
 		if (t.scopes.length === 0) return {
 			subject: e,
@@ -203,14 +203,14 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 		},
 		removed: i
 	};
-}, re = 3e4, ie = 1e4, Z = (e) => `${e.type}\u0000${e.tenantId ?? ""}\u0000${e.id ?? ""}`, ae = () => {
+}, ae = 3e4, oe = 1e4, Z = (e) => `${e.type}\u0000${e.tenantId ?? ""}\u0000${e.id ?? ""}`, se = () => {
 	if (typeof process > "u") return;
 	let e = process.env.VOLTRO_AUTH_SCOPE_CACHE_TTL_MS;
 	if (e === void 0 || e === "") return;
 	let t = Number(e);
 	return Number.isFinite(t) && t >= 0 ? t : void 0;
 }, Q = (e = {}) => {
-	let t = e.ttlMs ?? ae() ?? 3e4, n = e.maxEntries ?? 1e4, r = e.now ?? Date.now, i = /* @__PURE__ */ new Map(), a = () => {
+	let t = e.ttlMs ?? se() ?? 3e4, n = e.maxEntries ?? 1e4, r = e.now ?? Date.now, i = /* @__PURE__ */ new Map(), a = () => {
 		if (i.size <= n) return;
 		let e = r();
 		for (let [t, n] of i) n.freshUntil <= e && i.delete(t);
@@ -246,8 +246,8 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 			};
 		}
 	};
-}, oe = (e) => typeof e.resolve == "function", se = (e, t) => {
-	let n = t?.resolveScopes, r = n === void 0 || t?.scopeCache === !1 ? null : t?.scopeCache !== void 0 && oe(t.scopeCache) ? t.scopeCache : Q(t?.scopeCache ?? {});
+}, ce = (e) => typeof e.resolve == "function", le = (e, t) => {
+	let n = t?.resolveScopes, r = n === void 0 || t?.scopeCache === !1 ? null : t?.scopeCache !== void 0 && ce(t.scopeCache) ? t.scopeCache : Q(t?.scopeCache ?? {});
 	return async (i) => {
 		let a = t?.getStore?.(), o = a === void 0 ? i : {
 			...i,
@@ -258,7 +258,7 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 			if (e.kind === "matched") {
 				let a = e.subject;
 				if (n !== void 0) {
-					let s = async () => Y(await n(e.subject, o)), { decision: c, fresh: l } = r === null ? {
+					let s = async () => ie(await n(e.subject, o)), { decision: c, fresh: l } = r === null ? {
 						decision: await s(),
 						fresh: !0
 					} : await r.resolve(Z(e.subject), s);
@@ -294,10 +294,10 @@ var i = "admin:full", a = "apikeys:issue:self", o = "apikeys:issue:org", s = "ap
 		if (t?.fallback) return { subject: await t.fallback(o) };
 		let s = o.headers["x-tenant"] ?? null;
 		if (s === null && t?.anonymousTenantRequired === !0) throw new $({ reason: "tenant required (x-tenant header missing)" });
-		return { subject: B(s) };
+		return { subject: z(s) };
 	};
-}, $ = class extends n.TaggedError()("Unauthenticated", { reason: n.optional(n.String) }) {}, ce = (e, t) => {
+}, $ = class extends n.TaggedError()("Unauthenticated", { reason: n.optional(n.String) }) {}, ue = (e, t) => {
 	if (e.type === "anonymous") throw new $(t === void 0 ? {} : { reason: t });
 };
 //#endregion
-export { b as A, d as B, s as C, E as D, x as E, h as F, y as H, m as I, T as L, S as M, p as N, O, ee as P, g as R, o as S, c as T, l as U, ne as V, Z as _, re as a, H as b, W as c, X as d, ce as f, Q as g, U as h, ie as i, w as j, f as k, $ as l, J as m, G as n, I as o, se as p, q as r, L as s, K as t, B as u, R as v, a as w, i as x, V as y, te as z };
+export { D as A, ne as B, i as C, c as D, a as E, p as F, l as G, d as H, ee as I, h as L, y as M, C as N, b as O, x as P, m as R, V as S, s as T, re as U, te as V, v as W, Q as _, ae as a, L as b, I as c, z as d, X as f, H as g, Y as h, oe as i, f as j, T as k, G as l, le as m, K as n, U as o, ue as p, J as r, F as s, q as t, $ as u, W as v, o as w, B as x, Z as y, w as z };

package/dist/index.d.ts

@@ -2181,6 +2181,21 @@ export declare interface IdempotencyStore {
  *  corrupt the pointer. */
 export declare const idToPath: (id: RowId) => string;
 
+/**
+ * `Subject.metadata` is the APP's bag — opaque to the framework, stored
+ * verbatim — with exactly one reserved key: this one. It carries the mark that
+ * says the session is an impersonated one.
+ *
+ * **Why it lives in protocol and not in `@voltro/plugin-auth`, which mints it.**
+ * Two packages need the answer to "is this session impersonated" and they must
+ * not depend on each other: plugin-auth WRITES the mark, and plugin-audit reads
+ * it to stamp `AuditEvent.impersonation` before redaction runs. A key spelled
+ * out in both is a second definition that no guard is watching — the shape this
+ * repo has been bitten by often enough to have a rule about it. `Subject` is
+ * protocol's type, so its reserved key is protocol's too.
+ */
+export declare const IMPERSONATION_METADATA_KEY: "impersonation";
+
 export declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
     readonly table: string;
     readonly op: 'insert';
@@ -3591,6 +3606,18 @@ export declare const queryToRpc: <Name extends string, Input extends Schema.Sche
     revision: Schema.optional<typeof Schema.Number>;
 }>]>, Schema.Schema.All>, typeof Schema.Never, never>;
 
+/**
+ * The RAW mark, unvalidated, or `null`.
+ *
+ * Deliberately `unknown`: protocol owns the key, not the payload's shape.
+ * `@voltro/plugin-auth` mints the mark and validates it back into an
+ * `ImpersonationMark`; an auditor only needs to copy it out before a redactor
+ * can reach it, and giving protocol an opinion about the fields would make the
+ * shape need to agree in two places again — the exact thing the key moved here
+ * to avoid.
+ */
+export declare const rawImpersonationMark: (subject: Subject) => unknown;
+
 /** The `channel:` namespace. Every channel key starts with it. */
 export declare const REACTIVITY_CHANNEL_PREFIX = "channel:";