@classytic/arc 2.22.0 → 2.25.0

package/dist/headers-BvlQSDMB.mjs

@@ -0,0 +1,45 @@
+import { u as ValidationError } from "./errors-DkO8Nk6-.mjs";
+//#region src/utils/headers.ts
+/**
+* Canonical header typing + accessor.
+*
+* Node/Fastify header values are `string | string[] | undefined` — repeated
+* headers arrive as arrays. `IRequestContext.headers` is DECLARED as
+* `Record<string, string | undefined>` for ergonomic host code, but the HTTP
+* adapter passes Fastify's headers object through unchanged, so `string[]`
+* CAN appear at runtime behind the narrower type (the declared type is
+* scheduled to widen to {@link ArcHeaders} in v3). Until then, read headers
+* through {@link getHeader} instead of indexing — it's honest about arrays
+* and deterministic about duplicates.
+*/
+/**
+* Read a single header value. Lowercases the name (Node normalizes incoming
+* header names to lowercase) and returns the FIRST value when the header
+* was repeated.
+*
+* Duplicate policy: first-value is deterministic, but for security-sensitive
+* headers (authorization material, forwarded-for chains, content-length) a
+* duplicate usually signals smuggling or a broken proxy — consumers that
+* care should check `Array.isArray(headers[name])` and REJECT instead of
+* picking a winner.
+*/
+function getHeader(headers, name) {
+	if (!headers) return void 0;
+	const value = headers[name.toLowerCase()];
+	if (Array.isArray(value)) return value[0];
+	return value;
+}
+/**
+* Read an identity-bearing or protocol header and reject repeated values.
+*
+* Repeated security-sensitive headers are ambiguous at proxy boundaries and
+* may indicate request smuggling. Callers must not silently choose a winner.
+*/
+function requireSingleHeaderValue(headers, name) {
+	if (!headers) return void 0;
+	const value = headers[name.toLowerCase()];
+	if (Array.isArray(value)) throw new ValidationError(`Duplicate '${name}' header`);
+	return value;
+}
+//#endregion
+export { requireSingleHeaderValue as n, getHeader as t };

package/dist/health-CB_m4S32.mjs

@@ -0,0 +1,377 @@
+import { randomUUID } from "node:crypto";
+import fp from "fastify-plugin";
+//#region src/plugins/requestId.ts
+/**
+* Request ID Plugin
+*
+* Propagates request IDs for distributed tracing.
+* - Accepts incoming x-request-id header (sanitized)
+* - Generates UUID if not provided
+* - Echoes the id on the response header + W3C trace-context propagation
+*
+* ID RESOLUTION LIVES AT THE SERVER LEVEL, NOT HERE. Fastify binds
+* `request.log = logger.child({ reqId: request.id })` at request
+* construction — before any hook runs — so an id assigned inside a hook
+* never reaches the logs. `createApp` therefore wires
+* {@link createRequestIdGenerator} into Fastify's `genReqId` option, and
+* this plugin simply adopts `request.id`. Standalone registration on a
+* bare Fastify instance falls back to the legacy in-hook resolution
+* (header echo / UUID), with the documented limitation that
+* `request.log`'s `reqId` binding predates the overwrite — pass
+* `genReqId: createRequestIdGenerator()` to `Fastify()` to fix that.
+*
+* @example
+* import { requestIdPlugin, createRequestIdGenerator } from '@classytic/arc';
+*
+* const fastify = Fastify({ genReqId: createRequestIdGenerator() });
+* await fastify.register(requestIdPlugin);
+*
+* fastify.get('/', async (request) => {
+*   request.log.info('traced');   // carries the same reqId as the header
+*   return { id: request.id };
+* });
+*/
+/**
+* Sanitize an incoming request-id header value: max 128 chars, alphanumeric
+* plus dashes/underscores/dots/colons only. Returns `undefined` for anything
+* else (crafted values could pollute logs or response headers). Array values
+* (repeated headers) are rejected outright — a client sending multiple
+* request-id headers is not tracing in good faith.
+*/
+function sanitizeRequestId(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 && trimmed.length <= 128 && /^[\w.:-]+$/.test(trimmed) ? trimmed : void 0;
+}
+/**
+* Build a Fastify `genReqId` function: adopt a sanitized incoming request-id
+* header, or generate one. Wire this into the `Fastify()` constructor so
+* `request.id`, `request.log`'s `reqId` binding, and the echoed response
+* header all agree — `createApp` does this automatically.
+*/
+function createRequestIdGenerator(opts = {}) {
+	const { header = "x-request-id", generator = randomUUID } = opts;
+	const headerName = header.toLowerCase();
+	return (req) => sanitizeRequestId(req.headers[headerName]) ?? generator();
+}
+/** Fastify's default request ids are `req-<base36 counter>`. */
+const FASTIFY_DEFAULT_ID = /^req-[0-9a-z]+$/;
+/** W3C traceparent format: `version-traceid-parentid-flags` */
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i;
+/** W3C spec: version ff is reserved and invalid; trace/parent IDs must not be all zeros */
+const TRACEID_ZEROS = "0".repeat(32);
+const PARENTID_ZEROS = "0".repeat(16);
+/** tracestate: printable ASCII, <= 512 bytes */
+const TRACESTATE_MAX = 512;
+function isValidTraceparent(tp) {
+	const m = TRACEPARENT_RE.exec(tp);
+	if (!m) return false;
+	const version = m[1] ?? "";
+	const traceId = m[2] ?? "";
+	const parentId = m[3] ?? "";
+	if (version.toLowerCase() === "ff") return false;
+	if (traceId.toLowerCase() === TRACEID_ZEROS) return false;
+	if (parentId.toLowerCase() === PARENTID_ZEROS) return false;
+	return true;
+}
+const requestIdPlugin = async (fastify, opts = {}) => {
+	const { header = "x-request-id", generator = randomUUID, setResponseHeader = true, propagateTraceContext = true } = opts;
+	if (!fastify.hasRequestDecorator("requestId")) fastify.decorateRequest("requestId", "");
+	if (!fastify.hasRequestDecorator("traceContext")) fastify.decorateRequest("traceContext", void 0);
+	fastify.addHook("onRequest", async (request, reply) => {
+		const incoming = sanitizeRequestId(request.headers[header]);
+		let requestId = String(request.id);
+		if (incoming && incoming !== requestId) requestId = incoming;
+		else if (!incoming && FASTIFY_DEFAULT_ID.test(requestId)) requestId = generator();
+		if (requestId !== request.id) request.id = requestId;
+		request.requestId = requestId;
+		if (setResponseHeader) reply.header(header, requestId);
+		if (propagateTraceContext) {
+			const rawTraceparent = request.headers.traceparent;
+			const rawTracestate = request.headers.tracestate;
+			if (typeof rawTraceparent === "string") {
+				const tp = rawTraceparent.trim();
+				if (isValidTraceparent(tp)) {
+					const ts = typeof rawTracestate === "string" && rawTracestate.length > 0 && rawTracestate.length <= TRACESTATE_MAX ? rawTracestate : void 0;
+					request.traceContext = {
+						traceparent: tp,
+						...ts ? { tracestate: ts } : {}
+					};
+					reply.header("traceparent", tp);
+					if (ts) reply.header("tracestate", ts);
+				}
+			}
+		}
+	});
+	fastify.log?.debug?.("Request ID plugin registered");
+};
+var requestId_default = fp(requestIdPlugin, {
+	name: "arc-request-id",
+	fastify: "5.x"
+});
+//#endregion
+//#region src/plugins/health.ts
+/**
+* Merge health checks without losing ownership information.
+*
+* Check names are the identity used in readiness responses and criticality
+* lookup, so duplicates are ambiguous and fail at boot instead of silently
+* picking the first declaration. Input order is preserved.
+*/
+function mergeHealthChecks(groups) {
+	const owners = /* @__PURE__ */ new Map();
+	const merged = [];
+	for (const group of groups) for (const check of group.checks ?? []) {
+		const prior = owners.get(check.name);
+		if (prior !== void 0) throw new Error(`[arc] duplicate health-check name "${check.name}" — declared by ${prior} and ${group.owner}. Health-check names must be unique.`);
+		owners.set(check.name, group.owner);
+		merged.push(check);
+	}
+	return merged;
+}
+/**
+* Fixed histogram bucket upper bounds (ms). Recording is O(#buckets) per
+* request; the scrape derives quantile UPPER BOUNDS from cumulative counts
+* in O(#buckets) — no sample retention, no per-scrape sort (the previous
+* 10k-sample ring buffer copied + sorted on EVERY scrape), and bucket
+* counts aggregate correctly across instances.
+*/
+const DURATION_BUCKETS_MS = [
+	1,
+	2,
+	5,
+	10,
+	25,
+	50,
+	100,
+	250,
+	500,
+	1e3,
+	2500,
+	5e3,
+	1e4
+];
+function createHttpMetrics() {
+	return {
+		requestsTotal: {},
+		durationBuckets: new Array(DURATION_BUCKETS_MS.length + 1).fill(0),
+		durationCount: 0,
+		durationSumMs: 0,
+		startTime: Date.now()
+	};
+}
+/** Smallest bucket upper bound whose cumulative count reaches `q × total`. */
+function bucketQuantile(metrics, q) {
+	const target = Math.ceil(metrics.durationCount * q);
+	let cumulative = 0;
+	for (let i = 0; i < metrics.durationBuckets.length; i++) {
+		cumulative += metrics.durationBuckets[i] ?? 0;
+		if (cumulative >= target) return DURATION_BUCKETS_MS[i] ?? DURATION_BUCKETS_MS[DURATION_BUCKETS_MS.length - 1] ?? 0;
+	}
+	return DURATION_BUCKETS_MS[DURATION_BUCKETS_MS.length - 1] ?? 0;
+}
+const healthPlugin = async (fastify, opts = {}) => {
+	const { prefix = "/_health", checks = [], metrics = false, metricsCollector, version, collectHttpMetrics = metrics } = opts;
+	const readinessChecks = mergeHealthChecks([{
+		owner: "healthPlugin options",
+		checks
+	}]);
+	const httpMetrics = createHttpMetrics();
+	fastify.get(prefix, { schema: {
+		tags: ["Health"],
+		summary: "Liveness probe (alias for /live)",
+		description: "Returns 200 if the process is alive",
+		response: { 200: {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["ok"]
+				},
+				timestamp: { type: "string" },
+				version: { type: "string" }
+			}
+		} }
+	} }, async () => ({
+		status: "ok",
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		...version ? { version } : {}
+	}));
+	fastify.get(`${prefix}/live`, { schema: {
+		tags: ["Health"],
+		summary: "Liveness probe",
+		description: "Returns 200 if the process is alive",
+		response: { 200: {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["ok"]
+				},
+				timestamp: { type: "string" },
+				version: { type: "string" }
+			}
+		} }
+	} }, async () => {
+		return {
+			status: "ok",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			...version ? { version } : {}
+		};
+	});
+	fastify.get(`${prefix}/ready`, { schema: {
+		tags: ["Health"],
+		summary: "Readiness probe",
+		description: "Returns 200 if all dependencies are healthy",
+		response: {
+			200: {
+				type: "object",
+				properties: {
+					status: {
+						type: "string",
+						enum: ["ready", "not_ready"]
+					},
+					timestamp: { type: "string" },
+					checks: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								name: { type: "string" },
+								healthy: { type: "boolean" },
+								duration: { type: "number" },
+								error: { type: "string" }
+							}
+						}
+					}
+				}
+			},
+			503: {
+				type: "object",
+				properties: {
+					status: {
+						type: "string",
+						enum: ["not_ready"]
+					},
+					timestamp: { type: "string" },
+					checks: { type: "array" }
+				}
+			}
+		}
+	} }, async (_, reply) => {
+		const results = await runChecks(readinessChecks);
+		const criticalFailed = results.some((result, index) => !result.healthy && (readinessChecks[index]?.critical ?? true));
+		const response = {
+			status: criticalFailed ? "not_ready" : "ready",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			checks: results
+		};
+		if (criticalFailed) reply.code(503);
+		return response;
+	});
+	if (metrics) fastify.get(`${prefix}/metrics`, async (_, reply) => {
+		reply.type("text/plain; charset=utf-8");
+		if (metricsCollector) return await metricsCollector();
+		const uptime = process.uptime();
+		const memory = process.memoryUsage();
+		const cpu = process.cpuUsage();
+		const lines = [
+			"# HELP process_uptime_seconds Process uptime in seconds",
+			"# TYPE process_uptime_seconds gauge",
+			`process_uptime_seconds ${uptime.toFixed(2)}`,
+			"",
+			"# HELP process_memory_heap_bytes Heap memory usage in bytes",
+			"# TYPE process_memory_heap_bytes gauge",
+			`process_memory_heap_bytes{type="used"} ${memory.heapUsed}`,
+			`process_memory_heap_bytes{type="total"} ${memory.heapTotal}`,
+			"",
+			"# HELP process_memory_rss_bytes RSS memory in bytes",
+			"# TYPE process_memory_rss_bytes gauge",
+			`process_memory_rss_bytes ${memory.rss}`,
+			"",
+			"# HELP process_memory_external_bytes External memory in bytes",
+			"# TYPE process_memory_external_bytes gauge",
+			`process_memory_external_bytes ${memory.external}`,
+			"",
+			"# HELP process_cpu_user_microseconds User CPU time in microseconds",
+			"# TYPE process_cpu_user_microseconds counter",
+			`process_cpu_user_microseconds ${cpu.user}`,
+			"",
+			"# HELP process_cpu_system_microseconds System CPU time in microseconds",
+			"# TYPE process_cpu_system_microseconds counter",
+			`process_cpu_system_microseconds ${cpu.system}`,
+			""
+		];
+		if (collectHttpMetrics && Object.keys(httpMetrics.requestsTotal).length > 0) {
+			lines.push("# HELP http_requests_total Total HTTP requests by status code", "# TYPE http_requests_total counter");
+			for (const [status, count] of Object.entries(httpMetrics.requestsTotal)) lines.push(`http_requests_total{status="${status}"} ${count}`);
+			lines.push("");
+			if (httpMetrics.durationCount > 0) {
+				const p50 = bucketQuantile(httpMetrics, .5);
+				const p95 = bucketQuantile(httpMetrics, .95);
+				const p99 = bucketQuantile(httpMetrics, .99);
+				lines.push("# HELP http_request_duration_milliseconds HTTP request duration (bucket upper bounds)", "# TYPE http_request_duration_milliseconds summary", `http_request_duration_milliseconds{quantile="0.5"} ${p50.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.95"} ${p95.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.99"} ${p99.toFixed(2)}`, `http_request_duration_milliseconds_sum ${httpMetrics.durationSumMs.toFixed(2)}`, `http_request_duration_milliseconds_count ${httpMetrics.durationCount}`, "");
+			}
+		}
+		return lines.join("\n");
+	});
+	if (collectHttpMetrics) fastify.addHook("onResponse", async (_request, reply) => {
+		const duration = reply.elapsedTime;
+		const statusBucket = `${Math.floor(reply.statusCode / 100)}xx`;
+		httpMetrics.requestsTotal[statusBucket] = (httpMetrics.requestsTotal[statusBucket] || 0) + 1;
+		let bucket = DURATION_BUCKETS_MS.length;
+		for (let i = 0; i < DURATION_BUCKETS_MS.length; i++) {
+			const bound = DURATION_BUCKETS_MS[i];
+			if (bound !== void 0 && duration <= bound) {
+				bucket = i;
+				break;
+			}
+		}
+		httpMetrics.durationBuckets[bucket] = (httpMetrics.durationBuckets[bucket] ?? 0) + 1;
+		httpMetrics.durationCount++;
+		httpMetrics.durationSumMs += duration;
+	});
+	fastify.log?.debug?.(`Health plugin registered at ${prefix} (alias), ${prefix}/live, ${prefix}/ready${metrics ? `, ${prefix}/metrics` : ""}`);
+};
+/**
+* Run all health checks with timeout
+*/
+async function runChecks(checks) {
+	return Promise.all(checks.map(async (check) => {
+		const start = Date.now();
+		const timeout = check.timeout ?? 5e3;
+		let timer;
+		const abort = new AbortController();
+		try {
+			const checkPromise = Promise.resolve(check.check(abort.signal));
+			const timeoutPromise = new Promise((_, reject) => {
+				timer = setTimeout(() => {
+					const err = /* @__PURE__ */ new Error("Health check timeout");
+					abort.abort(err);
+					reject(err);
+				}, timeout);
+			});
+			const healthy = await Promise.race([checkPromise, timeoutPromise]);
+			return {
+				name: check.name,
+				healthy: Boolean(healthy),
+				duration: Date.now() - start
+			};
+		} catch (err) {
+			return {
+				name: check.name,
+				healthy: false,
+				duration: Date.now() - start,
+				error: err.message
+			};
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}));
+}
+var health_default = fp(healthPlugin, {
+	name: "arc-health",
+	fastify: "5.x"
+});
+//#endregion
+export { requestIdPlugin as a, createRequestIdGenerator as i, health_default as n, requestId_default as o, mergeHealthChecks as r, sanitizeRequestId as s, healthPlugin as t };

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-import { Cn as afterDelete, Dn as beforeUpdate, En as beforeDelete, On as createHookSystem, Sn as afterCreate, Tn as beforeCreate, _n as HookOperation, bn as HookSystem, gn as HookHandler, hn as HookContext, kn as defineHook, mn as DefineHookOptions, vn as HookPhase, wn as afterUpdate, xn as HookSystemOptions, yn as HookRegistration } from "../index-DbtgCOCj.mjs";
+import { Cn as defineHook, Sn as createHookSystem, _n as afterDelete, bn as beforeDelete, cn as DefineHookOptions, dn as HookOperation, fn as HookPhase, gn as afterCreate, hn as HookSystemOptions, ln as HookContext, mn as HookSystem, pn as HookRegistration, un as HookHandler, vn as afterUpdate, xn as beforeUpdate, yn as beforeCreate } from "../index-DPRH0Cme.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -77,6 +77,13 @@ declare module "fastify" {
        * ```
        */
       middleware: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+      /**
+       * The resolved backing store. Exposed so non-HTTP executors (MCP
+       * tools via `mcpPlugin`'s execution wiring, jobs, workflows) can run
+       * the same check → lock → execute → record protocol against the same
+       * backend. `undefined` when the plugin is disabled.
+       */
+      store?: IdempotencyStore;
     };
   }
 }

package/dist/idempotency/index.mjs

@@ -1,4 +1,6 @@
+import { n as requireSingleHeaderValue } from "../headers-BvlQSDMB.mjs";
 import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DY6xq4sM.mjs";
+import { t as createIdempotencyResult } from "../interface-n5hpKg1d.mjs";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
 import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
@@ -100,21 +102,6 @@ function repositoryAsIdempotencyStore(repository, defaultTtlMs) {
 	};
 }
 //#endregion
-//#region src/idempotency/stores/interface.ts
-/**
-* Helper to create a result object
-*/
-function createIdempotencyResult(statusCode, body, headers, ttlMs) {
-	const now = /* @__PURE__ */ new Date();
-	return {
-		statusCode,
-		headers,
-		body,
-		createdAt: now,
-		expiresAt: new Date(now.getTime() + ttlMs)
-	};
-}
-//#endregion
 //#region src/idempotency/stores/memory.ts
 var MemoryIdempotencyStore = class {
 	name = "memory";
@@ -263,6 +250,26 @@ var MemoryIdempotencyStore = class {
 * // Idempotency-Key: order-123-abc
 *
 * // If same key sent again within TTL, returns cached response
+*
+* ## Guarantee: best-effort effectively-once, NOT exactly-once
+*
+* The plugin gives strong request replay + overlap protection: a
+* distributed lock guards execution (concurrent same-key requests get
+* 409), the store key includes a body/caller fingerprint (a different
+* body under the same key executes as its own operation instead of
+* replaying someone else's response), and a completed result replays on
+* hit. It does NOT make the business effect exactly-once, because the
+* domain write and the idempotency record live in different systems:
+*
+*  - a crash after the DB mutation but before the result is recorded
+*    (preSerialization) lets a retry re-execute the mutation;
+*  - a handler that outruns `lockTimeoutMs` can overlap its own retry —
+*    size the lock timeout above the slowest protected handler.
+*
+* For mutations where re-execution is unacceptable, write the idempotency
+* record in the SAME transaction as the business write inside the handler
+* (the store contract is public — `@classytic/arc/idempotency` exports it),
+* or make the handler naturally idempotent (upserts, compare-and-set).
 */
 const HEADER_IDEMPOTENCY_REPLAYED = "x-idempotency-replayed";
 const HEADER_IDEMPOTENCY_KEY = "x-idempotency-key";
@@ -283,7 +290,8 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		fastify.decorate("idempotency", {
 			invalidate: async () => {},
 			has: async () => false,
-			middleware: async () => {}
+			middleware: async () => {},
+			store: void 0
 		});
 		fastify.decorateRequest("idempotencyKey", void 0);
 		fastify.decorateRequest("idempotencyReplayed", false);
@@ -319,7 +327,11 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 	*/
 	function normalizeBody(obj, depth = 0) {
 		if (obj === null || typeof obj !== "object") return obj;
-		if (depth >= MAX_FINGERPRINT_DEPTH) return "<truncated>";
+		if (depth >= MAX_FINGERPRINT_DEPTH) try {
+			return `<deep:${createHash("sha256").update(JSON.stringify(obj)).digest("hex").slice(0, 16)}>`;
+		} catch {
+			return "<truncated>";
+		}
 		if (Array.isArray(obj)) return obj.map((item) => normalizeBody(item, depth + 1));
 		const sorted = {};
 		const keys = Object.keys(obj).sort();
@@ -348,8 +360,7 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 	}
 	const idempotencyMiddleware = async (request, reply) => {
 		if (!shouldApplyIdempotency(request)) return;
-		const keyHeader = request.headers[headerName.toLowerCase()];
-		const idempotencyKey = typeof keyHeader === "string" ? keyHeader.trim() : void 0;
+		const idempotencyKey = requireSingleHeaderValue(request.headers, headerName)?.trim();
 		if (!idempotencyKey) return;
 		request.idempotencyKey = idempotencyKey;
 		const fullKey = `${idempotencyKey}:${getRequestFingerprint(request)}`;
@@ -380,7 +391,8 @@ const idempotencyPlugin = async (fastify, opts = {}) => {
 		has: async (key) => {
 			return !!await store.findByPrefix(`${key}:`);
 		},
-		middleware: idempotencyMiddleware
+		middleware: idempotencyMiddleware,
+		store
 	});
 	fastify.addHook("preSerialization", async (request, reply, payload) => {
 		if (request.idempotencyReplayed) return payload;

package/dist/{index-ogIHvOjo.d.mts → index-BMnbzvtO.d.mts}

@@ -1,6 +1,6 @@
-import { r as CacheStore, t as CacheLogger } from "./interface-C1_WLTMK.mjs";
-import { i as RequestScope, n as Mandate } from "./types-DH0GupI7.mjs";
-import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-Csxga7d3.mjs";
+import { r as CacheStore, t as CacheLogger } from "./interface-BGZCzOGL.mjs";
+import { i as RequestScope, n as Mandate } from "./types-DjC-KUCz.mjs";
+import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-Dmw-6Qeo.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 //#region src/permissions/agent.d.ts
 /**
@@ -449,6 +449,72 @@ declare function createOrgPermissions(config: {
  */
 declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixConfig): DynamicPermissionMatrix;
 //#endregion
+//#region src/permissions/grants.d.ts
+/**
+ * The grant-mode lattice, weakest → strongest. Holding a mode satisfies
+ * every mode at or below it (`write` ⊇ `read` ⊇ `list` ⊇ `see`); `manage`
+ * (grant/revoke rights) satisfies everything. Same semantics as Puter's
+ * `see < list < read < write` hierarchy with `manage` folded into the
+ * lattice top instead of a separate string namespace.
+ */
+declare const GRANT_MODES: readonly ["see", "list", "read", "write", "manage"];
+/** One mode from the {@link GRANT_MODES} lattice. */
+type GrantMode = (typeof GRANT_MODES)[number];
+/**
+ * Does a HELD mode satisfy a REQUIRED mode? Lattice implication —
+ * `modeSatisfies('write', 'read') === true`, `modeSatisfies('see', 'read')
+ * === false`. Unknown strings (a corrupted grant row) never satisfy
+ * anything: fail-closed.
+ */
+declare function modeSatisfies(held: string | undefined, required: GrantMode): boolean;
+/**
+ * What a grant `resolve` callback may return:
+ *
+ * - `boolean` — the host did the whole check itself (already compared modes).
+ * - `{ mode }` — the strongest mode the caller holds on `ctx.resourceId`;
+ *   the combinator applies the lattice against the required mode.
+ * - `{ filters }` — list-shaped resolution: row filters that scope the
+ *   query to visible records (flows through `PermissionResult.filters` →
+ *   `_policyFilters` → the repository query). Grants access with the
+ *   filters attached.
+ * - `{ mode, filters }` — mode gates; filters ride along when it passes.
+ *
+ * An empty object (neither `mode` nor `filters`) and a thrown error both
+ * DENY — grant resolution is fail-closed, same stance as `isRevoked`.
+ */
+type GrantResolution = boolean | {
+  mode?: GrantMode | string;
+  filters?: Record<string, unknown>;
+  /** Optional denial reason surfaced on the 403 (clamped by the framework). */
+  reason?: string;
+};
+interface RequireGrantOptions {
+  /** The mode this operation needs (lattice-checked against the held mode). */
+  mode: GrantMode;
+  /**
+   * Look up the caller's grant. Receives the full `PermissionContext`
+   * (`resourceId` for single-record ops, `request` for headers/scope —
+   * e.g. a share-link token). May be sync or async.
+   *
+   * NOTE: unauthenticated callers are NOT rejected up front — share links
+   * grant access to anonymous callers by design. If your grants are
+   * session-only, return `false` when `ctx.user` is null (or compose with
+   * `requireAuth()` via `allOf`).
+   */
+  resolve: (ctx: PermissionContext) => GrantResolution | Promise<GrantResolution>;
+  /** Roles that skip the grant check entirely (platform admins). */
+  bypassRoles?: readonly string[];
+}
+/**
+ * Per-record grant gate. Same combinator tier as `requireOwnership` —
+ * compose with `anyOf`/`allOf` like any other `PermissionCheck`.
+ *
+ * Fail-closed contract: resolver throws → denied (logged via
+ * `ctx.request.log`); resolution carries neither `mode` nor `filters` →
+ * denied; unknown/corrupted mode strings → denied.
+ */
+declare function requireGrant(options: RequireGrantOptions): PermissionCheck;
+//#endregion
 //#region src/permissions/roleHierarchy.d.ts
 /**
  * Role Hierarchy — Composable RBAC Inheritance
@@ -706,4 +772,4 @@ declare function fullPublic<TDoc = Record<string, unknown>>(overrides?: Permissi
  */
 declare function readOnly<TDoc = Record<string, unknown>>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
 //#endregion
-export { requireOwnership as A, requireMandate as B, createOrgPermissions as C, denyAll as D, anyOf as E, normalizePermissionResult as F, RequireAgentScopeOptions as I, RequireMandateOptions as L, roles as M, when as N, not as O, applyPermissionResult as P, requireAgentScope as R, createDynamicPermissionMatrix as S, allowPublic as T, createRoleHierarchy as _, permissionMatrix as a, DynamicPermissionMatrixConfig as b, publicReadAdminWrite as c, requireOrgMembership as d, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, requireRoles as j, requireAuth as k, readOnly as l, requireServiceScope as m, authenticated as n, presets_d_exports as o, requireScopeContext as p, fullPublic as r, publicRead as s, adminOnly as t, requireOrgInScope as u, ConnectEventsOptions as v, allOf as w, PermissionEventBus as x, DynamicPermissionMatrix as y, requireDPoP as z };
+export { allOf as A, applyPermissionResult as B, requireGrant as C, PermissionEventBus as D, DynamicPermissionMatrixConfig as E, requireAuth as F, requireDPoP as G, RequireAgentScopeOptions as H, requireOwnership as I, requireMandate as K, requireRoles as L, anyOf as M, denyAll as N, createDynamicPermissionMatrix as O, not as P, roles as R, modeSatisfies as S, DynamicPermissionMatrix as T, RequireMandateOptions as U, normalizePermissionResult as V, requireAgentScope as W, createRoleHierarchy as _, permissionMatrix as a, GrantResolution as b, publicReadAdminWrite as c, requireOrgMembership as d, requireOrgRole as f, RoleHierarchy as g, requireTeamMembership as h, ownerWithAdminBypass as i, allowPublic as j, createOrgPermissions as k, readOnly as l, requireServiceScope as m, authenticated as n, presets_d_exports as o, requireScopeContext as p, fullPublic as r, publicRead as s, adminOnly as t, requireOrgInScope as u, GRANT_MODES as v, ConnectEventsOptions as w, RequireGrantOptions as x, GrantMode as y, when as z };