@learncard/network-brain-service 3.18.0 → 3.19.1

package/src/helpers/share-link-lifecycle/types.ts

@@ -0,0 +1,58 @@
+/**
+ * LC-2187 share-link lifecycle constants and literals.
+ *
+ * This module is intentionally storage- and transport-agnostic: routes, the
+ * LearnCloud client and the reconciliation worker all derive their bounds from
+ * here so the Brain repository and the tests agree on one set of numbers.
+ */
+
+/** Operation kinds that are bound to an idempotency record. */
+export type ShareLinkOperationKind = 'create' | 'update' | 'revoke';
+
+export const SHARE_LINK_OPERATION_KINDS: readonly ShareLinkOperationKind[] = [
+    'create',
+    'update',
+    'revoke',
+];
+
+/**
+ * Default bounded lease for one in-flight share content operation. A worker that
+ * cannot finish staging + finalize within the lease loses its fence and must not
+ * commit; a later reservation supersedes it with a higher generation.
+ */
+export const SHARE_LINK_DEFAULT_LEASE_MS = 2 * 60 * 1000;
+
+/**
+ * Retain completed operation records for 30 days.
+ *
+ * Pruning is an explicit operator action, not an automatic replay path. After a
+ * record is pruned, object-reference uniqueness, the share version compare-and-set
+ * and the `stopped` terminal state still prevent a replay from overwriting newer
+ * content.
+ */
+export const SHARE_LINK_OPERATION_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Cleanup retry backoff bounds (exponential, capped). */
+export const SHARE_LINK_CLEANUP_BASE_BACKOFF_MS = 30 * 1000;
+export const SHARE_LINK_CLEANUP_MAX_BACKOFF_MS = 24 * 60 * 60 * 1000;
+
+/** Default cap on cleanup jobs claimed in one bounded batch. */
+export const SHARE_LINK_CLEANUP_DEFAULT_BATCH = 25;
+export const SHARE_LINK_CLEANUP_MAX_BATCH = 100;
+
+/** Default lease for a claimed cleanup job. */
+export const SHARE_LINK_CLEANUP_DEFAULT_CLAIM_MS = 5 * 60 * 1000;
+
+/**
+ * Hard bounds for a caller-supplied cleanup claim lease. A configured
+ * maintenance lease is clamped into this window so a bad deployment cannot hold
+ * (or instantly drop) work; the repository default is unchanged.
+ */
+export const SHARE_LINK_CLEANUP_MIN_CLAIM_MS = 1_000;
+export const SHARE_LINK_CLEANUP_MAX_CLAIM_MS = 30 * 60 * 1000;
+
+/** Reasons a durable cleanup job can be created. */
+export type ShareContentCleanupReason = 'superseded' | 'abandoned' | 'stopped';
+
+/** Lifecycle status of a durable cleanup job. */
+export type ShareContentCleanupStatus = 'queued' | 'claimed' | 'completed';

package/src/helpers/share-link-maintenance/budget.ts

@@ -0,0 +1,63 @@
+import type { MaintenanceBudget } from '../share-link-coordinator';
+
+/**
+ * Monotonic wall-clock budget for one maintenance pass.
+ *
+ * The runner checks `exhausted()` before each claim; once the remaining time is
+ * at or below `finalizeReserveMs` it must stop starting new graph/remote work so
+ * the pass can still log and return a summary. This is a cooperative deadline,
+ * not a hard kill: it never uses `Promise.race`, which would leave an untracked
+ * mutation running after the pass returned.
+ */
+export type MaintenancePassBudget = MaintenanceBudget & {
+    elapsedMs: () => number;
+    configuredMs: number;
+};
+
+const defaultMonotonicNow = (): number =>
+    typeof performance !== 'undefined' && typeof performance.now === 'function'
+        ? performance.now()
+        : Date.now();
+
+/**
+ * Resolve the pass budget from a Lambda remaining-time value.
+ *
+ * `undefined` means "no Lambda signal" and keeps the configured budget. Any
+ * other value failing the finite/positive check — NaN, Infinity, negative or
+ * zero — fails closed to a zero budget so the pass does no work.
+ */
+export const resolveMaintenanceBudgetMs = (
+    configuredBudgetMs: number,
+    remainingTimeMs: number | undefined
+): number => {
+    if (remainingTimeMs === undefined) return configuredBudgetMs;
+    if (!Number.isFinite(remainingTimeMs) || remainingTimeMs <= 0) return 0;
+
+    return Math.min(configuredBudgetMs, Math.trunc(remainingTimeMs));
+};
+
+export const createMaintenancePassBudget = (input: {
+    budgetMs: number;
+    finalizeReserveMs: number;
+    monotonicNow?: () => number;
+}): MaintenancePassBudget => {
+    const monotonicNow = input.monotonicNow ?? defaultMonotonicNow;
+    const configuredMs = Number.isFinite(input.budgetMs)
+        ? Math.max(0, Math.trunc(input.budgetMs))
+        : 0;
+    const reserveMs = Number.isFinite(input.finalizeReserveMs)
+        ? Math.max(0, Math.trunc(input.finalizeReserveMs))
+        : 0;
+    const startedAt = monotonicNow();
+    const deadline = startedAt + configuredMs;
+
+    const remainingMs = (): number => deadline - monotonicNow();
+
+    return {
+        configuredMs,
+        elapsedMs: () => monotonicNow() - startedAt,
+        remainingMs,
+        reserveMs: () => reserveMs,
+        exhausted: () => remainingMs() <= reserveMs,
+    };
+};

package/src/helpers/share-link-maintenance/config.ts

@@ -0,0 +1,312 @@
+import {
+    SHARE_LINK_CLEANUP_DEFAULT_BATCH,
+    SHARE_LINK_CLEANUP_DEFAULT_CLAIM_MS,
+    SHARE_LINK_CLEANUP_MAX_BATCH,
+    SHARE_LINK_CLEANUP_MAX_CLAIM_MS,
+    SHARE_LINK_CLEANUP_MIN_CLAIM_MS,
+    SHARE_LINK_DEFAULT_LEASE_MS,
+} from '../share-link-lifecycle';
+import {
+    SHARE_LINK_RECOVERY_DEFAULT_BATCH,
+    SHARE_LINK_RECOVERY_MAX_BATCH,
+} from '../share-link-lifecycle/recovery.helpers';
+import { validateShareContentOrigin } from '../share-content-client/config';
+import type { ShareLinkMaintenanceConfig, ShareLinkMaintenanceConfigResolution } from './types';
+
+/**
+ * Operator-facing configuration for the automatic share-link maintenance pass.
+ *
+ * Every value is read and validated here rather than in the global environment
+ * schema so malformed maintenance settings fail closed to a fixed category
+ * instead of preventing the whole Brain service from booting. Absent or
+ * invalid configuration must perform no graph or remote I/O and must not
+ * initialize a signer.
+ */
+
+export const SHARE_LINK_MAINTENANCE_ENV = {
+    NAMESPACE: 'SHARE_LINK_MAINTENANCE_NAMESPACE',
+    ORIGIN: 'SHARE_LINK_MAINTENANCE_ORIGIN',
+    AUDIENCE: 'SHARE_LINK_MAINTENANCE_AUDIENCE',
+    ALLOW_INSECURE_LOOPBACK: 'SHARE_LINK_MAINTENANCE_ALLOW_INSECURE_LOOPBACK',
+    CLAIMANT: 'SHARE_LINK_MAINTENANCE_CLAIMANT',
+    RECOVERY_LIMIT: 'SHARE_LINK_MAINTENANCE_RECOVERY_LIMIT',
+    CLEANUP_LIMIT: 'SHARE_LINK_MAINTENANCE_CLEANUP_LIMIT',
+    RECEIPT_PRUNE_LIMIT: 'SHARE_LINK_MAINTENANCE_RECEIPT_PRUNE_LIMIT',
+    LEASE_MS: 'SHARE_LINK_MAINTENANCE_LEASE_MS',
+    CLAIM_MS: 'SHARE_LINK_MAINTENANCE_CLAIM_MS',
+    BUDGET_MS: 'SHARE_LINK_MAINTENANCE_BUDGET_MS',
+    INTERVAL_MS: 'SHARE_LINK_MAINTENANCE_INTERVAL_MS',
+    REQUEST_TIMEOUT_MS: 'SHARE_LINK_MAINTENANCE_REQUEST_TIMEOUT_MS',
+    FINALIZE_RESERVE_MS: 'SHARE_LINK_MAINTENANCE_FINALIZE_RESERVE_MS',
+    GRAPH_TIMEOUT_MS: 'SHARE_LINK_MAINTENANCE_GRAPH_TIMEOUT_MS',
+} as const;
+
+export const SHARE_LINK_MAINTENANCE_DEFAULTS = Object.freeze({
+    claimant: 'brain-share-link-maintenance',
+    recoveryLimit: SHARE_LINK_RECOVERY_DEFAULT_BATCH,
+    cleanupLimit: SHARE_LINK_CLEANUP_DEFAULT_BATCH,
+    receiptPruneLimit: 200,
+    leaseMs: SHARE_LINK_DEFAULT_LEASE_MS,
+    claimMs: SHARE_LINK_CLEANUP_DEFAULT_CLAIM_MS,
+    budgetMs: 60_000,
+    intervalMs: 300_000,
+    requestTimeoutMs: 10_000,
+    finalizeReserveMs: 5_000,
+    graphTimeoutMs: 15_000,
+});
+
+export const SHARE_LINK_MAINTENANCE_INVALID_CATEGORY =
+    'share_link_maintenance_configuration_invalid' as const;
+
+/**
+ * Transport/service-client portion of the share-content configuration.
+ *
+ * Owner/public APIs and maintenance use the same validated namespace, origin,
+ * and audience. No backend rollout flag is required.
+ */
+export type ShareLinkServiceTransportConfig = {
+    namespace: string;
+    origin: string;
+    audience: string;
+    allowInsecureLoopback: boolean;
+};
+
+export type ShareLinkServiceTransportConfigResolution =
+    { status: 'enabled'; config: ShareLinkServiceTransportConfig } | { status: 'invalid' };
+
+/** Whether any required service wiring has been supplied (empty deployment defaults are absent). */
+export const hasShareLinkServiceTransportConfig = (source: Record<string, unknown>): boolean =>
+    [
+        SHARE_LINK_MAINTENANCE_ENV.NAMESPACE,
+        SHARE_LINK_MAINTENANCE_ENV.ORIGIN,
+        SHARE_LINK_MAINTENANCE_ENV.AUDIENCE,
+    ].some(key => source[key] !== undefined && source[key] !== null && source[key] !== '');
+
+/**
+ * Validate service-client transport fields without echoing values or exceptions.
+ */
+export const resolveShareLinkServiceTransportConfig = (
+    raw: unknown
+): ShareLinkServiceTransportConfigResolution => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { status: 'invalid' };
+    }
+
+    const source = raw as Record<string, unknown>;
+    const allowInsecureLoopback = parseDeliberateBoolean(
+        source[SHARE_LINK_MAINTENANCE_ENV.ALLOW_INSECURE_LOOPBACK]
+    );
+    if (allowInsecureLoopback === null) return { status: 'invalid' };
+    const insecureLoopbackAllowed = allowInsecureLoopback === true;
+
+    const origin = validateShareContentOrigin(
+        source[SHARE_LINK_MAINTENANCE_ENV.ORIGIN],
+        insecureLoopbackAllowed
+    );
+    if (!origin.ok) return { status: 'invalid' };
+
+    const namespace = source[SHARE_LINK_MAINTENANCE_ENV.NAMESPACE];
+    if (!isOpaqueIdentifier(namespace)) return { status: 'invalid' };
+
+    const audience = source[SHARE_LINK_MAINTENANCE_ENV.AUDIENCE];
+    if (typeof audience !== 'string' || !audience.startsWith('did:')) {
+        return { status: 'invalid' };
+    }
+
+    return {
+        status: 'enabled',
+        config: {
+            namespace,
+            origin: origin.origin,
+            audience,
+            allowInsecureLoopback: insecureLoopbackAllowed,
+        },
+    };
+};
+
+const OPAQUE_IDENTIFIER_RE = /^[A-Za-z0-9._~-]+$/;
+
+const isOpaqueIdentifier = (value: unknown, maxLength = 128): value is string =>
+    typeof value === 'string' &&
+    value.length >= 1 &&
+    value.length <= maxLength &&
+    OPAQUE_IDENTIFIER_RE.test(value);
+
+const MISSING = Symbol('missing');
+
+/** Deliberate boolean parse: only booleans and the exact strings true/false. */
+const parseDeliberateBoolean = (value: unknown): boolean | typeof MISSING | null => {
+    if (value === undefined || value === null || value === '') return MISSING;
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'true') return true;
+        if (normalized === 'false') return false;
+    }
+
+    return null;
+};
+
+type BoundedIntegerOptions = { minimum: number; maximum: number; fallback: number };
+
+const parseBoundedInteger = (
+    value: unknown,
+    options: BoundedIntegerOptions
+): number | typeof MISSING | null => {
+    if (value === undefined || value === null || value === '') return MISSING;
+
+    let parsed: number;
+    if (typeof value === 'number') parsed = value;
+    else if (typeof value === 'string' && /^[0-9]+$/.test(value.trim()))
+        parsed = Number(value.trim());
+    else return null;
+
+    if (!Number.isSafeInteger(parsed) || parsed < options.minimum || parsed > options.maximum)
+        return null;
+
+    return parsed;
+};
+
+const invalid = (): ShareLinkMaintenanceConfigResolution => ({
+    status: 'invalid',
+    category: SHARE_LINK_MAINTENANCE_INVALID_CATEGORY,
+});
+
+/**
+ * Resolve maintenance configuration from a raw record (typically `process.env`).
+ * Never throws and never echoes a value.
+ */
+export const resolveShareLinkMaintenanceConfig = (
+    raw: unknown
+): ShareLinkMaintenanceConfigResolution => {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return invalid();
+
+    const source = raw as Record<string, unknown>;
+    if (!hasShareLinkServiceTransportConfig(source)) return { status: 'disabled' };
+
+    const transport = resolveShareLinkServiceTransportConfig(source);
+    if (transport.status !== 'enabled') return invalid();
+
+    const { namespace, origin, audience, allowInsecureLoopback } = transport.config;
+
+    const claimantValue = source[SHARE_LINK_MAINTENANCE_ENV.CLAIMANT];
+    const claimant =
+        claimantValue === undefined || claimantValue === ''
+            ? SHARE_LINK_MAINTENANCE_DEFAULTS.claimant
+            : claimantValue;
+    if (!isOpaqueIdentifier(claimant)) return invalid();
+
+    const numericFields: Array<[string, BoundedIntegerOptions]> = [
+        [
+            SHARE_LINK_MAINTENANCE_ENV.RECOVERY_LIMIT,
+            {
+                minimum: 1,
+                maximum: SHARE_LINK_RECOVERY_MAX_BATCH,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.recoveryLimit,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.CLEANUP_LIMIT,
+            {
+                minimum: 1,
+                maximum: SHARE_LINK_CLEANUP_MAX_BATCH,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.cleanupLimit,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.RECEIPT_PRUNE_LIMIT,
+            {
+                minimum: 1,
+                maximum: 1_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.receiptPruneLimit,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.LEASE_MS,
+            {
+                minimum: 1_000,
+                maximum: 30 * 60 * 1000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.leaseMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.CLAIM_MS,
+            {
+                minimum: SHARE_LINK_CLEANUP_MIN_CLAIM_MS,
+                maximum: SHARE_LINK_CLEANUP_MAX_CLAIM_MS,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.claimMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.BUDGET_MS,
+            {
+                minimum: 1_000,
+                maximum: 240_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.budgetMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.INTERVAL_MS,
+            {
+                minimum: 1_000,
+                maximum: 60 * 60 * 1000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.intervalMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.REQUEST_TIMEOUT_MS,
+            {
+                minimum: 100,
+                maximum: 30_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.requestTimeoutMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.FINALIZE_RESERVE_MS,
+            {
+                minimum: 100,
+                maximum: 120_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.finalizeReserveMs,
+            },
+        ],
+        [
+            SHARE_LINK_MAINTENANCE_ENV.GRAPH_TIMEOUT_MS,
+            {
+                minimum: 100,
+                maximum: 120_000,
+                fallback: SHARE_LINK_MAINTENANCE_DEFAULTS.graphTimeoutMs,
+            },
+        ],
+    ];
+
+    const resolved: Record<string, number> = {};
+    for (const [key, options] of numericFields) {
+        const parsed = parseBoundedInteger(source[key], options);
+        if (parsed === null) return invalid();
+        resolved[key] = parsed === MISSING ? options.fallback : parsed;
+    }
+
+    const budgetMs = resolved[SHARE_LINK_MAINTENANCE_ENV.BUDGET_MS] as number;
+    const finalizeReserveMs = resolved[SHARE_LINK_MAINTENANCE_ENV.FINALIZE_RESERVE_MS] as number;
+    if (finalizeReserveMs >= budgetMs) return invalid();
+
+    const config: ShareLinkMaintenanceConfig = {
+        namespace,
+        origin,
+        audience,
+        allowInsecureLoopback,
+        claimant,
+        recoveryLimit: resolved[SHARE_LINK_MAINTENANCE_ENV.RECOVERY_LIMIT] as number,
+        cleanupLimit: resolved[SHARE_LINK_MAINTENANCE_ENV.CLEANUP_LIMIT] as number,
+        receiptPruneLimit: resolved[SHARE_LINK_MAINTENANCE_ENV.RECEIPT_PRUNE_LIMIT] as number,
+        leaseMs: resolved[SHARE_LINK_MAINTENANCE_ENV.LEASE_MS] as number,
+        claimMs: resolved[SHARE_LINK_MAINTENANCE_ENV.CLAIM_MS] as number,
+        budgetMs,
+        intervalMs: resolved[SHARE_LINK_MAINTENANCE_ENV.INTERVAL_MS] as number,
+        requestTimeoutMs: resolved[SHARE_LINK_MAINTENANCE_ENV.REQUEST_TIMEOUT_MS] as number,
+        finalizeReserveMs,
+        graphTimeoutMs: resolved[SHARE_LINK_MAINTENANCE_ENV.GRAPH_TIMEOUT_MS] as number,
+    };
+
+    return { status: 'enabled', config };
+};

package/src/helpers/share-link-maintenance/index.ts

@@ -0,0 +1,24 @@
+export * from './types';
+export {
+    SHARE_LINK_MAINTENANCE_DEFAULTS,
+    SHARE_LINK_MAINTENANCE_ENV,
+    SHARE_LINK_MAINTENANCE_INVALID_CATEGORY,
+    resolveShareLinkMaintenanceConfig,
+} from './config';
+export { createMaintenancePassBudget, type MaintenancePassBudget } from './budget';
+export {
+    createConsoleMaintenanceLogger,
+    safeLogMaintenance,
+    toMaintenanceLogEvent,
+} from './telemetry';
+export { runShareLinkMaintenancePass, type ShareLinkMaintenanceRunnerDependencies } from './runner';
+export {
+    createShareLinkMaintenanceScheduler,
+    type ShareLinkMaintenanceScheduler,
+    type ShareLinkMaintenanceSchedulerDependencies,
+} from './scheduler';
+export {
+    createShareLinkMaintenanceRuntime,
+    type CreateShareLinkMaintenanceRuntimeOptions,
+    type ShareLinkMaintenanceRuntime,
+} from './runtime';

package/src/helpers/share-link-maintenance/runner.ts

@@ -0,0 +1,223 @@
+import type {
+    CleanupRunnerDependencies,
+    RecoveryRunnerDependencies,
+} from '../share-link-coordinator';
+import { runShareContentCleanupOnce } from '../share-link-coordinator/cleanup-runner';
+import { budgetAllows } from '../share-link-coordinator/budget-helpers';
+import { runShareLinkRecoveryOnce } from '../share-link-coordinator/recovery-runner';
+import type { ShareContentClient } from '../share-content-client/types';
+import type { PruneShareViewReceiptsInput } from '../../accesslayer/share-link/types';
+import {
+    createMaintenancePassBudget,
+    resolveMaintenanceBudgetMs,
+    type MaintenancePassBudget,
+} from './budget';
+import { safeLogMaintenance } from './telemetry';
+import type {
+    ShareLinkMaintenanceConfig,
+    ShareLinkMaintenanceFailureCategory,
+    ShareLinkMaintenanceLogger,
+    ShareLinkMaintenanceRunSummary,
+} from './types';
+
+export type ShareLinkMaintenanceRunnerDependencies = {
+    config: ShareLinkMaintenanceConfig;
+    recoveryRepository: RecoveryRunnerDependencies['repository'];
+    cleanupRepository: CleanupRunnerDependencies['repository'];
+    /**
+     * Namespace-scoped, bounded receipt prune. Injected so DB-free unit tests
+     * never load the Neo4j `@instance`; production passes the real repository.
+     */
+    pruneReceipts: (input: PruneShareViewReceiptsInput) => Promise<number>;
+    client: Pick<ShareContentClient, 'stat' | 'delete'>;
+    logger: ShareLinkMaintenanceLogger;
+    /** Monotonic clock for the cooperative budget; injectable for tests. */
+    monotonicNow?: () => number;
+    /** Wall clock passed through to the repositories; production omits it. */
+    now?: () => Date;
+    /**
+     * Optional Lambda remaining-time source, in milliseconds. Ignored when a
+     * pre-started `budget` is supplied.
+     */
+    remainingTimeMs?: () => number;
+    /**
+     * Optional budget already started by the runtime BEFORE dependency
+     * initialization. Reused so a slow cold start consumes the invocation
+     * deadline rather than receiving a fresh post-setup budget.
+     */
+    budget?: MaintenancePassBudget;
+};
+
+/**
+ * Bounded graph cost of the very first recovery stage (discovery read). If this
+ * does not fit, neither recovery nor cleanup can start.
+ */
+const recoveryDiscoveryCostMs = (config: ShareLinkMaintenanceConfig): number =>
+    config.graphTimeoutMs;
+
+/**
+ * Worst-case bounded cost of one whole cleanup unit:
+ *   claim (graph) + delete (HTTP) + complete (graph).
+ */
+const cleanupUnitCostMs = (config: ShareLinkMaintenanceConfig): number =>
+    config.requestTimeoutMs + 2 * config.graphTimeoutMs;
+
+/**
+ * Bounded cost of one namespace-scoped receipt-prune read transaction.
+ */
+const receiptPruneCostMs = (config: ShareLinkMaintenanceConfig): number => config.graphTimeoutMs;
+
+/**
+ * One bounded maintenance invocation: namespace-scoped recovery followed by
+ * namespace-scoped cleanup, each with its own count limit and a shared elapsed
+ * deadline.
+ *
+ * The deadline is cooperative (see `createMaintenancePassBudget`): it is checked
+ * before every claim, never enforced with `Promise.race`, so a remote delete or
+ * graph mutation that has already started is always awaited to a tracked result.
+ * Admission requires the remaining time to cover the whole next unit — the
+ * claim, the bounded HTTP call and the finalizing graph write — plus the
+ * finalization/telemetry reserve. The HTTP allowance is fixed when the transport
+ * client is built, so it cannot be shrunk per call; graph transaction timeouts
+ * are dynamically capped to the time actually left.
+ *
+ * Every failure is folded into a fixed category; the summary exposes aggregate
+ * counts and durations only.
+ */
+export const runShareLinkMaintenancePass = async (
+    dependencies: ShareLinkMaintenanceRunnerDependencies
+): Promise<ShareLinkMaintenanceRunSummary> => {
+    const { config, logger } = dependencies;
+
+    const budget =
+        dependencies.budget ??
+        createMaintenancePassBudget({
+            budgetMs: resolveMaintenanceBudgetMs(config.budgetMs, dependencies.remainingTimeMs?.()),
+            finalizeReserveMs: config.finalizeReserveMs,
+            monotonicNow: dependencies.monotonicNow,
+        });
+
+    const categories: Partial<Record<ShareLinkMaintenanceFailureCategory, number>> = {};
+
+    if (budget.exhausted()) {
+        const summary: ShareLinkMaintenanceRunSummary = {
+            status: 'deadline_exhausted',
+            durationMs: budget.elapsedMs(),
+            budgetMs: budget.configuredMs,
+            recovery: null,
+            cleanup: null,
+            receiptPrune: null,
+            categories,
+        };
+
+        safeLogMaintenance(logger, summary);
+
+        return summary;
+    }
+
+    let recovery: ShareLinkMaintenanceRunSummary['recovery'] = null;
+    let cleanup: ShareLinkMaintenanceRunSummary['cleanup'] = null;
+    let receiptPrune: ShareLinkMaintenanceRunSummary['receiptPrune'] = null;
+    let recoveryAttempted = false;
+    let cleanupAttempted = false;
+    let receiptPruneAttempted = false;
+    let budgetStoppedRecovery = false;
+    let budgetStoppedCleanup = false;
+    let budgetStoppedReceiptPrune = false;
+
+    if (budgetAllows(budget, recoveryDiscoveryCostMs(config))) {
+        recoveryAttempted = true;
+
+        try {
+            recovery = await runShareLinkRecoveryOnce({
+                repository: dependencies.recoveryRepository,
+                client: dependencies.client,
+                claimant: config.claimant,
+                namespace: config.namespace,
+                limit: config.recoveryLimit,
+                leaseMs: config.leaseMs,
+                budget,
+                transactionTimeoutMs: config.graphTimeoutMs,
+                requestTimeoutMs: config.requestTimeoutMs,
+                noInlineRetry: true,
+                now: dependencies.now,
+            });
+        } catch {
+            categories.share_link_maintenance_recovery_failed = 1;
+        }
+    } else {
+        budgetStoppedRecovery = true;
+    }
+
+    if (budgetAllows(budget, cleanupUnitCostMs(config))) {
+        cleanupAttempted = true;
+
+        try {
+            cleanup = await runShareContentCleanupOnce({
+                repository: dependencies.cleanupRepository,
+                client: dependencies.client,
+                claimant: config.claimant,
+                namespace: config.namespace,
+                limit: config.cleanupLimit,
+                claimMs: config.claimMs,
+                // One job per claim so a lapsed deadline can never strand a batch.
+                claimBatchSize: 1,
+                transactionTimeoutMs: config.graphTimeoutMs,
+                requestTimeoutMs: config.requestTimeoutMs,
+                noInlineRetry: true,
+                budget,
+                now: dependencies.now,
+            });
+        } catch {
+            categories.share_link_maintenance_cleanup_failed = 1;
+        }
+    } else {
+        budgetStoppedCleanup = true;
+    }
+
+    if (budgetAllows(budget, receiptPruneCostMs(config))) {
+        receiptPruneAttempted = true;
+
+        try {
+            const pruned = await dependencies.pruneReceipts({
+                namespace: config.namespace,
+                limit: config.receiptPruneLimit,
+                now: dependencies.now?.(),
+                // One bounded explicit read transaction, no inline retry: the
+                // scheduler cadence owns retry.
+                transaction: { timeoutMs: config.graphTimeoutMs, noInlineRetry: true },
+            });
+            receiptPrune = { pruned };
+        } catch {
+            categories.share_link_maintenance_receipt_prune_failed = 1;
+        }
+    } else {
+        budgetStoppedReceiptPrune = true;
+    }
+
+    const failed =
+        (recoveryAttempted && recovery === null) ||
+        (cleanupAttempted && cleanup === null) ||
+        (receiptPruneAttempted && receiptPrune === null);
+    const deadlineStopped =
+        budgetStoppedRecovery || budgetStoppedCleanup || budgetStoppedReceiptPrune;
+    const status = failed
+        ? 'failed'
+        : budget.exhausted() || deadlineStopped
+          ? 'deadline_exhausted'
+          : 'completed';
+
+    const summary: ShareLinkMaintenanceRunSummary = {
+        status,
+        durationMs: budget.elapsedMs(),
+        budgetMs: budget.configuredMs,
+        recovery,
+        cleanup,
+        receiptPrune,
+        categories,
+    };
+
+    safeLogMaintenance(logger, summary);
+
+    return summary;
+};