@unson/brainbase-mcp 0.10.15 → 0.12.0

package/dist/execution-authority.js

@@ -13,11 +13,11 @@ export class ExecutionAuthorityError extends Error {
 }
 /**
  * Persists the execution intent before crossing either the reservation or
- * external-effect boundary. The reservation and intent sidecars are separate
+ * external-effect boundary. The reservation and intent stores are separate
  * transactions; callers must reconcile recovery_required/unknown states.
  */
 export class ExecutionAuthorityService {
-    dataDir;
+    store;
     authority;
     approval;
     constraint;
@@ -25,9 +25,7 @@ export class ExecutionAuthorityService {
     readAccess;
     effect;
     clock;
-    sidecarPath;
     constructor(options) {
-        assertText(options.dataDir, 'dataDir');
         if (!options.authority || typeof options.authority.verify !== 'function')
             throw new TypeError('authority port is required');
         if (!options.approval || typeof options.approval.verify !== 'function')
@@ -39,9 +37,20 @@ export class ExecutionAuthorityService {
         }
         if (!options.readAccess || typeof options.readAccess.verify !== 'function')
             throw new TypeError('read access port is required');
-        if (!options.effect || typeof options.effect.start !== 'function')
-            throw new TypeError('effect port is required');
-        this.dataDir = options.dataDir;
+        if (options.effect !== undefined && (!options.effect || typeof options.effect.start !== 'function')) {
+            throw new TypeError('effect port must implement start');
+        }
+        if (options.store) {
+            if (typeof options.store.read !== 'function' || typeof options.store.insert !== 'function' || typeof options.store.update !== 'function') {
+                throw new TypeError('store must implement read, insert, and update');
+            }
+            this.store = options.store;
+        }
+        else {
+            if (!isText(options.dataDir))
+                throw new TypeError('store or dataDir is required');
+            this.store = createSidecarExecutionIntentStore({ dataDir: options.dataDir, sidecarPath: options.sidecarPath });
+        }
         this.authority = options.authority;
         this.approval = options.approval;
         this.constraint = options.constraint;
@@ -49,28 +58,155 @@ export class ExecutionAuthorityService {
         this.readAccess = options.readAccess;
         this.effect = options.effect;
         this.clock = options.clock ?? (() => new Date());
-        this.sidecarPath = options.sidecarPath ?? defaultSidecarPath;
-        assertSidecarPath(this.sidecarPath);
     }
     async initialize() {
-        await initializePersonalOs(this.dataDir);
+        await this.storeCall(async () => { await this.store.initialize?.(); });
+    }
+    /** Runs the checks, marks the reservation, and calls the in-process effect port. */
+    async start(input, options = {}) {
+        if (!this.effect)
+            throw new ExecutionAuthorityError('effect_unconfigured', 'This host has no effect port; use register instead');
+        const normalized = normalizeInput(input);
+        const attribution = normalizeAttribution(options.attribution, normalized.principal);
+        const payloadDigest = digest(normalized);
+        await this.initialize();
+        await this.verifyReadAccess(normalized);
+        const existing = await this.findIntent(normalized);
+        if (existing)
+            return this.handleExisting(existing, payloadDigest, attribution);
+        const prepared = await this.prepare(normalized, payloadDigest, attribution, 'start');
+        if ('replay' in prepared)
+            return this.handleExisting(prepared.replay, payloadDigest, attribution);
+        let effectResult;
+        try {
+            effectResult = normalizeEffectResult(await this.effect.start({ ...normalized, capability: prepared.capability }));
+        }
+        catch {
+            await this.persistRecovery(normalized, payloadDigest, {
+                code: 'effect_unknown',
+                reason: 'effect provider failed after the reservation start boundary',
+                reservationMark: 'started',
+                effect: 'unknown',
+                phase: 'unknown',
+            });
+            throw new ExecutionAuthorityError('effect_unknown', 'External effect start is unknown; reconciliation is required');
+        }
+        if (effectResult.status !== 'started') {
+            await this.persistRecovery(normalized, payloadDigest, {
+                code: 'effect_unknown',
+                reason: 'effect provider returned an unknown start state',
+                reservationMark: 'started',
+                effect: 'unknown',
+                phase: 'unknown',
+            });
+            throw new ExecutionAuthorityError('effect_unknown', 'External effect start is unknown; reconciliation is required');
+        }
+        try {
+            const intent = await this.updateIntent(normalized, payloadDigest, (next) => {
+                next.phase = 'started';
+                next.reservationMark = 'started';
+                next.effect.status = 'started';
+            });
+            return {
+                intent: publicIntent(intent),
+                effect: { operationId: normalized.operationId, status: 'started' },
+                replayed: false,
+            };
+        }
+        catch {
+            throw new ExecutionAuthorityError('recovery_required', 'Effect started but the execution intent could not be finalized');
+        }
     }
-    async start(input) {
+    /**
+     * Registers the execution: runs the checks, marks the reservation, and
+     * issues the permit. The effect owner reports the outcome with reportEffect.
+     */
+    async register(input, options = {}) {
         const normalized = normalizeInput(input);
+        const attribution = normalizeAttribution(options.attribution, normalized.principal);
         const payloadDigest = digest(normalized);
         await this.initialize();
         await this.verifyReadAccess(normalized);
         const existing = await this.findIntent(normalized);
         if (existing)
-            return this.handleExisting(existing, payloadDigest);
-        const initial = await this.verifyAll(normalized, 'initial');
+            return this.replayRegistration(existing, payloadDigest, attribution);
+        const prepared = await this.prepare(normalized, payloadDigest, attribution, 'register');
+        if ('replay' in prepared)
+            return this.replayRegistration(prepared.replay, payloadDigest, attribution);
+        return {
+            intent: publicIntent(prepared.intent),
+            capability: clone(prepared.capability),
+            capabilityDigest: prepared.capabilityDigest,
+            replayed: false,
+        };
+    }
+    /** Records the effect owner's outcome for a registered execution. */
+    async reportEffect(report) {
+        const lookup = normalizeLookup(report);
+        if (report.status !== 'started' && report.status !== 'unknown') {
+            throw new ExecutionAuthorityError('validation_error', 'status must be started or unknown');
+        }
+        assertText(report.capabilityDigest, 'capabilityDigest');
+        await this.initialize();
+        await this.verifyReadAccess(lookup);
+        const updated = await this.storeCall(() => this.store.update(intentKey(lookup), (current) => {
+            validateStoredIntent(current);
+            assertIntentScope(lookup, current);
+            if (current.capability?.digest !== report.capabilityDigest) {
+                throw new ExecutionAuthorityError('capability_mismatch', 'The report does not match the issued permit');
+            }
+            const next = clone(current);
+            if (report.status === 'started') {
+                if (current.phase === 'started')
+                    return current;
+                if (current.phase !== 'registered' && current.phase !== 'unknown') {
+                    throw new ExecutionAuthorityError('recovery_required', `Operation ${current.operationId} requires reconciliation before a report`);
+                }
+                next.phase = 'started';
+                next.effect.status = 'started';
+                delete next.failure;
+            }
+            else {
+                if (current.phase === 'unknown')
+                    return current;
+                if (current.phase === 'started') {
+                    throw new ExecutionAuthorityError('operation_conflict', `Operation ${current.operationId} already reported a started effect`);
+                }
+                if (current.phase !== 'registered') {
+                    throw new ExecutionAuthorityError('recovery_required', `Operation ${current.operationId} requires reconciliation before a report`);
+                }
+                next.phase = 'unknown';
+                next.effect.status = 'unknown';
+                next.failure = { code: 'effect_unknown', reason: 'effect owner reported an unknown outcome' };
+            }
+            next.updatedAt = this.now().toISOString();
+            return next;
+        }));
+        if (!updated)
+            throw new ExecutionAuthorityError('intent_not_found', `Execution intent ${lookup.operationId} was not found`);
+        validateStoredIntent(updated);
+        return publicIntent(updated);
+    }
+    async readIntent(input) {
+        const lookup = normalizeLookup(input);
+        await this.initialize();
+        await this.verifyReadAccess(lookup);
+        const intent = await this.findIntent(lookup);
+        return intent ? publicIntent(intent) : undefined;
+    }
+    /**
+     * Shared path for start and register: initial checks, durable intent,
+     * fenced final checks, permit, and the reservation mark.
+     */
+    async prepare(normalized, payloadDigest, attribution, mode) {
+        const initial = await this.verifyAll(normalized, 'initial', undefined, attribution);
         if (initial.failure)
             throw errorFromFailure(initial.failure);
-        const recorded = await this.recordIntent(normalized, payloadDigest, initial.checks);
+        const recorded = await this.recordIntent(normalized, payloadDigest, initial.checks, attribution);
         if (!recorded.created)
-            return this.handleExisting(recorded.intent, payloadDigest);
+            return { replay: recorded.intent };
         const expectedRevisions = Object.fromEntries(initial.checks.map((check) => [check.check, check.revision ?? '']));
-        const final = await this.verifyAll(normalized, 'final', expectedRevisions);
+        const final = await this.verifyAll(normalized, 'final', expectedRevisions, attribution);
         if (final.failure) {
             await this.tryUpdateIntent(normalized, payloadDigest, (intent) => {
                 intent.verification.final = final.checks;
@@ -91,11 +227,14 @@ export class ExecutionAuthorityService {
             });
             throw errorFromFailure(failure);
         }
+        const capability = final.capability;
+        const capabilityDigest = digest(capability);
         await this.updateIntent(normalized, payloadDigest, (intent) => {
             intent.verification.final = final.checks;
             intent.capability = {
-                expiresAt: final.capability.expiresAt,
-                digest: digest(final.capability),
+                expiresAt: capability.expiresAt,
+                digest: capabilityDigest,
+                ...(mode === 'register' ? { grant: clone(capability) } : {}),
             };
         });
         let mark;
@@ -127,73 +266,31 @@ export class ExecutionAuthorityService {
             });
             throw new ExecutionAuthorityError('reservation_mark_unknown', 'Reservation start is unknown; reconciliation is required');
         }
-        try {
-            await this.updateIntent(normalized, payloadDigest, (intent) => {
-                intent.phase = 'reservation_marked';
-                intent.reservationMark = 'started';
-                // A crash after this write and during effect.start is ambiguous.
-                intent.effect.status = 'unknown';
-            });
-        }
-        catch {
-            throw new ExecutionAuthorityError('recovery_required', 'Reservation started but the execution intent could not be advanced');
-        }
-        let effectResult;
-        try {
-            effectResult = normalizeEffectResult(await this.effect.start({ ...normalized, capability: final.capability }));
-        }
-        catch {
-            await this.persistRecovery(normalized, payloadDigest, {
-                code: 'effect_unknown',
-                reason: 'effect provider failed after the reservation start boundary',
-                reservationMark: 'started',
-                effect: 'unknown',
-                phase: 'unknown',
-            });
-            throw new ExecutionAuthorityError('effect_unknown', 'External effect start is unknown; reconciliation is required');
-        }
-        if (effectResult.status !== 'started') {
-            await this.persistRecovery(normalized, payloadDigest, {
-                code: 'effect_unknown',
-                reason: 'effect provider returned an unknown start state',
-                reservationMark: 'started',
-                effect: 'unknown',
-                phase: 'unknown',
-            });
-            throw new ExecutionAuthorityError('effect_unknown', 'External effect start is unknown; reconciliation is required');
-        }
         try {
             const intent = await this.updateIntent(normalized, payloadDigest, (next) => {
-                next.phase = 'started';
                 next.reservationMark = 'started';
-                next.effect.status = 'started';
+                if (mode === 'register') {
+                    // The permit is issued; the effect owner has not started yet.
+                    next.phase = 'registered';
+                    next.effect.status = 'not_started';
+                }
+                else {
+                    next.phase = 'reservation_marked';
+                    // A crash after this write and during effect.start is ambiguous.
+                    next.effect.status = 'unknown';
+                }
             });
-            return {
-                intent,
-                effect: { operationId: normalized.operationId, status: 'started' },
-                replayed: false,
-            };
+            return { intent, capability, capabilityDigest };
         }
         catch {
-            throw new ExecutionAuthorityError('recovery_required', 'Effect started but the execution intent could not be finalized');
+            throw new ExecutionAuthorityError('recovery_required', 'Reservation started but the execution intent could not be advanced');
         }
     }
-    async readIntent(input) {
-        const lookup = normalizeLookup(input);
-        await this.initialize();
-        await this.verifyReadAccess(lookup);
-        const ledger = parseLedger(await readPersonalOsSidecar(this.dataDir, this.sidecarPath));
-        const intent = ledger.intents.find((candidate) => candidate.tenantId === lookup.tenantId && candidate.operationId === lookup.operationId);
-        if (!intent)
-            return undefined;
-        assertIntentScope(lookup, intent);
-        return clone(intent);
-    }
     async findIntent(input) {
-        const ledger = parseLedger(await readPersonalOsSidecar(this.dataDir, this.sidecarPath));
-        const intent = ledger.intents.find((candidate) => candidate.tenantId === input.tenantId && candidate.operationId === input.operationId);
+        const intent = await this.storeCall(() => this.store.read(intentKey(input)));
         if (!intent)
             return undefined;
+        validateStoredIntent(intent);
         assertIntentScope(input, intent);
         return clone(intent);
     }
@@ -213,51 +310,44 @@ export class ExecutionAuthorityService {
         const code = status === 'revoked' ? 'read_revoked' : status === 'expired' ? 'read_expired' : 'read_unknown';
         throw new ExecutionAuthorityError(code, `Current execution intent read access is ${status}`);
     }
-    async recordIntent(input, payloadDigest, checks) {
-        return mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, async (current, sidecarContent) => {
-            const ledger = parseLedger(sidecarContent);
-            const existing = ledger.intents.find((candidate) => candidate.tenantId === input.tenantId && candidate.operationId === input.operationId);
-            if (existing) {
-                assertIntentScope(input, existing);
-                if (existing.payloadDigest !== payloadDigest) {
-                    throw new ExecutionAuthorityError('operation_conflict', `Operation ${input.operationId} was already used with a different payload`);
-                }
-                return { next: current, sidecarContent: serializeLedger(ledger), result: { intent: clone(existing), created: false } };
+    async recordIntent(input, payloadDigest, checks, attribution) {
+        const now = this.now().toISOString();
+        const intent = {
+            version: ledgerVersion,
+            operationId: input.operationId,
+            tenantId: input.tenantId,
+            principal: input.principal,
+            scopeId: input.scopeId,
+            runId: input.runId,
+            reservationId: input.reservationId,
+            approvalId: input.approvalId,
+            authorityRef: input.authorityRef,
+            constraintRefs: [...input.constraintRefs],
+            problem: { ...input.problem },
+            payloadDigest,
+            ...(attribution ? { attribution: clone(attribution) } : {}),
+            // This is deliberately a non-replayable durable state. The current
+            // call may continue in memory; a later caller must reconcile it.
+            phase: 'recovery_required',
+            reservationMark: 'not_started',
+            effect: { operationId: input.operationId, status: 'not_started' },
+            verification: { initial: clone(checks) },
+            createdAt: now,
+            updatedAt: now,
+        };
+        const result = await this.storeCall(() => this.store.insert(intent));
+        validateStoredIntent(result.intent);
+        if (!result.created) {
+            assertIntentScope(input, result.intent);
+            if (result.intent.payloadDigest !== payloadDigest) {
+                throw new ExecutionAuthorityError('operation_conflict', `Operation ${input.operationId} was already used with a different payload`);
             }
-            const now = this.now().toISOString();
-            const intent = {
-                version: ledgerVersion,
-                operationId: input.operationId,
-                tenantId: input.tenantId,
-                principal: input.principal,
-                scopeId: input.scopeId,
-                runId: input.runId,
-                reservationId: input.reservationId,
-                approvalId: input.approvalId,
-                authorityRef: input.authorityRef,
-                constraintRefs: [...input.constraintRefs],
-                problem: { ...input.problem },
-                payloadDigest,
-                // This is deliberately a non-replayable durable state. The current
-                // call may continue in memory; a later caller must reconcile it.
-                phase: 'recovery_required',
-                reservationMark: 'not_started',
-                effect: { operationId: input.operationId, status: 'not_started' },
-                verification: { initial: clone(checks) },
-                createdAt: now,
-                updatedAt: now,
-            };
-            ledger.intents.push(intent);
-            return { next: current, sidecarContent: serializeLedger(ledger), result: { intent: clone(intent), created: true } };
-        });
+        }
+        return { intent: clone(result.intent), created: result.created };
     }
     async updateIntent(input, payloadDigest, mutation) {
-        return mutatePersonalOsWithSidecar(this.dataDir, this.sidecarPath, async (current, sidecarContent) => {
-            const ledger = parseLedger(sidecarContent);
-            const index = ledger.intents.findIndex((candidate) => candidate.tenantId === input.tenantId && candidate.operationId === input.operationId);
-            if (index < 0)
-                throw new ExecutionAuthorityError('ledger_invalid', `Execution intent ${input.operationId} was not found`);
-            const existing = ledger.intents[index];
+        const updated = await this.storeCall(() => this.store.update(intentKey(input), (existing) => {
+            validateStoredIntent(existing);
             assertIntentScope(input, existing);
             if (existing.payloadDigest !== payloadDigest) {
                 throw new ExecutionAuthorityError('operation_conflict', `Operation ${input.operationId} was already used with a different payload`);
@@ -265,9 +355,12 @@ export class ExecutionAuthorityService {
             const nextIntent = clone(existing);
             mutation(nextIntent);
             nextIntent.updatedAt = this.now().toISOString();
-            ledger.intents[index] = nextIntent;
-            return { next: current, sidecarContent: serializeLedger(ledger), result: clone(nextIntent) };
-        });
+            return nextIntent;
+        }));
+        if (!updated)
+            throw new ExecutionAuthorityError('ledger_invalid', `Execution intent ${input.operationId} was not found`);
+        validateStoredIntent(updated);
+        return clone(updated);
     }
     async tryUpdateIntent(input, payloadDigest, mutation) {
         try {
@@ -275,7 +368,7 @@ export class ExecutionAuthorityService {
         }
         catch {
             // The durable recovery_required state is safer than retrying a failed
-            // cross-sidecar transition. Preserve the original denial to the caller.
+            // cross-store transition. Preserve the original denial to the caller.
         }
     }
     async persistRecovery(input, payloadDigest, options) {
@@ -286,7 +379,7 @@ export class ExecutionAuthorityService {
             intent.failure = { code: options.code, reason: options.reason };
         });
     }
-    async verifyAll(input, phase, expectedRevisions) {
+    async verifyAll(input, phase, expectedRevisions, attribution) {
         const providers = [
             ['authority', this.authority],
             ['approval', this.approval],
@@ -298,6 +391,7 @@ export class ExecutionAuthorityService {
             try {
                 result = await provider.verify({
                     ...input,
+                    ...(attribution ? { attribution: clone(attribution) } : {}),
                     check,
                     phase,
                     expectedRevision: expectedRevisions?.[check],
@@ -345,6 +439,7 @@ export class ExecutionAuthorityService {
             scopeId: input.scopeId,
             issuedAt: now.toISOString(),
             expiresAt: new Date(earliestExpiration).toISOString(),
+            ...(attribution ? { attribution: clone(attribution) } : {}),
             checks: Object.fromEntries(normalizedChecks.map(({ record, fencingToken, expiresAt }) => [record.check, {
                     revision: record.revision,
                     fencingToken: fencingToken,
@@ -353,13 +448,11 @@ export class ExecutionAuthorityService {
         };
         return { checks, capability };
     }
-    handleExisting(intent, payloadDigest) {
-        if (intent.payloadDigest !== payloadDigest) {
-            throw new ExecutionAuthorityError('operation_conflict', `Operation ${intent.operationId} was already used with a different payload`);
-        }
+    handleExisting(intent, payloadDigest, attribution) {
+        assertSameRequest(intent, payloadDigest, attribution);
         if (intent.phase === 'started' && intent.effect.status === 'started') {
             return {
-                intent: clone(intent),
+                intent: publicIntent(intent),
                 effect: { operationId: intent.operationId, status: 'started' },
                 replayed: true,
             };
@@ -371,6 +464,36 @@ export class ExecutionAuthorityService {
         }
         throw new ExecutionAuthorityError('recovery_required', `Operation ${intent.operationId} requires reconciliation before another attempt`);
     }
+    replayRegistration(intent, payloadDigest, attribution) {
+        assertSameRequest(intent, payloadDigest, attribution);
+        const grant = intent.capability?.grant;
+        const replayable = intent.phase === 'registered' || intent.phase === 'started' || intent.phase === 'unknown';
+        if (replayable && grant && intent.capability) {
+            if (intent.phase === 'registered' && Date.parse(grant.expiresAt) <= this.now().getTime()) {
+                throw new ExecutionAuthorityError('capability_expired', `The permit for operation ${intent.operationId} has expired`);
+            }
+            return {
+                intent: publicIntent(intent),
+                capability: clone(grant),
+                capabilityDigest: intent.capability.digest,
+                replayed: true,
+            };
+        }
+        if (intent.phase === 'rejected' && intent.failure)
+            throw errorFromFailure(intent.failure);
+        throw new ExecutionAuthorityError('recovery_required', `Operation ${intent.operationId} requires reconciliation before another attempt`);
+    }
+    /** Store failures are never success and never switch to another ledger. */
+    async storeCall(call) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (error instanceof ExecutionAuthorityError)
+                throw error;
+            throw new ExecutionAuthorityError('store_unavailable', 'Execution intent store is unavailable');
+        }
+    }
     now() {
         const now = this.clock();
         if (!(now instanceof Date) || !Number.isFinite(now.getTime()))
@@ -378,6 +501,47 @@ export class ExecutionAuthorityService {
         return new Date(now);
     }
 }
+/** The default store: a JSON sidecar under the local SSOT lock. */
+export function createSidecarExecutionIntentStore(options) {
+    assertText(options?.dataDir, 'dataDir');
+    const dataDir = options.dataDir;
+    const sidecarPath = options.sidecarPath ?? defaultSidecarPath;
+    assertSidecarPath(sidecarPath);
+    const findIndex = (ledger, key) => ledger.intents
+        .findIndex((candidate) => candidate.tenantId === key.tenantId && candidate.operationId === key.operationId);
+    return {
+        async initialize() {
+            await initializePersonalOs(dataDir);
+        },
+        async read(key) {
+            const ledger = parseLedger(await readPersonalOsSidecar(dataDir, sidecarPath));
+            const index = findIndex(ledger, key);
+            return index < 0 ? undefined : clone(ledger.intents[index]);
+        },
+        async insert(intent) {
+            return mutatePersonalOsWithSidecar(dataDir, sidecarPath, async (current, sidecarContent) => {
+                const ledger = parseLedger(sidecarContent);
+                const index = findIndex(ledger, intent);
+                if (index >= 0) {
+                    return { next: current, sidecarContent: serializeLedger(ledger), result: { intent: clone(ledger.intents[index]), created: false } };
+                }
+                ledger.intents.push(clone(intent));
+                return { next: current, sidecarContent: serializeLedger(ledger), result: { intent: clone(intent), created: true } };
+            });
+        },
+        async update(key, mutate) {
+            return mutatePersonalOsWithSidecar(dataDir, sidecarPath, async (current, sidecarContent) => {
+                const ledger = parseLedger(sidecarContent);
+                const index = findIndex(ledger, key);
+                if (index < 0)
+                    return { next: current, sidecarContent: serializeLedger(ledger), result: undefined };
+                const next = mutate(clone(ledger.intents[index]));
+                ledger.intents[index] = clone(next);
+                return { next: current, sidecarContent: serializeLedger(ledger), result: clone(next) };
+            });
+        },
+    };
+}
 /**
  * Binds the existing reservation store to the execution port without calling
  * it from inside the execution sidecar transaction. The store remains the
@@ -478,6 +642,61 @@ function normalizeInput(input) {
         problem,
     };
 }
+const attributionModes = ['person', 'delegated_service', 'service'];
+/** Enforces who may appear in which role; a service never passes as the person. */
+function normalizeAttribution(value, principal) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        throw new ExecutionAuthorityError('validation_error', 'attribution must be an object');
+    const known = new Set(['mode', 'servicePrincipal', 'delegationRef', 'correlationId']);
+    if (Object.keys(value).some((key) => !known.has(key))) {
+        throw new ExecutionAuthorityError('validation_error', 'attribution contains an unknown field');
+    }
+    if (!attributionModes.includes(value.mode))
+        throw new ExecutionAuthorityError('validation_error', 'attribution.mode is invalid');
+    for (const field of ['servicePrincipal', 'delegationRef', 'correlationId']) {
+        if (value[field] !== undefined)
+            assertText(value[field], `attribution.${field}`);
+    }
+    if (value.mode === 'person') {
+        if (value.servicePrincipal !== undefined || value.delegationRef !== undefined) {
+            throw new ExecutionAuthorityError('validation_error', 'A person attribution cannot carry a service principal or delegation');
+        }
+    }
+    else {
+        if (value.servicePrincipal === undefined || value.delegationRef === undefined) {
+            throw new ExecutionAuthorityError('validation_error', `A ${value.mode} attribution requires servicePrincipal and delegationRef`);
+        }
+        if (value.mode === 'delegated_service' && value.servicePrincipal === principal) {
+            throw new ExecutionAuthorityError('validation_error', 'A delegated service must differ from the principal it acts for');
+        }
+        if (value.mode === 'service' && value.servicePrincipal !== principal) {
+            throw new ExecutionAuthorityError('validation_error', 'A service attribution must name the service as the principal');
+        }
+    }
+    return {
+        mode: value.mode,
+        ...(value.servicePrincipal !== undefined ? { servicePrincipal: value.servicePrincipal } : {}),
+        ...(value.delegationRef !== undefined ? { delegationRef: value.delegationRef } : {}),
+        ...(value.correlationId !== undefined ? { correlationId: value.correlationId } : {}),
+    };
+}
+function assertSameRequest(intent, payloadDigest, attribution) {
+    if (intent.payloadDigest !== payloadDigest || digest(intent.attribution ?? null) !== digest(attribution ?? null)) {
+        throw new ExecutionAuthorityError('operation_conflict', `Operation ${intent.operationId} was already used with a different payload or attribution`);
+    }
+}
+/** Readers see the permit's expiry and digest, never its fencing tokens. */
+function publicIntent(intent) {
+    const next = clone(intent);
+    if (next.capability)
+        next.capability = { expiresAt: next.capability.expiresAt, digest: next.capability.digest };
+    return next;
+}
+function intentKey(input) {
+    return { tenantId: input.tenantId, operationId: input.operationId };
+}
 function normalizeLookup(input) {
     if (!input || typeof input !== 'object')
         throw new ExecutionAuthorityError('validation_error', 'execution lookup is required');
@@ -587,7 +806,7 @@ function validateStoredIntent(value) {
         || !isText(value.principal)
         || !isText(value.scopeId)
         || !isText(value.payloadDigest)
-        || !['recovery_required', 'reservation_marked', 'started', 'unknown', 'rejected'].includes(value.phase)
+        || !['recovery_required', 'reservation_marked', 'registered', 'started', 'unknown', 'rejected'].includes(value.phase)
         || !['not_started', 'started', 'unknown'].includes(value.reservationMark)
         || !isRecord(value.effect)
         || value.effect.operationId !== value.operationId
@@ -600,6 +819,20 @@ function validateStoredIntent(value) {
         || !isText(value.updatedAt)) {
         throw new ExecutionAuthorityError('ledger_invalid', 'Execution intent ledger contains an invalid record');
     }
+    if (value.attribution !== undefined) {
+        try {
+            normalizeAttribution(value.attribution, value.principal);
+        }
+        catch {
+            throw new ExecutionAuthorityError('ledger_invalid', 'Execution intent ledger contains an invalid attribution');
+        }
+    }
+    if (value.capability !== undefined && (!isRecord(value.capability)
+        || !isText(value.capability.expiresAt)
+        || !isText(value.capability.digest)
+        || (value.capability.grant !== undefined && (!isRecord(value.capability.grant) || value.capability.grant.kind !== 'execution-start')))) {
+        throw new ExecutionAuthorityError('ledger_invalid', 'Execution intent ledger contains an invalid capability');
+    }
 }
 function serializeLedger(ledger) {
     return `${JSON.stringify(ledger, null, 2)}\n`;

package/dist/judgment-value-proof.d.ts

@@ -14,12 +14,27 @@ export interface JudgmentValueProofArtifactRef {
 }
 /** Which part of the organization's judgment a basis came from. Absent means not recorded. */
 export type JudgmentValueProofBasisLayer = 'philosophy' | 'objective' | 'world_model' | 'method' | 'constraint' | 'other';
+/**
+ * A source that the local Web host can read and open.  This is deliberately
+ * not a URL: the host owns the reader and keeps navigation same-origin.
+ */
+export type JudgmentValueProofBasisSourceKind = 'local_graph';
+export type JudgmentValueProofBasisSourceEntityType = 'person' | 'org' | 'project' | 'decision';
+export interface JudgmentValueProofBasisSource {
+    kind: JudgmentValueProofBasisSourceKind;
+    entity_id: string;
+    entity_type: JudgmentValueProofBasisSourceEntityType;
+    version?: string | null;
+    digest?: string | null;
+}
 export interface JudgmentValueProofBasis {
     entity_id: string;
     application: string;
     layer?: JudgmentValueProofBasisLayer;
     /** Version of the referenced entity used for this judgment. */
     version?: string | null;
+    /** Optional, typed read contract for a source-bearing proof. */
+    source?: JudgmentValueProofBasisSource | null;
 }
 export interface JudgmentValueProofInheritanceSource {
     kind: 'judgment' | 'method' | 'decision' | 'other';