@kici-dev/engine 0.0.0 → 0.1.0

package/dist/audit/access-log-policy.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Per-action access-log policy + sampling helper.
+ *
+ * Single source of truth for the keep / sample / rate-limit decision used by
+ * the orchestrator's `access_log` writer. The policy table is exhaustive
+ * over `AccessLogAction.options` so a new enum value without a policy entry
+ * is a compile-time error.
+ *
+ * Override layers (applied in `shouldRecordAccess`, in order):
+ *
+ * 1. `outcome !== 'allowed'` → always record (denied/error are full-fidelity).
+ * 2. `actor.type === 'platform_operator'` → always record (compliance: any
+ *    activity by a non-org member must be auditable in full).
+ * 3. The per-action `POLICY_BY_ACTION` decision (`always` / `sample` /
+ *    `rate_limit`).
+ *
+ * Browser-safe: this module MUST NOT import any Node built-ins (`node:crypto`
+ * etc.). It is re-exported via the `@kici-dev/engine` barrel which the
+ * dashboard imports. Sampling uses a tiny inline FNV-1a 32-bit hash.
+ */
+import { z } from 'zod';
+import { AccessLogAction, type AccessLogOutcome } from '../protocol/messages/access-log.js';
+import { type ActorPrincipal } from '../protocol/messages/actor.js';
+/** Discriminator for the per-action policy entry. */
+export declare const AccessLogPolicyKind: z.ZodEnum<{
+    always: "always";
+    sample: "sample";
+    rate_limit: "rate_limit";
+}>;
+export type AccessLogPolicyKind = z.infer<typeof AccessLogPolicyKind>;
+export type AccessLogPolicy = {
+    kind: 'always';
+} | {
+    kind: 'sample';
+    allowedRate: number;
+} | {
+    kind: 'rate_limit';
+    perMinutePerActor: number;
+};
+/**
+ * Minimal interface for the rate-limit decision so the engine stays
+ * dependency-free. Orchestrator wires in a real `SamplingRateLimiter`.
+ */
+export interface AccessLogRateLimiter {
+    permit(action: AccessLogAction, actorKey: string, perMinute: number): boolean;
+}
+/**
+ * Policy table mirroring research-doc §2 verdicts (with the user's
+ * §7 platform-operator override applied separately in `shouldRecordAccess`).
+ *
+ * Exhaustive over `AccessLogAction.options` — TypeScript catches additions.
+ */
+export declare const POLICY_BY_ACTION: Record<AccessLogAction, AccessLogPolicy>;
+/**
+ * Tiny FNV-1a 32-bit hash. Used for stable hash-based sampling so a single
+ * actor's request stream lands in the same sampling bucket repeatedly.
+ *
+ * Pure JS, no Node built-ins (engine barrel must stay browser-safe).
+ */
+export declare function fnv1a32(input: string): number;
+/**
+ * Decide whether to write an `access_log` row for the given action.
+ *
+ * @param action     The action being attempted.
+ * @param outcome    `allowed` / `denied` / `error`.
+ * @param actor      The principal performing the action.
+ * @param requestId  The orchestrator request id (used for stable sampling).
+ * @param limiter    Rate-limiter instance (only consulted for `rate_limit`
+ *                   actions; tests can pass a stub).
+ *
+ * Returns `true` to write the row, `false` to drop.
+ */
+export declare function shouldRecordAccess(action: AccessLogAction, outcome: AccessLogOutcome, actor: ActorPrincipal, requestId: string | null, limiter: AccessLogRateLimiter): boolean;
+/**
+ * Decide whether to write a `secret_audit_log` row for `resolve` /
+ * `resolve_named`. Volume class is per-job (every step's secret resolution),
+ * so the sample rate is much lower than `access_log`.
+ *
+ * The secret-resolver's `AuditEntry` doesn't carry an `ActorPrincipal` —
+ * we synthesise a stable key from `runId` / `jobId` so a single job's
+ * trace either lands wholesale in the sample or doesn't.
+ *
+ * @param entry      The audit entry being written (action, outcome, runId,
+ *                   jobId, userId, role).
+ * @param requestId  Optional sampler salt (defaults to the entry's runId
+ *                   /jobId composite); kept for symmetry with
+ *                   `shouldRecordAccess`.
+ */
+export interface SecretResolveSampleInput {
+    outcome: 'allowed' | 'denied';
+    runId: string | null;
+    jobId: string | null;
+    userId: string | null;
+    role: string | null;
+}
+export declare function shouldRecordSecretResolve(entry: SecretResolveSampleInput): boolean;
+//# sourceMappingURL=access-log-policy.d.ts.map

package/dist/audit/access-log-policy.js

@@ -0,0 +1,195 @@
+import "../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/audit/access-log-policy.ts
+/**
+* Per-action access-log policy + sampling helper.
+*
+* Single source of truth for the keep / sample / rate-limit decision used by
+* the orchestrator's `access_log` writer. The policy table is exhaustive
+* over `AccessLogAction.options` so a new enum value without a policy entry
+* is a compile-time error.
+*
+* Override layers (applied in `shouldRecordAccess`, in order):
+*
+* 1. `outcome !== 'allowed'` → always record (denied/error are full-fidelity).
+* 2. `actor.type === 'platform_operator'` → always record (compliance: any
+*    activity by a non-org member must be auditable in full).
+* 3. The per-action `POLICY_BY_ACTION` decision (`always` / `sample` /
+*    `rate_limit`).
+*
+* Browser-safe: this module MUST NOT import any Node built-ins (`node:crypto`
+* etc.). It is re-exported via the `@kici-dev/engine` barrel which the
+* dashboard imports. Sampling uses a tiny inline FNV-1a 32-bit hash.
+*/
+/** Discriminator for the per-action policy entry. */
+const AccessLogPolicyKind = z.enum([
+	"always",
+	"sample",
+	"rate_limit"
+]);
+/**
+* Policy table mirroring research-doc §2 verdicts (with the user's
+* §7 platform-operator override applied separately in `shouldRecordAccess`).
+*
+* Exhaustive over `AccessLogAction.options` — TypeScript catches additions.
+*/
+const POLICY_BY_ACTION = {
+	"run.detail.read": {
+		kind: "sample",
+		allowedRate: .05
+	},
+	"run.orch_logs.read": {
+		kind: "sample",
+		allowedRate: .1
+	},
+	"step.logs.read": {
+		kind: "sample",
+		allowedRate: .1
+	},
+	"event_log.list.read": {
+		kind: "sample",
+		allowedRate: .05
+	},
+	"environment.list.read": {
+		kind: "sample",
+		allowedRate: .1
+	},
+	"registration.list.read": {
+		kind: "sample",
+		allowedRate: .1
+	},
+	"global_workflows.get.read": {
+		kind: "sample",
+		allowedRate: .1
+	},
+	"environment.get.read": {
+		kind: "sample",
+		allowedRate: .2
+	},
+	"environment.history.read": {
+		kind: "sample",
+		allowedRate: .2
+	},
+	"held_run.list.read": {
+		kind: "sample",
+		allowedRate: .2
+	},
+	"env_binding.list.read": {
+		kind: "sample",
+		allowedRate: .2
+	},
+	"backend.list.read": {
+		kind: "sample",
+		allowedRate: .2
+	},
+	"backend.get.read": {
+		kind: "sample",
+		allowedRate: .2
+	},
+	"diagnostics.read": {
+		kind: "rate_limit",
+		perMinutePerActor: 1
+	},
+	"scaler.capacity.read": {
+		kind: "rate_limit",
+		perMinutePerActor: 1
+	},
+	"scaler.agents.read": {
+		kind: "rate_limit",
+		perMinutePerActor: 1
+	},
+	"run.payload.read": { kind: "always" },
+	"run.cancel": { kind: "always" },
+	"run.rerun": { kind: "always" },
+	"run.manual_schedule": { kind: "always" },
+	"job.cancel": { kind: "always" },
+	"event_log.detail.read": { kind: "always" },
+	"event_log.payload.read": { kind: "always" },
+	"environment.create": { kind: "always" },
+	"environment.update": { kind: "always" },
+	"environment.delete": { kind: "always" },
+	"env_var.list.read": { kind: "always" },
+	"env_var.set": { kind: "always" },
+	"env_var.delete": { kind: "always" },
+	"source_override.list.read": { kind: "always" },
+	"source_override.set": { kind: "always" },
+	"source_override.delete": { kind: "always" },
+	"env_binding.set": { kind: "always" },
+	"secret.list.read": { kind: "always" },
+	"secret.set": { kind: "always" },
+	"secret.delete": { kind: "always" },
+	"secret.reveal": { kind: "always" },
+	"secret_scope.create": { kind: "always" },
+	"secret_scope.rename": { kind: "always" },
+	"secret_scope.delete": { kind: "always" },
+	"held_run.approve": { kind: "always" },
+	"held_run.reject": { kind: "always" },
+	"registration.disable": { kind: "always" },
+	"registration.delete": { kind: "always" },
+	"backend.sync": { kind: "always" },
+	"backend.sync.one": { kind: "always" },
+	"backend.test": { kind: "always" },
+	"global_workflows.update": { kind: "always" },
+	"access_log.list.read": { kind: "always" },
+	"event_dlq.list.read": {
+		kind: "sample",
+		allowedRate: .2
+	},
+	"event_dlq.retry": { kind: "always" },
+	"event_dlq.discard": { kind: "always" },
+	archive_chunk: { kind: "always" }
+};
+/**
+* Tiny FNV-1a 32-bit hash. Used for stable hash-based sampling so a single
+* actor's request stream lands in the same sampling bucket repeatedly.
+*
+* Pure JS, no Node built-ins (engine barrel must stay browser-safe).
+*/
+function fnv1a32(input) {
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i) & 255;
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+}
+/** Build a stable cache / sampler key from the actor's flattened identity. */
+function actorKey(actor) {
+	switch (actor.type) {
+		case "user": return `user:${actor.sub}`;
+		case "api_key": return `api_key:${actor.keyId}`;
+		case "service_account": return `service_account:${actor.id}`;
+		case "platform_operator": return `platform_operator:${actor.sub}`;
+		case "system": return `system:${actor.component}`;
+	}
+}
+/**
+* Decide whether to write an `access_log` row for the given action.
+*
+* @param action     The action being attempted.
+* @param outcome    `allowed` / `denied` / `error`.
+* @param actor      The principal performing the action.
+* @param requestId  The orchestrator request id (used for stable sampling).
+* @param limiter    Rate-limiter instance (only consulted for `rate_limit`
+*                   actions; tests can pass a stub).
+*
+* Returns `true` to write the row, `false` to drop.
+*/
+function shouldRecordAccess(action, outcome, actor, requestId, limiter) {
+	if (outcome !== "allowed") return true;
+	if (actor.type === "platform_operator") return true;
+	const policy = POLICY_BY_ACTION[action];
+	switch (policy.kind) {
+		case "always": return true;
+		case "sample": return fnv1a32(`${actorKey(actor)}|${requestId ?? ""}`) / 4294967296 < policy.allowedRate;
+		case "rate_limit": return limiter.permit(action, actorKey(actor), policy.perMinutePerActor);
+	}
+}
+function shouldRecordSecretResolve(entry) {
+	if (entry.outcome !== "allowed") return true;
+	return fnv1a32(`system:${entry.runId ?? entry.jobId ?? entry.userId ?? "unknown"}`) / 4294967296 < .01;
+}
+//#endregion
+export { AccessLogPolicyKind, POLICY_BY_ACTION, fnv1a32, shouldRecordAccess, shouldRecordSecretResolve };
+
+//# sourceMappingURL=access-log-policy.js.map

package/dist/audit/activity.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Unified Activity row + filter schemas for the dashboard's federated
+ * "Activity" view. Federates Platform `audit_log` (mutation events,
+ * free-form target_type) with orchestrator `access_log` (reads + admin
+ * mutations, strict-enum target_type) at the query layer — see plan
+ * `~/.claude/plans/ui-audit-logs-page-sleepy-wave.md`.
+ *
+ * The `source` discriminator on each row tells the UI whether to render
+ * the audit_log or access_log column set. Fields unique to access_log
+ * (origin, requestId, outcome) are nullable so audit_log rows stay
+ * shape-compatible without padding.
+ *
+ * Browser-safe: only Zod imports + base64 helpers via globalThis.btoa/atob
+ * (available in Node 18+ and all evergreen browsers). No Node built-ins.
+ */
+import { z } from 'zod';
+/**
+ * Source discriminator on a unified Activity row.
+ * NOT to be confused with `AccessLogSource` (platform_proxy / admin_http /
+ * admin_cli) — that field is renamed to `origin` on the unified row to
+ * avoid the collision.
+ */
+export declare const ActivityRowSource: z.ZodEnum<{
+    access_log: "access_log";
+    audit_log: "audit_log";
+}>;
+export type ActivityRowSource = z.infer<typeof ActivityRowSource>;
+/**
+ * `source` filter parameter on /activity. `all` is the default and means
+ * "federate both streams"; the other values restrict to a single stream.
+ */
+export declare const ActivityFilterSource: z.ZodEnum<{
+    access_log: "access_log";
+    audit_log: "audit_log";
+    all: "all";
+}>;
+export type ActivityFilterSource = z.infer<typeof ActivityFilterSource>;
+/**
+ * Unified row shape returned by GET /orgs/:customerId/activity.
+ *
+ * - audit_log rows: outcome=null, errorMessage=null, requestId=undefined,
+ *   origin=undefined. target_type/target_id are free-form strings.
+ * - access_log rows: outcome populated, errorMessage may be set on
+ *   denied/error, requestId/origin populated.
+ */
+export declare const activityRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodEnum<{
+        access_log: "access_log";
+        audit_log: "audit_log";
+    }>;
+    createdAt: z.ZodString;
+    actorType: z.ZodEnum<{
+        user: "user";
+        api_key: "api_key";
+        service_account: "service_account";
+        platform_operator: "platform_operator";
+        system: "system";
+    }>;
+    actorId: z.ZodString;
+    actorMeta: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    actorEmail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    actorDisplayName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    action: z.ZodString;
+    targetType: z.ZodNullable<z.ZodString>;
+    targetId: z.ZodNullable<z.ZodString>;
+    outcome: z.ZodNullable<z.ZodEnum<{
+        error: "error";
+        allowed: "allowed";
+        denied: "denied";
+    }>>;
+    errorMessage: z.ZodNullable<z.ZodString>;
+    details: z.ZodNullable<z.ZodUnknown>;
+    requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    origin: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        platform_proxy: "platform_proxy";
+        admin_http: "admin_http";
+        admin_cli: "admin_cli";
+    }>>>;
+}, z.core.$strip>;
+export type ActivityRow = z.infer<typeof activityRowSchema>;
+/**
+ * Unified filter schema accepted by GET /orgs/:customerId/activity.
+ * Captures every filter the existing CLI commands expose, plus the new
+ * search features (runId sugar, full-text q).
+ */
+export declare const activityFilterSchema: z.ZodObject<{
+    source: z.ZodDefault<z.ZodEnum<{
+        access_log: "access_log";
+        audit_log: "audit_log";
+        all: "all";
+    }>>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        user: "user";
+        api_key: "api_key";
+        service_account: "service_account";
+        platform_operator: "platform_operator";
+        system: "system";
+    }>>;
+    actorId: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        allowed: "allowed";
+        denied: "denied";
+    }>>;
+    origin: z.ZodOptional<z.ZodEnum<{
+        platform_proxy: "platform_proxy";
+        admin_http: "admin_http";
+        admin_cli: "admin_cli";
+    }>>;
+    targetType: z.ZodOptional<z.ZodString>;
+    targetId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    q: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type ActivityFilter = z.infer<typeof activityFilterSchema>;
+/**
+ * Internal cursor shape — preserves both halves of the federated
+ * pagination state. `null` for either half means that source is exhausted
+ * and should not be re-queried on the next page.
+ *
+ * Encoded as base64url(JSON) to keep it opaque-looking and URL-safe.
+ */
+export declare const activityCursorSchema: z.ZodObject<{
+    audit: z.ZodNullable<z.ZodObject<{
+        offset: z.ZodNumber;
+    }, z.core.$strip>>;
+    access: z.ZodNullable<z.ZodObject<{
+        inner: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ActivityCursor = z.infer<typeof activityCursorSchema>;
+/**
+ * Encode a cursor for the federated /activity endpoint. Returns a
+ * URL-safe opaque string suitable for the `cursor` query param.
+ */
+export declare function encodeActivityCursor(cursor: ActivityCursor): string;
+/**
+ * Decode an opaque cursor string. Returns `null` when the input is
+ * malformed (corrupted base64, invalid JSON, or schema mismatch). Callers
+ * should treat null as "start from page zero" rather than 500ing.
+ */
+export declare function decodeActivityCursor(cursor: string): ActivityCursor | null;
+/**
+ * Apply the runId sugar: when `runId` is set on the filter, it is mapped
+ * to (targetType='run', targetId=runId) for both halves of the
+ * federation. Returns a new filter with runId resolved into the explicit
+ * target fields; existing target* fields take precedence if both are set.
+ */
+export declare function resolveRunIdSugar(filter: ActivityFilter): ActivityFilter;
+//# sourceMappingURL=activity.d.ts.map

package/dist/audit/activity.js

@@ -0,0 +1,175 @@
+import "../chunk-gOLHoazu.js";
+import { ActorType } from "../protocol/messages/actor.js";
+import { AccessLogOutcome } from "../protocol/messages/access-log.js";
+import { z } from "zod";
+//#region src/audit/activity.ts
+/**
+* Unified Activity row + filter schemas for the dashboard's federated
+* "Activity" view. Federates Platform `audit_log` (mutation events,
+* free-form target_type) with orchestrator `access_log` (reads + admin
+* mutations, strict-enum target_type) at the query layer — see plan
+* `~/.claude/plans/ui-audit-logs-page-sleepy-wave.md`.
+*
+* The `source` discriminator on each row tells the UI whether to render
+* the audit_log or access_log column set. Fields unique to access_log
+* (origin, requestId, outcome) are nullable so audit_log rows stay
+* shape-compatible without padding.
+*
+* Browser-safe: only Zod imports + base64 helpers via globalThis.btoa/atob
+* (available in Node 18+ and all evergreen browsers). No Node built-ins.
+*/
+/**
+* Source discriminator on a unified Activity row.
+* NOT to be confused with `AccessLogSource` (platform_proxy / admin_http /
+* admin_cli) — that field is renamed to `origin` on the unified row to
+* avoid the collision.
+*/
+const ActivityRowSource = z.enum(["audit_log", "access_log"]);
+/**
+* `source` filter parameter on /activity. `all` is the default and means
+* "federate both streams"; the other values restrict to a single stream.
+*/
+const ActivityFilterSource = z.enum([
+	"audit_log",
+	"access_log",
+	"all"
+]);
+/**
+* Unified row shape returned by GET /orgs/:customerId/activity.
+*
+* - audit_log rows: outcome=null, errorMessage=null, requestId=undefined,
+*   origin=undefined. target_type/target_id are free-form strings.
+* - access_log rows: outcome populated, errorMessage may be set on
+*   denied/error, requestId/origin populated.
+*/
+const activityRowSchema = z.object({
+	id: z.string(),
+	source: ActivityRowSource,
+	/** Merge key (createdAt DESC). ISO 8601. */
+	createdAt: z.string(),
+	/** Resolved actor identity. Display fields populated for user / platform_operator actors. */
+	actorType: ActorType,
+	actorId: z.string(),
+	actorMeta: z.record(z.string(), z.unknown()).nullable(),
+	actorEmail: z.string().nullable().optional(),
+	actorDisplayName: z.string().nullable().optional(),
+	/** Free-form on audit_log; AccessLogAction-shaped on access_log. */
+	action: z.string(),
+	/** Free-form string on audit_log (e.g. "member"); enum-bounded on access_log. */
+	targetType: z.string().nullable(),
+	targetId: z.string().nullable(),
+	/** access_log only; null on audit_log (audit_log has no outcome concept). */
+	outcome: AccessLogOutcome.nullable(),
+	/** access_log only; surfaces denied-reason and error text. */
+	errorMessage: z.string().nullable(),
+	/**
+	* audit_log: jsonb `details` column (field changes etc.).
+	* access_log: not populated by the federation (per-row metadata is in
+	* actorMeta); kept on the schema so the row shape is uniform.
+	*/
+	details: z.unknown().nullable(),
+	/** access_log only — request correlation ID. */
+	requestId: z.string().nullable().optional(),
+	/**
+	* access_log only — origin of the entry (platform_proxy / admin_http /
+	* admin_cli). Renamed from `source` on the access_log row schema so the
+	* unified row's `source` field is unambiguously the audit_log vs.
+	* access_log discriminator.
+	*/
+	origin: z.enum([
+		"platform_proxy",
+		"admin_http",
+		"admin_cli"
+	]).nullable().optional()
+});
+/**
+* Unified filter schema accepted by GET /orgs/:customerId/activity.
+* Captures every filter the existing CLI commands expose, plus the new
+* search features (runId sugar, full-text q).
+*/
+const activityFilterSchema = z.object({
+	source: ActivityFilterSource.default("all"),
+	actorType: ActorType.optional(),
+	actorId: z.string().optional(),
+	/** Free-form: matches access_log AccessLogAction values OR audit_log free-form actions. */
+	action: z.string().optional(),
+	outcome: AccessLogOutcome.optional(),
+	origin: z.enum([
+		"platform_proxy",
+		"admin_http",
+		"admin_cli"
+	]).optional(),
+	targetType: z.string().optional(),
+	targetId: z.string().optional(),
+	/** Sugar: maps to targetType='run' + targetId=runId. Both halves of the federation respect it. */
+	runId: z.string().optional(),
+	/** Full-text search over access_log.error_message and audit_log.details::text. */
+	q: z.string().optional(),
+	/** ISO timestamp lower bound (inclusive). */
+	from: z.string().optional(),
+	/** ISO timestamp upper bound (exclusive). */
+	to: z.string().optional(),
+	/** Opaque cursor produced by encodeActivityCursor(). */
+	cursor: z.string().optional(),
+	limit: z.coerce.number().int().min(1).max(200).default(50)
+});
+/**
+* Internal cursor shape — preserves both halves of the federated
+* pagination state. `null` for either half means that source is exhausted
+* and should not be re-queried on the next page.
+*
+* Encoded as base64url(JSON) to keep it opaque-looking and URL-safe.
+*/
+const activityCursorSchema = z.object({
+	audit: z.object({ offset: z.number().int().nonnegative() }).nullable(),
+	access: z.object({ 
+	/** Inner cursor returned by the orchestrator's dashboard.access-log.list response. */
+inner: z.string() }).nullable()
+});
+function base64UrlEncode(s) {
+	return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(s) {
+	const pad = (4 - s.length % 4) % 4;
+	const padded = (s + "=".repeat(pad)).replace(/-/g, "+").replace(/_/g, "/");
+	return atob(padded);
+}
+/**
+* Encode a cursor for the federated /activity endpoint. Returns a
+* URL-safe opaque string suitable for the `cursor` query param.
+*/
+function encodeActivityCursor(cursor) {
+	return base64UrlEncode(JSON.stringify(cursor));
+}
+/**
+* Decode an opaque cursor string. Returns `null` when the input is
+* malformed (corrupted base64, invalid JSON, or schema mismatch). Callers
+* should treat null as "start from page zero" rather than 500ing.
+*/
+function decodeActivityCursor(cursor) {
+	try {
+		const json = base64UrlDecode(cursor);
+		const parsed = activityCursorSchema.safeParse(JSON.parse(json));
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Apply the runId sugar: when `runId` is set on the filter, it is mapped
+* to (targetType='run', targetId=runId) for both halves of the
+* federation. Returns a new filter with runId resolved into the explicit
+* target fields; existing target* fields take precedence if both are set.
+*/
+function resolveRunIdSugar(filter) {
+	if (!filter.runId) return filter;
+	return {
+		...filter,
+		targetType: filter.targetType ?? "run",
+		targetId: filter.targetId ?? filter.runId
+	};
+}
+//#endregion
+export { ActivityFilterSource, ActivityRowSource, activityCursorSchema, activityFilterSchema, activityRowSchema, decodeActivityCursor, encodeActivityCursor, resolveRunIdSugar };
+
+//# sourceMappingURL=activity.js.map