@fabricorg/platform-host 2.0.1 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +29 -0
- package/MIGRATION-2-IDEMPOTENCY.md +32 -0
- package/README.md +26 -5
- package/dist/index.cjs +244 -33
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +86 -8
- package/dist/index.d.ts +86 -8
- package/dist/index.js +242 -35
- package/dist/index.js.map +1 -1
- package/package.json +4 -3
package/dist/index.d.cts
CHANGED
|
@@ -1,7 +1,39 @@
|
|
|
1
|
-
import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
|
|
1
|
+
import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ModuleRegistry, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
|
|
2
2
|
|
|
3
3
|
/** Durable Host lifecycle generation, independent from the npm package version. */
|
|
4
4
|
declare const PLATFORM_HOST_CONTRACT_VERSION: 2;
|
|
5
|
+
type InvocationSource = "ui" | "api" | "agent" | "worker" | "system" | (string & {});
|
|
6
|
+
type NamespacedAttributes = Record<string, string>;
|
|
7
|
+
interface InvocationProvenance {
|
|
8
|
+
source: InvocationSource;
|
|
9
|
+
correlationId: string;
|
|
10
|
+
causationId?: string;
|
|
11
|
+
traceAttributes?: NamespacedAttributes;
|
|
12
|
+
auditAttributes?: NamespacedAttributes;
|
|
13
|
+
}
|
|
14
|
+
type AuthorizationGoverningMoment = "capture" | "execution" | "both";
|
|
15
|
+
interface AuthorizationBinding {
|
|
16
|
+
id: string;
|
|
17
|
+
tenantId: string;
|
|
18
|
+
actorId: string;
|
|
19
|
+
actionId: string;
|
|
20
|
+
parameterDigest: string;
|
|
21
|
+
resourceScope?: string;
|
|
22
|
+
capturedAt: string;
|
|
23
|
+
expiresAt?: string;
|
|
24
|
+
governingMoment: AuthorizationGoverningMoment;
|
|
25
|
+
}
|
|
26
|
+
interface IdempotencyConflict {
|
|
27
|
+
code: "IDEMPOTENCY_CONFLICT";
|
|
28
|
+
idempotencyKey: string;
|
|
29
|
+
existingInvocationId: string;
|
|
30
|
+
reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters">;
|
|
31
|
+
}
|
|
32
|
+
declare class IdempotencyConflictError extends Error {
|
|
33
|
+
readonly conflict: IdempotencyConflict;
|
|
34
|
+
readonly code: "IDEMPOTENCY_CONFLICT";
|
|
35
|
+
constructor(conflict: IdempotencyConflict);
|
|
36
|
+
}
|
|
5
37
|
interface PendingAssetEvent {
|
|
6
38
|
eventType: string;
|
|
7
39
|
subjectType: string;
|
|
@@ -23,6 +55,14 @@ interface ActionInvocationRecord {
|
|
|
23
55
|
correlationId: string;
|
|
24
56
|
causationId?: string;
|
|
25
57
|
idempotencyKey?: string;
|
|
58
|
+
parameterDigest?: string;
|
|
59
|
+
parameterDigestAlgorithm?: "fabric-canonical-json-sha256-v1";
|
|
60
|
+
idempotencyActorId?: string;
|
|
61
|
+
idempotencyAuthorizationBindingId?: string;
|
|
62
|
+
provenance?: Omit<InvocationProvenance, "traceAttributes">;
|
|
63
|
+
authorizationBinding?: AuthorizationBinding;
|
|
64
|
+
executionReason?: ActionExecutionReason;
|
|
65
|
+
authorizationReconciliation?: AuthorizationReconciliationOutcome;
|
|
26
66
|
/** Opaque, non-secret reference used to revalidate delegated execution authority. */
|
|
27
67
|
authorizationBindingId?: string;
|
|
28
68
|
attemptCount: number;
|
|
@@ -40,6 +80,14 @@ interface ActionInvocationRecord {
|
|
|
40
80
|
createdAt: Date;
|
|
41
81
|
updatedAt: Date;
|
|
42
82
|
}
|
|
83
|
+
interface AuthorizationReconciliationOutcome {
|
|
84
|
+
kind: "authorization_expired" | "authorization_denied" | "authorization_missing_capture_evidence";
|
|
85
|
+
governingMoment: AuthorizationGoverningMoment;
|
|
86
|
+
executionReason: ActionExecutionReason;
|
|
87
|
+
authorizationBindingId?: string;
|
|
88
|
+
provenance?: Omit<InvocationProvenance, "traceAttributes">;
|
|
89
|
+
message: string;
|
|
90
|
+
}
|
|
43
91
|
interface HitlDecisionEvidence {
|
|
44
92
|
route: AgentActionRoute;
|
|
45
93
|
riskTier: AgentActionRiskTier;
|
|
@@ -111,7 +159,7 @@ interface PlatformHostStore<TDb> {
|
|
|
111
159
|
transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
|
|
112
160
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
113
161
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
114
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
162
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
115
163
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
116
164
|
createAdapterInvocation(record: AdapterInvocationRecord): Promise<void>;
|
|
117
165
|
getAdapterInvocation(id: string): Promise<AdapterInvocationRecord | undefined>;
|
|
@@ -134,7 +182,7 @@ interface PlatformHostMutationTransaction<TDb> {
|
|
|
134
182
|
appendEventWithOutbox?(event: AssetEventEnvelope, metadata: OutboxEventMetadata): Promise<void>;
|
|
135
183
|
nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
|
|
136
184
|
listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
|
|
137
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
185
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
138
186
|
}
|
|
139
187
|
type OutboxStatus = "pending" | "published" | "dead_letter";
|
|
140
188
|
type EventPayloadClassification = "public" | "internal" | "confidential" | "restricted";
|
|
@@ -142,6 +190,7 @@ interface OutboxEventMetadata {
|
|
|
142
190
|
producerModuleVersion: string;
|
|
143
191
|
payloadClassification: EventPayloadClassification;
|
|
144
192
|
traceContext?: Record<string, string>;
|
|
193
|
+
includeProvenance?: boolean;
|
|
145
194
|
}
|
|
146
195
|
interface EnterpriseEventEnvelope {
|
|
147
196
|
eventId: string;
|
|
@@ -160,6 +209,10 @@ interface EnterpriseEventEnvelope {
|
|
|
160
209
|
producerModuleVersion: string;
|
|
161
210
|
payloadClassification: EventPayloadClassification;
|
|
162
211
|
traceContext?: Record<string, string>;
|
|
212
|
+
provenance?: {
|
|
213
|
+
source: InvocationSource;
|
|
214
|
+
auditAttributes?: NamespacedAttributes;
|
|
215
|
+
};
|
|
163
216
|
payload: unknown;
|
|
164
217
|
}
|
|
165
218
|
interface OutboxRecord {
|
|
@@ -275,7 +328,8 @@ interface ActionAuthorizationInput {
|
|
|
275
328
|
actorId: string;
|
|
276
329
|
actorType: ActorType;
|
|
277
330
|
}
|
|
278
|
-
type
|
|
331
|
+
type KnownActionExecutionReason = "initial" | "approval_resume" | "recovery" | "offline_replay";
|
|
332
|
+
type ActionExecutionReason = KnownActionExecutionReason | (string & {});
|
|
279
333
|
/**
|
|
280
334
|
* Trusted execution-boundary authorization input.
|
|
281
335
|
*
|
|
@@ -323,10 +377,13 @@ interface SubmitActionInput {
|
|
|
323
377
|
actorType: ActorType;
|
|
324
378
|
correlationId?: string;
|
|
325
379
|
causationId?: string;
|
|
326
|
-
|
|
380
|
+
provenance?: InvocationProvenance;
|
|
381
|
+
executionReason?: Extract<KnownActionExecutionReason, "initial" | "offline_replay">;
|
|
382
|
+
/** Stable logical command key. Reusing it returns the original invocation without re-dispatch. */
|
|
327
383
|
idempotencyKey?: string;
|
|
328
384
|
/** Opaque, non-secret authorization/admission reference persisted with the invocation. */
|
|
329
385
|
authorizationBindingId?: string;
|
|
386
|
+
authorizationBinding?: AuthorizationBinding;
|
|
330
387
|
}
|
|
331
388
|
interface SubmitActionResult {
|
|
332
389
|
actionInvocationId: string;
|
|
@@ -335,6 +392,7 @@ interface SubmitActionResult {
|
|
|
335
392
|
runId?: string;
|
|
336
393
|
result?: Record<string, unknown>;
|
|
337
394
|
error?: string;
|
|
395
|
+
reconciliation?: AuthorizationReconciliationOutcome;
|
|
338
396
|
hitlRoute?: AgentActionRoute;
|
|
339
397
|
hitlRiskTier?: AgentActionRiskTier;
|
|
340
398
|
}
|
|
@@ -343,6 +401,7 @@ interface ExecuteActionResult {
|
|
|
343
401
|
status: ActionStatus;
|
|
344
402
|
result?: Record<string, unknown>;
|
|
345
403
|
error?: string;
|
|
404
|
+
reconciliation?: AuthorizationReconciliationOutcome;
|
|
346
405
|
hitlRoute?: AgentActionRoute;
|
|
347
406
|
hitlRiskTier?: AgentActionRiskTier;
|
|
348
407
|
}
|
|
@@ -372,15 +431,30 @@ interface PlatformActionWorkerCycleResult {
|
|
|
372
431
|
interface PlatformHostOptions<TDb> {
|
|
373
432
|
store: PlatformHostStore<TDb>;
|
|
374
433
|
authorization: PlatformHostAuthorization;
|
|
434
|
+
/** Preferred explicit catalog assembled from this runtime's Fabric modules. */
|
|
435
|
+
registry?: Pick<ModuleRegistry<TDb>, "resolveAction" | "resolvePolicy" | "resolveStateMachine">;
|
|
375
436
|
/** Resolve vertical- or runtime-local actions without mutating the process-wide registry. */
|
|
376
437
|
resolveAction?: (actionId: ActionId) => ActionDefinition<TDb> | undefined;
|
|
377
438
|
adapters?: readonly AdapterImplementation[];
|
|
378
439
|
dispatcher?: PlatformActionDispatcher;
|
|
379
440
|
services?: FabricRuntimeServices;
|
|
441
|
+
idempotency?: {
|
|
442
|
+
conflictMode?: "audit-only" | "enforce";
|
|
443
|
+
onConflict?(conflict: IdempotencyConflict): void;
|
|
444
|
+
onLegacyRecord?(invocation: ActionInvocationRecord): void;
|
|
445
|
+
};
|
|
446
|
+
provenance?: {
|
|
447
|
+
auditAttributeAllowlist?: readonly string[];
|
|
448
|
+
maxAttributes?: number;
|
|
449
|
+
maxValueLength?: number;
|
|
450
|
+
redactAuditAttributes?(attributes: NamespacedAttributes): NamespacedAttributes;
|
|
451
|
+
onTrace?(provenance: InvocationProvenance): void;
|
|
452
|
+
};
|
|
380
453
|
/** Requires an outbox-capable store; every canonical event is then appended with delivery state. */
|
|
381
454
|
outbox?: {
|
|
382
455
|
producerModuleVersion(actionId: ActionId, actionVersion: number): string;
|
|
383
456
|
classifyPayload(event: AssetEventEnvelope): EventPayloadClassification;
|
|
457
|
+
includeProvenance?(event: AssetEventEnvelope, classification: EventPayloadClassification): boolean;
|
|
384
458
|
traceContext?(event: AssetEventEnvelope): Record<string, string> | undefined;
|
|
385
459
|
/** Host lifecycle events are excluded by default; opt in only after making their payload audit-safe. */
|
|
386
460
|
shouldPublish?(event: AssetEventEnvelope): boolean;
|
|
@@ -457,7 +531,7 @@ declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostSto
|
|
|
457
531
|
private runTransactionWithEvents;
|
|
458
532
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
459
533
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
460
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
534
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
461
535
|
recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
|
|
462
536
|
beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
|
|
463
537
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
@@ -553,7 +627,7 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
|
|
|
553
627
|
transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
|
|
554
628
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
555
629
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
556
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
630
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
557
631
|
recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
|
|
558
632
|
beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
|
|
559
633
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
@@ -593,6 +667,10 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
|
|
|
593
667
|
listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
|
|
594
668
|
}
|
|
595
669
|
|
|
670
|
+
declare const PARAMETER_DIGEST_ALGORITHM: "fabric-canonical-json-sha256-v1";
|
|
671
|
+
declare function canonicalJson(value: unknown): string;
|
|
672
|
+
declare function digestParameters(parameters: unknown): string;
|
|
673
|
+
|
|
596
674
|
/**
|
|
597
675
|
* Durable store-backed dispatch: the pending invocation row is the queue item.
|
|
598
676
|
* Repeated dispatches are safe because the workflow id is stable per invocation.
|
|
@@ -603,4 +681,4 @@ declare function runPlatformActionWorkerCycle<TDb>(options: PlatformActionWorker
|
|
|
603
681
|
/** Poll until aborted. Each iteration is bounded and waits without busy-spinning. */
|
|
604
682
|
declare function runPlatformActionWorker<TDb>(options: PlatformActionWorkerOptions<TDb>): Promise<void>;
|
|
605
683
|
|
|
606
|
-
export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PLATFORM_HOST_CONTRACT_VERSION, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, type PolicyObligationRecord, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
|
|
684
|
+
export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type AuthorizationBinding, type AuthorizationGoverningMoment, type AuthorizationReconciliationOutcome, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type IdempotencyConflict, IdempotencyConflictError, type InvocationProvenance, type InvocationSource, type KnownActionExecutionReason, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type NamespacedAttributes, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PARAMETER_DIGEST_ALGORITHM, PLATFORM_HOST_CONTRACT_VERSION, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, type PolicyObligationRecord, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, canonicalJson, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, digestParameters, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,39 @@
|
|
|
1
|
-
import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
|
|
1
|
+
import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, MutationFootprint, ExecutionPrincipal, GovernanceRuntimeEvidence, PolicyOutcome, AssetEventEnvelope, ExecutionAttestation, ExternalReconciliation, PolicyObligation, PolicyObligationStatus, ModuleRegistry, ActionDefinition, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, MutationGovernanceResolver, RuntimePolicyDefinition } from '@fabricorg/platform';
|
|
2
2
|
|
|
3
3
|
/** Durable Host lifecycle generation, independent from the npm package version. */
|
|
4
4
|
declare const PLATFORM_HOST_CONTRACT_VERSION: 2;
|
|
5
|
+
type InvocationSource = "ui" | "api" | "agent" | "worker" | "system" | (string & {});
|
|
6
|
+
type NamespacedAttributes = Record<string, string>;
|
|
7
|
+
interface InvocationProvenance {
|
|
8
|
+
source: InvocationSource;
|
|
9
|
+
correlationId: string;
|
|
10
|
+
causationId?: string;
|
|
11
|
+
traceAttributes?: NamespacedAttributes;
|
|
12
|
+
auditAttributes?: NamespacedAttributes;
|
|
13
|
+
}
|
|
14
|
+
type AuthorizationGoverningMoment = "capture" | "execution" | "both";
|
|
15
|
+
interface AuthorizationBinding {
|
|
16
|
+
id: string;
|
|
17
|
+
tenantId: string;
|
|
18
|
+
actorId: string;
|
|
19
|
+
actionId: string;
|
|
20
|
+
parameterDigest: string;
|
|
21
|
+
resourceScope?: string;
|
|
22
|
+
capturedAt: string;
|
|
23
|
+
expiresAt?: string;
|
|
24
|
+
governingMoment: AuthorizationGoverningMoment;
|
|
25
|
+
}
|
|
26
|
+
interface IdempotencyConflict {
|
|
27
|
+
code: "IDEMPOTENCY_CONFLICT";
|
|
28
|
+
idempotencyKey: string;
|
|
29
|
+
existingInvocationId: string;
|
|
30
|
+
reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters">;
|
|
31
|
+
}
|
|
32
|
+
declare class IdempotencyConflictError extends Error {
|
|
33
|
+
readonly conflict: IdempotencyConflict;
|
|
34
|
+
readonly code: "IDEMPOTENCY_CONFLICT";
|
|
35
|
+
constructor(conflict: IdempotencyConflict);
|
|
36
|
+
}
|
|
5
37
|
interface PendingAssetEvent {
|
|
6
38
|
eventType: string;
|
|
7
39
|
subjectType: string;
|
|
@@ -23,6 +55,14 @@ interface ActionInvocationRecord {
|
|
|
23
55
|
correlationId: string;
|
|
24
56
|
causationId?: string;
|
|
25
57
|
idempotencyKey?: string;
|
|
58
|
+
parameterDigest?: string;
|
|
59
|
+
parameterDigestAlgorithm?: "fabric-canonical-json-sha256-v1";
|
|
60
|
+
idempotencyActorId?: string;
|
|
61
|
+
idempotencyAuthorizationBindingId?: string;
|
|
62
|
+
provenance?: Omit<InvocationProvenance, "traceAttributes">;
|
|
63
|
+
authorizationBinding?: AuthorizationBinding;
|
|
64
|
+
executionReason?: ActionExecutionReason;
|
|
65
|
+
authorizationReconciliation?: AuthorizationReconciliationOutcome;
|
|
26
66
|
/** Opaque, non-secret reference used to revalidate delegated execution authority. */
|
|
27
67
|
authorizationBindingId?: string;
|
|
28
68
|
attemptCount: number;
|
|
@@ -40,6 +80,14 @@ interface ActionInvocationRecord {
|
|
|
40
80
|
createdAt: Date;
|
|
41
81
|
updatedAt: Date;
|
|
42
82
|
}
|
|
83
|
+
interface AuthorizationReconciliationOutcome {
|
|
84
|
+
kind: "authorization_expired" | "authorization_denied" | "authorization_missing_capture_evidence";
|
|
85
|
+
governingMoment: AuthorizationGoverningMoment;
|
|
86
|
+
executionReason: ActionExecutionReason;
|
|
87
|
+
authorizationBindingId?: string;
|
|
88
|
+
provenance?: Omit<InvocationProvenance, "traceAttributes">;
|
|
89
|
+
message: string;
|
|
90
|
+
}
|
|
43
91
|
interface HitlDecisionEvidence {
|
|
44
92
|
route: AgentActionRoute;
|
|
45
93
|
riskTier: AgentActionRiskTier;
|
|
@@ -111,7 +159,7 @@ interface PlatformHostStore<TDb> {
|
|
|
111
159
|
transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
|
|
112
160
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
113
161
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
114
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
162
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
115
163
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
116
164
|
createAdapterInvocation(record: AdapterInvocationRecord): Promise<void>;
|
|
117
165
|
getAdapterInvocation(id: string): Promise<AdapterInvocationRecord | undefined>;
|
|
@@ -134,7 +182,7 @@ interface PlatformHostMutationTransaction<TDb> {
|
|
|
134
182
|
appendEventWithOutbox?(event: AssetEventEnvelope, metadata: OutboxEventMetadata): Promise<void>;
|
|
135
183
|
nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
|
|
136
184
|
listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
|
|
137
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
185
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
138
186
|
}
|
|
139
187
|
type OutboxStatus = "pending" | "published" | "dead_letter";
|
|
140
188
|
type EventPayloadClassification = "public" | "internal" | "confidential" | "restricted";
|
|
@@ -142,6 +190,7 @@ interface OutboxEventMetadata {
|
|
|
142
190
|
producerModuleVersion: string;
|
|
143
191
|
payloadClassification: EventPayloadClassification;
|
|
144
192
|
traceContext?: Record<string, string>;
|
|
193
|
+
includeProvenance?: boolean;
|
|
145
194
|
}
|
|
146
195
|
interface EnterpriseEventEnvelope {
|
|
147
196
|
eventId: string;
|
|
@@ -160,6 +209,10 @@ interface EnterpriseEventEnvelope {
|
|
|
160
209
|
producerModuleVersion: string;
|
|
161
210
|
payloadClassification: EventPayloadClassification;
|
|
162
211
|
traceContext?: Record<string, string>;
|
|
212
|
+
provenance?: {
|
|
213
|
+
source: InvocationSource;
|
|
214
|
+
auditAttributes?: NamespacedAttributes;
|
|
215
|
+
};
|
|
163
216
|
payload: unknown;
|
|
164
217
|
}
|
|
165
218
|
interface OutboxRecord {
|
|
@@ -275,7 +328,8 @@ interface ActionAuthorizationInput {
|
|
|
275
328
|
actorId: string;
|
|
276
329
|
actorType: ActorType;
|
|
277
330
|
}
|
|
278
|
-
type
|
|
331
|
+
type KnownActionExecutionReason = "initial" | "approval_resume" | "recovery" | "offline_replay";
|
|
332
|
+
type ActionExecutionReason = KnownActionExecutionReason | (string & {});
|
|
279
333
|
/**
|
|
280
334
|
* Trusted execution-boundary authorization input.
|
|
281
335
|
*
|
|
@@ -323,10 +377,13 @@ interface SubmitActionInput {
|
|
|
323
377
|
actorType: ActorType;
|
|
324
378
|
correlationId?: string;
|
|
325
379
|
causationId?: string;
|
|
326
|
-
|
|
380
|
+
provenance?: InvocationProvenance;
|
|
381
|
+
executionReason?: Extract<KnownActionExecutionReason, "initial" | "offline_replay">;
|
|
382
|
+
/** Stable logical command key. Reusing it returns the original invocation without re-dispatch. */
|
|
327
383
|
idempotencyKey?: string;
|
|
328
384
|
/** Opaque, non-secret authorization/admission reference persisted with the invocation. */
|
|
329
385
|
authorizationBindingId?: string;
|
|
386
|
+
authorizationBinding?: AuthorizationBinding;
|
|
330
387
|
}
|
|
331
388
|
interface SubmitActionResult {
|
|
332
389
|
actionInvocationId: string;
|
|
@@ -335,6 +392,7 @@ interface SubmitActionResult {
|
|
|
335
392
|
runId?: string;
|
|
336
393
|
result?: Record<string, unknown>;
|
|
337
394
|
error?: string;
|
|
395
|
+
reconciliation?: AuthorizationReconciliationOutcome;
|
|
338
396
|
hitlRoute?: AgentActionRoute;
|
|
339
397
|
hitlRiskTier?: AgentActionRiskTier;
|
|
340
398
|
}
|
|
@@ -343,6 +401,7 @@ interface ExecuteActionResult {
|
|
|
343
401
|
status: ActionStatus;
|
|
344
402
|
result?: Record<string, unknown>;
|
|
345
403
|
error?: string;
|
|
404
|
+
reconciliation?: AuthorizationReconciliationOutcome;
|
|
346
405
|
hitlRoute?: AgentActionRoute;
|
|
347
406
|
hitlRiskTier?: AgentActionRiskTier;
|
|
348
407
|
}
|
|
@@ -372,15 +431,30 @@ interface PlatformActionWorkerCycleResult {
|
|
|
372
431
|
interface PlatformHostOptions<TDb> {
|
|
373
432
|
store: PlatformHostStore<TDb>;
|
|
374
433
|
authorization: PlatformHostAuthorization;
|
|
434
|
+
/** Preferred explicit catalog assembled from this runtime's Fabric modules. */
|
|
435
|
+
registry?: Pick<ModuleRegistry<TDb>, "resolveAction" | "resolvePolicy" | "resolveStateMachine">;
|
|
375
436
|
/** Resolve vertical- or runtime-local actions without mutating the process-wide registry. */
|
|
376
437
|
resolveAction?: (actionId: ActionId) => ActionDefinition<TDb> | undefined;
|
|
377
438
|
adapters?: readonly AdapterImplementation[];
|
|
378
439
|
dispatcher?: PlatformActionDispatcher;
|
|
379
440
|
services?: FabricRuntimeServices;
|
|
441
|
+
idempotency?: {
|
|
442
|
+
conflictMode?: "audit-only" | "enforce";
|
|
443
|
+
onConflict?(conflict: IdempotencyConflict): void;
|
|
444
|
+
onLegacyRecord?(invocation: ActionInvocationRecord): void;
|
|
445
|
+
};
|
|
446
|
+
provenance?: {
|
|
447
|
+
auditAttributeAllowlist?: readonly string[];
|
|
448
|
+
maxAttributes?: number;
|
|
449
|
+
maxValueLength?: number;
|
|
450
|
+
redactAuditAttributes?(attributes: NamespacedAttributes): NamespacedAttributes;
|
|
451
|
+
onTrace?(provenance: InvocationProvenance): void;
|
|
452
|
+
};
|
|
380
453
|
/** Requires an outbox-capable store; every canonical event is then appended with delivery state. */
|
|
381
454
|
outbox?: {
|
|
382
455
|
producerModuleVersion(actionId: ActionId, actionVersion: number): string;
|
|
383
456
|
classifyPayload(event: AssetEventEnvelope): EventPayloadClassification;
|
|
457
|
+
includeProvenance?(event: AssetEventEnvelope, classification: EventPayloadClassification): boolean;
|
|
384
458
|
traceContext?(event: AssetEventEnvelope): Record<string, string> | undefined;
|
|
385
459
|
/** Host lifecycle events are excluded by default; opt in only after making their payload audit-safe. */
|
|
386
460
|
shouldPublish?(event: AssetEventEnvelope): boolean;
|
|
@@ -457,7 +531,7 @@ declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostSto
|
|
|
457
531
|
private runTransactionWithEvents;
|
|
458
532
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
459
533
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
460
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
534
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
461
535
|
recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
|
|
462
536
|
beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
|
|
463
537
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
@@ -553,7 +627,7 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
|
|
|
553
627
|
transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
|
|
554
628
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
555
629
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
556
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
630
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
557
631
|
recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
|
|
558
632
|
beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
|
|
559
633
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
@@ -593,6 +667,10 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
|
|
|
593
667
|
listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
|
|
594
668
|
}
|
|
595
669
|
|
|
670
|
+
declare const PARAMETER_DIGEST_ALGORITHM: "fabric-canonical-json-sha256-v1";
|
|
671
|
+
declare function canonicalJson(value: unknown): string;
|
|
672
|
+
declare function digestParameters(parameters: unknown): string;
|
|
673
|
+
|
|
596
674
|
/**
|
|
597
675
|
* Durable store-backed dispatch: the pending invocation row is the queue item.
|
|
598
676
|
* Repeated dispatches are safe because the workflow id is stable per invocation.
|
|
@@ -603,4 +681,4 @@ declare function runPlatformActionWorkerCycle<TDb>(options: PlatformActionWorker
|
|
|
603
681
|
/** Poll until aborted. Each iteration is bounded and waits without busy-spinning. */
|
|
604
682
|
declare function runPlatformActionWorker<TDb>(options: PlatformActionWorkerOptions<TDb>): Promise<void>;
|
|
605
683
|
|
|
606
|
-
export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PLATFORM_HOST_CONTRACT_VERSION, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, type PolicyObligationRecord, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
|
|
684
|
+
export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionExecutionAuthorizationInput, type ActionExecutionReason, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type AtomicMutationPlatformHostStore, type AuthorizationBinding, type AuthorizationGoverningMoment, type AuthorizationReconciliationOutcome, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type ClaimOutboxInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type EnterpriseEventEnvelope, type EnterpriseEventPublisher, type EventPayloadClassification, type ExecuteActionResult, type ExecuteInvocationOptions, type ExecutionAttestationRecord, type ExternalReconciliationRecord, type GovernancePlatformHostStore, type GovernedActionHost, type HitlDecisionEvidence, type IdempotencyConflict, IdempotencyConflictError, type InvocationProvenance, type InvocationSource, type KnownActionExecutionReason, type ListActionInvocationsInput, MemoryPlatformHostStore, type MemoryPlatformHostTransactionProvider, type NamespacedAttributes, type OutboxEventMetadata, type OutboxPlatformHostStore, type OutboxRecord, type OutboxRelayOptions, type OutboxRelayResult, type OutboxStatus, PARAMETER_DIGEST_ALGORITHM, PLATFORM_HOST_CONTRACT_VERSION, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostMutationTransaction, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, type PolicyObligationRecord, PostgresPlatformHostStore, type PostgresPlatformHostTransactionContext, type PostgresPlatformHostTransactionProvider, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, canonicalJson, cloneOutboxRecord, createGovernedActionHost, createStoreBackedActionDispatcher, digestParameters, runOutboxRelayCycle, runPlatformActionWorker, runPlatformActionWorkerCycle, toEnterpriseEventEnvelope };
|