@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/resource-reservations.js

@@ -0,0 +1,577 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { initializePersonalOs, mutatePersonalOsWithSidecar, readPersonalOsSidecar } from './ssot.js';
+const ledgerVersion = 1;
+const defaultSidecarPath = 'resource-reservations/ledger.json';
+const snapshotIdPattern = /^sha256:[0-9a-f]{64}$/u;
+/**
+ * Adapt the real immutable ProblemSnapshot store to the reservation port.
+ *
+ * Story05 owns loading, integrity checks, and current read ACL checks.  This
+ * adapter only binds the caller's principal, loads the current snapshot, and
+ * verifies the fixed problem/revision and scope reference.  The loader must
+ * connect Story05's canonical reference provider.  The tenant boundary and
+ * execution authorization remain the reservation/auth ports.
+ */
+export function createResourceReservationProblemSnapshotPort(options) {
+    if (!options || typeof options !== 'object' || typeof options.root !== 'string' || options.root.length === 0) {
+        throw new TypeError('problem snapshot root must be a non-empty path');
+    }
+    if (typeof options.load !== 'function') {
+        throw new TypeError('problem snapshot loader is required');
+    }
+    return {
+        async verify({ principal, scopeId, reference }) {
+            try {
+                const snapshot = await options.load({
+                    root: options.root,
+                    snapshot_id: reference.problem_snapshot_id,
+                    access: { principal },
+                    reference_resolution: 'current',
+                });
+                return snapshot.snapshot_version === 'judgment-problem-snapshot.v1'
+                    && snapshot.problem_id === reference.problem_id
+                    && snapshot.revision === reference.revision
+                    && snapshot.owner_scope.id === scopeId
+                    && snapshot.execution_permission === 'none';
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+export class ResourceReservationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ResourceReservationError';
+        this.code = code;
+    }
+}
+export class ResourceReservationService {
+    dataDir;
+    authorization;
+    problemSnapshot;
+    capacity;
+    clock;
+    sidecarPath;
+    constructor(options) {
+        assertText(options.dataDir, 'dataDir');
+        this.dataDir = options.dataDir;
+        this.authorization = options.authorization;
+        this.problemSnapshot = options.problemSnapshot;
+        this.capacity = options.capacity;
+        this.clock = options.clock ?? (() => new Date());
+        this.sidecarPath = options.sidecarPath ?? defaultSidecarPath;
+        assertSidecarPath(this.sidecarPath);
+    }
+    async initialize() {
+        await initializePersonalOs(this.dataDir);
+    }
+    async estimate(input) {
+        const request = normalizeRequest(input);
+        await this.verifyProblem(request);
+        await this.authorize({ action: 'estimate', request });
+        await this.initialize();
+        const ledger = parseLedger(await readPersonalOsSidecar(this.dataDir, this.sidecarPath));
+        const capacity = await this.readCapacity(request);
+        const committedAmount = committedAmountFor(ledger, request);
+        return {
+            tenantId: request.tenantId,
+            scopeId: request.scopeId,
+            resourceId: request.resourceId,
+            period: request.period,
+            unit: request.unit,
+            requestedAmount: request.amount,
+            capacity,
+            committedAmount,
+            availableAmount: Math.max(0, capacity - committedAmount),
+        };
+    }
+    async approve(input) {
+        const request = normalizeRequest(input);
+        return this.mutate('approve', request.operationId, request, async (ledger) => {
+            await this.verifyProblem(request);
+            const decision = await this.authorize({ action: 'approve', request });
+            const approval = approvalFromDecision(decision, this.now());
+            const now = this.now().toISOString();
+            const reservation = {
+                reservationId: `reservation-${randomUUID()}`,
+                state: 'approved',
+                ...reservationFields(request),
+                approval,
+                externalAction: { status: 'not_started' },
+                createdAt: now,
+                updatedAt: now,
+                history: [{
+                        action: 'approve',
+                        operationId: request.operationId,
+                        principal: request.principal,
+                        occurredAt: now,
+                        toState: 'approved',
+                        amount: request.amount,
+                        externalActionStatus: 'not_started',
+                    }],
+            };
+            ledger.reservations.push(reservation);
+            return { reservation: clone(reservation) };
+        });
+    }
+    async reserve(input) {
+        const request = normalizeRequest(input);
+        const approvalId = input.approvalId;
+        if (approvalId !== undefined)
+            assertText(approvalId, 'approvalId');
+        if (approvalId === undefined) {
+            throw new ResourceReservationError('approval_required', 'reserve requires a prior approvalId');
+        }
+        const payload = { ...request, approvalId };
+        return this.mutate('reserve', request.operationId, payload, async (ledger) => {
+            await this.verifyProblem(request);
+            const reservation = findReservationByApprovalId(ledger, approvalId, request);
+            assertRequestMatchesReservation(request, reservation);
+            assertApprovalUsable(reservation, this.now());
+            if (reservation.state !== 'approved') {
+                throw new ResourceReservationError('reservation_state_conflict', `Reservation ${reservation.reservationId} is ${reservation.state}`);
+            }
+            const approval = reservation.approval;
+            await this.authorize({ action: 'reserve', request, approvalId: approval.approvalId, reservation });
+            const capacity = await this.readCapacity(request);
+            const committedAmount = committedAmountFor(ledger, request, reservation.reservationId);
+            if (committedAmount + request.amount > capacity) {
+                throw new ResourceReservationError('capacity_exceeded', `Capacity ${capacity} is insufficient for ${request.amount}`);
+            }
+            const now = this.now().toISOString();
+            const previousState = reservation.state;
+            reservation.state = 'reserved';
+            reservation.updatedAt = now;
+            reservation.history.push({
+                action: 'reserve',
+                operationId: request.operationId,
+                principal: request.principal,
+                occurredAt: now,
+                fromState: previousState,
+                toState: 'reserved',
+                amount: reservation.amount,
+                externalActionStatus: reservation.externalAction.status,
+            });
+            return { reservation: clone(reservation) };
+        });
+    }
+    async release(input) {
+        return this.transition('release', input, 'released');
+    }
+    async cancel(input) {
+        return this.transition('cancel', input, 'cancelled');
+    }
+    async consume(input) {
+        return this.transition('consume', input, 'consumed');
+    }
+    async startExternalAction(input) {
+        const normalized = normalizeMutationInput(input);
+        return this.mutate('start_external', normalized.operationId, normalized, async (ledger) => {
+            const reservation = findReservationById(ledger, normalized.reservationId, normalized);
+            await this.authorize({ action: 'start_external', input: normalized, reservation });
+            if (reservation.state !== 'reserved') {
+                throw new ResourceReservationError('reservation_state_conflict', `Reservation ${reservation.reservationId} is ${reservation.state}`);
+            }
+            if (reservation.externalAction.status !== 'not_started') {
+                throw new ResourceReservationError('reservation_state_conflict', `External action is already ${reservation.externalAction.status}`);
+            }
+            const now = this.now().toISOString();
+            reservation.externalAction = { status: 'started', startedAt: now };
+            reservation.updatedAt = now;
+            reservation.history.push({
+                action: 'start_external',
+                operationId: normalized.operationId,
+                principal: normalized.principal,
+                occurredAt: now,
+                fromState: reservation.state,
+                toState: reservation.state,
+                amount: reservation.amount,
+                externalActionStatus: 'started',
+            });
+            return { reservation: clone(reservation) };
+        });
+    }
+    async readLedger(input) {
+        const normalized = normalizeScopeInput(input);
+        await this.authorize({ action: 'read', input: normalized });
+        await this.initialize();
+        const ledger = parseLedger(await readPersonalOsSidecar(this.dataDir, this.sidecarPath));
+        return {
+            version: ledgerVersion,
+            reservations: ledger.reservations
+                .filter((reservation) => reservation.tenantId === normalized.tenantId
+                && reservation.scopeId === normalized.scopeId
+                && reservation.principal === normalized.principal)
+                .map((reservation) => clone(reservation)),
+        };
+    }
+    async transition(action, input, targetState) {
+        const normalized = normalizeMutationInput(input);
+        return this.mutate(action, normalized.operationId, normalized, async (ledger) => {
+            const reservation = findReservationById(ledger, normalized.reservationId, normalized);
+            await this.authorize({ action, input: normalized, reservation });
+            if (reservation.externalAction.status === 'started' || reservation.externalAction.status === 'unknown') {
+                if (action === 'release' || action === 'cancel') {
+                    throw new ResourceReservationError('external_action_reconciliation_required', `Reservation ${reservation.reservationId} has an external action in ${reservation.externalAction.status} state`);
+                }
+            }
+            const allowedStates = action === 'consume' ? ['reserved'] : ['approved', 'reserved'];
+            if (!allowedStates.includes(reservation.state)) {
+                throw new ResourceReservationError('reservation_state_conflict', `Reservation ${reservation.reservationId} is ${reservation.state}`);
+            }
+            const now = this.now().toISOString();
+            const previousState = reservation.state;
+            reservation.state = targetState;
+            reservation.updatedAt = now;
+            if (action === 'consume')
+                reservation.externalAction = { status: 'completed', startedAt: reservation.externalAction.startedAt };
+            reservation.history.push({
+                action,
+                operationId: normalized.operationId,
+                principal: normalized.principal,
+                occurredAt: now,
+                fromState: previousState,
+                toState: targetState,
+                amount: reservation.amount,
+                externalActionStatus: reservation.externalAction.status,
+            });
+            return { reservation: clone(reservation) };
+        });
+    }
+    async mutate(action, operationId, payload, handler) {
+        await this.initialize();
+        const payloadDigest = digest({ action, payload });
+        return mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, async (current, sidecarContent) => {
+            const ledger = parseLedger(sidecarContent);
+            const tenantId = extractTenantId(payload);
+            const existing = ledger.operations.find((operation) => (operation.tenantId === tenantId && operation.operationId === operationId));
+            if (existing) {
+                // Keep the scope boundary before comparing the payload so a caller in
+                // another principal or scope cannot learn whether an operation exists.
+                assertReplayScope(payload, existing.result.reservation);
+                if (existing.action !== action || existing.payloadDigest !== payloadDigest) {
+                    throw new ResourceReservationError('operation_conflict', `Operation ${operationId} was already used with a different payload`);
+                }
+                // Replaying an idempotent operation still reads its stored result. The
+                // caller must pass the current authorization check before that result
+                // is returned, even though no new write is performed.
+                await this.reauthorizeReplay(action, existing);
+                return { next: current, sidecarContent: serializeLedger(ledger), result: clone(existing.result) };
+            }
+            const result = await handler(ledger);
+            ledger.operations.push({
+                operationId,
+                tenantId,
+                action,
+                payloadDigest,
+                result: clone(result),
+                recordedAt: this.now().toISOString(),
+            });
+            return { next: current, sidecarContent: serializeLedger(ledger), result };
+        });
+    }
+    async reauthorizeReplay(action, existing) {
+        const storedReservation = existing.result.reservation;
+        if (action === 'approve') {
+            const request = requestFromReservation(storedReservation, existing.operationId);
+            await this.authorize({ action, request, reservation: storedReservation });
+            return;
+        }
+        if (action === 'reserve') {
+            const request = requestFromReservation(storedReservation, existing.operationId);
+            await this.authorize({
+                action,
+                request,
+                approvalId: storedReservation.approval.approvalId,
+                reservation: storedReservation,
+            });
+            return;
+        }
+        const input = {
+            operationId: existing.operationId,
+            tenantId: storedReservation.tenantId,
+            principal: storedReservation.principal,
+            scopeId: storedReservation.scopeId,
+            reservationId: storedReservation.reservationId,
+        };
+        await this.authorize({ action, input, reservation: storedReservation });
+    }
+    async authorize(input) {
+        const request = input.request;
+        const scopeInput = input.input;
+        const mutationInput = scopeInput !== undefined && 'reservationId' in scopeInput ? scopeInput : undefined;
+        const decision = await this.authorization.authorize({
+            action: input.action,
+            operationId: request?.operationId ?? mutationInput?.operationId ?? `read-${randomUUID()}`,
+            tenantId: request?.tenantId ?? scopeInput?.tenantId ?? input.reservation?.tenantId ?? '',
+            principal: request?.principal ?? scopeInput?.principal ?? input.reservation?.principal ?? '',
+            scopeId: request?.scopeId ?? scopeInput?.scopeId ?? input.reservation?.scopeId ?? '',
+            resourceId: request?.resourceId ?? input.reservation?.resourceId,
+            runId: request?.runId ?? input.reservation?.runId,
+            problem: request?.problem ?? input.reservation?.problem,
+            approvalId: input.approvalId,
+            reservationId: mutationInput?.reservationId ?? input.reservation?.reservationId,
+            reservation: input.reservation,
+        });
+        if (decision.status === 'expired')
+            throw new ResourceReservationError('approval_expired', 'Authorization approval is expired');
+        if (decision.status === 'revoked')
+            throw new ResourceReservationError('approval_revoked', 'Authorization approval is revoked');
+        if (decision.status !== 'approved')
+            throw new ResourceReservationError('authorization_denied', 'Authorization denied the resource operation');
+        if (decision.expiresAt !== undefined && decision.expiresAt !== null) {
+            assertTimestamp(decision.expiresAt, 'authorization.expiresAt');
+            if (Date.parse(decision.expiresAt) <= this.now().getTime()) {
+                throw new ResourceReservationError('approval_expired', 'Authorization approval is expired');
+            }
+        }
+        return decision;
+    }
+    async verifyProblem(request) {
+        try {
+            const verified = await this.problemSnapshot.verify({
+                tenantId: request.tenantId,
+                principal: request.principal,
+                scopeId: request.scopeId,
+                reference: request.problem,
+            });
+            if (verified === false)
+                throw new Error('snapshot verifier rejected reference');
+        }
+        catch {
+            throw new ResourceReservationError('problem_snapshot_invalid', 'Problem snapshot reference could not be verified');
+        }
+    }
+    async readCapacity(request) {
+        const capacity = await this.capacity.read({
+            tenantId: request.tenantId,
+            principal: request.principal,
+            scopeId: request.scopeId,
+            resourceId: request.resourceId,
+            period: request.period,
+            unit: request.unit,
+        });
+        if (capacity === null || !Number.isFinite(capacity) || capacity < 0) {
+            throw new ResourceReservationError('capacity_unknown', 'Current resource capacity is unknown');
+        }
+        return capacity;
+    }
+    now() {
+        const now = this.clock();
+        if (!(now instanceof Date) || !Number.isFinite(now.getTime()))
+            throw new ResourceReservationError('validation_error', 'Clock returned an invalid date');
+        return new Date(now);
+    }
+}
+function normalizeRequest(input) {
+    assertText(input.operationId, 'operationId');
+    assertText(input.tenantId, 'tenantId');
+    assertText(input.principal, 'principal');
+    assertText(input.scopeId, 'scopeId');
+    assertText(input.resourceId, 'resourceId');
+    assertText(input.unit, 'unit');
+    assertText(input.runId, 'runId');
+    if (!Number.isFinite(input.amount) || input.amount <= 0)
+        throw new ResourceReservationError('validation_error', 'amount must be a positive finite number');
+    const period = normalizePeriod(input.period);
+    const problem = normalizeProblemReference(input.problem);
+    return {
+        operationId: input.operationId,
+        tenantId: input.tenantId,
+        principal: input.principal,
+        scopeId: input.scopeId,
+        resourceId: input.resourceId,
+        period,
+        amount: input.amount,
+        unit: input.unit,
+        runId: input.runId,
+        problem,
+    };
+}
+function normalizeMutationInput(input) {
+    assertText(input.operationId, 'operationId');
+    assertText(input.tenantId, 'tenantId');
+    assertText(input.principal, 'principal');
+    assertText(input.scopeId, 'scopeId');
+    assertText(input.reservationId, 'reservationId');
+    return { ...input };
+}
+function normalizeScopeInput(input) {
+    assertText(input.tenantId, 'tenantId');
+    assertText(input.principal, 'principal');
+    assertText(input.scopeId, 'scopeId');
+    return { ...input };
+}
+function normalizePeriod(period) {
+    assertText(period?.startsAt, 'period.startsAt');
+    assertText(period?.endsAt, 'period.endsAt');
+    assertTimestamp(period.startsAt, 'period.startsAt');
+    assertTimestamp(period.endsAt, 'period.endsAt');
+    if (Date.parse(period.endsAt) <= Date.parse(period.startsAt)) {
+        throw new ResourceReservationError('validation_error', 'period.endsAt must be after period.startsAt');
+    }
+    return { startsAt: period.startsAt, endsAt: period.endsAt };
+}
+function normalizeProblemReference(reference) {
+    assertText(reference?.problem_snapshot_id, 'problem.problem_snapshot_id');
+    assertText(reference?.problem_id, 'problem.problem_id');
+    assertText(reference?.revision, 'problem.revision');
+    if (!snapshotIdPattern.test(reference.problem_snapshot_id)) {
+        throw new ResourceReservationError('validation_error', 'problem.problem_snapshot_id must be a sha256 snapshot ID');
+    }
+    return {
+        problem_snapshot_id: reference.problem_snapshot_id,
+        problem_id: reference.problem_id,
+        revision: reference.revision,
+    };
+}
+function reservationFields(request) {
+    const { operationId: _operationId, ...fields } = request;
+    return fields;
+}
+function requestFromReservation(reservation, operationId) {
+    return {
+        operationId,
+        tenantId: reservation.tenantId,
+        principal: reservation.principal,
+        scopeId: reservation.scopeId,
+        resourceId: reservation.resourceId,
+        period: { ...reservation.period },
+        amount: reservation.amount,
+        unit: reservation.unit,
+        runId: reservation.runId,
+        problem: { ...reservation.problem },
+    };
+}
+function assertText(value, label) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 512 || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new ResourceReservationError('validation_error', `${label} must be a bounded text value`);
+    }
+}
+function assertTimestamp(value, label) {
+    if (!Number.isFinite(Date.parse(value)))
+        throw new ResourceReservationError('validation_error', `${label} must be an ISO timestamp`);
+}
+function assertSidecarPath(path) {
+    if (!path || path.startsWith('/') || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..')) {
+        throw new ResourceReservationError('validation_error', 'sidecarPath must remain relative to the SSOT root');
+    }
+}
+function approvalFromDecision(decision, now) {
+    const approvalId = decision.approvalId ?? `approval-${randomUUID()}`;
+    assertText(approvalId, 'authorization.approvalId');
+    const expiresAt = decision.expiresAt ?? undefined;
+    if (expiresAt !== undefined)
+        assertTimestamp(expiresAt, 'authorization.expiresAt');
+    const evidence = decision.evidence ?? {};
+    for (const [key, value] of Object.entries(evidence)) {
+        assertText(key, 'authorization.evidence key');
+        assertText(value, 'authorization.evidence value');
+    }
+    return {
+        approvalId,
+        approvedAt: now.toISOString(),
+        ...(expiresAt ? { expiresAt } : {}),
+        evidence: { ...evidence },
+    };
+}
+function assertApprovalUsable(reservation, now = new Date()) {
+    if (reservation.approval.expiresAt !== undefined && Date.parse(reservation.approval.expiresAt) <= now.getTime()) {
+        throw new ResourceReservationError('approval_expired', `Approval ${reservation.approval.approvalId} is expired`);
+    }
+}
+function assertRequestMatchesReservation(request, reservation) {
+    if (request.tenantId !== reservation.tenantId || request.scopeId !== reservation.scopeId) {
+        throw new ResourceReservationError('scope_mismatch', `Reservation ${reservation.reservationId} is outside the requested scope`);
+    }
+    const same = request.resourceId === reservation.resourceId
+        && request.unit === reservation.unit
+        && request.runId === reservation.runId
+        && request.amount === reservation.amount
+        && request.period.startsAt === reservation.period.startsAt
+        && request.period.endsAt === reservation.period.endsAt
+        && digest(request.problem) === digest(reservation.problem);
+    if (!same)
+        throw new ResourceReservationError('approval_mismatch', `Reservation ${reservation.reservationId} does not match the requested payload`);
+}
+function assertReplayScope(payload, reservation) {
+    if (!isRecord(payload)
+        || payload.tenantId !== reservation.tenantId
+        || payload.principal !== reservation.principal
+        || payload.scopeId !== reservation.scopeId) {
+        throw new ResourceReservationError('scope_mismatch', `Stored operation ${reservation.reservationId} is outside the requested scope`);
+    }
+}
+function findReservationById(ledger, reservationId, scope) {
+    const reservation = ledger.reservations.find((item) => item.reservationId === reservationId);
+    if (!reservation)
+        throw new ResourceReservationError('reservation_not_found', `Reservation ${reservationId} was not found`);
+    if (reservation.tenantId !== scope.tenantId || reservation.principal !== scope.principal || reservation.scopeId !== scope.scopeId) {
+        throw new ResourceReservationError('scope_mismatch', `Reservation ${reservationId} is outside the requested scope`);
+    }
+    return reservation;
+}
+function findReservationByApprovalId(ledger, approvalId, scope) {
+    const reservation = ledger.reservations.find((item) => item.approval.approvalId === approvalId);
+    if (!reservation)
+        throw new ResourceReservationError('approval_required', `Approval ${approvalId} was not found`);
+    if (reservation.tenantId !== scope.tenantId || reservation.principal !== scope.principal || reservation.scopeId !== scope.scopeId) {
+        throw new ResourceReservationError('scope_mismatch', `Approval ${approvalId} is outside the requested scope`);
+    }
+    return reservation;
+}
+function committedAmountFor(ledger, request, excludingReservationId) {
+    return ledger.reservations
+        .filter((reservation) => reservation.reservationId !== excludingReservationId)
+        .filter((reservation) => reservation.state === 'reserved')
+        .filter((reservation) => reservation.tenantId === request.tenantId && reservation.scopeId === request.scopeId)
+        .filter((reservation) => reservation.resourceId === request.resourceId && reservation.unit === request.unit)
+        .filter((reservation) => overlaps(reservation.period, request.period))
+        .reduce((sum, reservation) => sum + reservation.amount, 0);
+}
+function overlaps(left, right) {
+    return Date.parse(left.startsAt) < Date.parse(right.endsAt) && Date.parse(right.startsAt) < Date.parse(left.endsAt);
+}
+function parseLedger(content) {
+    if (!content || content.trim() === '')
+        return { version: ledgerVersion, reservations: [], operations: [] };
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        throw new ResourceReservationError('ledger_invalid', 'Resource reservation ledger is not valid JSON');
+    }
+    if (!isRecord(value) || value.version !== ledgerVersion || !Array.isArray(value.reservations) || !Array.isArray(value.operations)) {
+        throw new ResourceReservationError('ledger_invalid', 'Resource reservation ledger has an unsupported shape');
+    }
+    return value;
+}
+function serializeLedger(ledger) {
+    return `${JSON.stringify(ledger, null, 2)}\n`;
+}
+function extractTenantId(payload) {
+    if (!isRecord(payload) || typeof payload.tenantId !== 'string') {
+        throw new ResourceReservationError('validation_error', 'operation payload must include tenantId');
+    }
+    return payload.tenantId;
+}
+function digest(value) {
+    return createHash('sha256').update(JSON.stringify(sortJson(value))).digest('hex');
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map((item) => sortJson(item));
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, sortJson(item)]));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function clone(value) {
+    return structuredClone(value);
+}