@fabricorg/platform-host 2.0.0 → 3.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 +35 -8
- package/MIGRATION-2-IDEMPOTENCY.md +32 -0
- package/README.md +36 -7
- package/dist/index.cjs +295 -31
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +94 -8
- package/dist/index.d.ts +94 -8
- package/dist/index.js +292 -32
- package/dist/index.js.map +1 -1
- package/package.json +4 -3
package/dist/index.d.cts
CHANGED
|
@@ -2,6 +2,38 @@ import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTie
|
|
|
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 = "sdui" | "api" | "agent" | "worker" | "system";
|
|
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
|
}
|
|
@@ -377,11 +436,26 @@ interface PlatformHostOptions<TDb> {
|
|
|
377
436
|
adapters?: readonly AdapterImplementation[];
|
|
378
437
|
dispatcher?: PlatformActionDispatcher;
|
|
379
438
|
services?: FabricRuntimeServices;
|
|
439
|
+
idempotency?: {
|
|
440
|
+
conflictMode?: "audit-only" | "enforce";
|
|
441
|
+
onConflict?(conflict: IdempotencyConflict): void;
|
|
442
|
+
onLegacyRecord?(invocation: ActionInvocationRecord): void;
|
|
443
|
+
};
|
|
444
|
+
provenance?: {
|
|
445
|
+
auditAttributeAllowlist?: readonly string[];
|
|
446
|
+
maxAttributes?: number;
|
|
447
|
+
maxValueLength?: number;
|
|
448
|
+
redactAuditAttributes?(attributes: NamespacedAttributes): NamespacedAttributes;
|
|
449
|
+
onTrace?(provenance: InvocationProvenance): void;
|
|
450
|
+
};
|
|
380
451
|
/** Requires an outbox-capable store; every canonical event is then appended with delivery state. */
|
|
381
452
|
outbox?: {
|
|
382
453
|
producerModuleVersion(actionId: ActionId, actionVersion: number): string;
|
|
383
454
|
classifyPayload(event: AssetEventEnvelope): EventPayloadClassification;
|
|
455
|
+
includeProvenance?(event: AssetEventEnvelope, classification: EventPayloadClassification): boolean;
|
|
384
456
|
traceContext?(event: AssetEventEnvelope): Record<string, string> | undefined;
|
|
457
|
+
/** Host lifecycle events are excluded by default; opt in only after making their payload audit-safe. */
|
|
458
|
+
shouldPublish?(event: AssetEventEnvelope): boolean;
|
|
385
459
|
};
|
|
386
460
|
/** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
|
|
387
461
|
hitlEvaluator?: AgentActionPolicyEvaluator;
|
|
@@ -433,8 +507,15 @@ interface GovernedActionHost {
|
|
|
433
507
|
|
|
434
508
|
declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost;
|
|
435
509
|
|
|
510
|
+
interface MemoryPlatformHostTransactionProvider<TDb> {
|
|
511
|
+
snapshot(db: TDb): TDb;
|
|
512
|
+
restore(db: TDb, snapshot: TDb): void;
|
|
513
|
+
}
|
|
436
514
|
declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb>, GovernancePlatformHostStore<TDb>, OutboxPlatformHostStore<TDb> {
|
|
437
515
|
readonly db: TDb;
|
|
516
|
+
readonly transactionalOutbox: boolean;
|
|
517
|
+
transactionWithEvents?: <TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>) => Promise<TResult>;
|
|
518
|
+
private transactionTail;
|
|
438
519
|
readonly invocations: ActionInvocationRecord[];
|
|
439
520
|
readonly policyEvaluations: PolicyEvaluationRecord[];
|
|
440
521
|
readonly adapterInvocations: AdapterInvocationRecord[];
|
|
@@ -443,11 +524,12 @@ declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostSto
|
|
|
443
524
|
readonly executionAttestations: ExecutionAttestationRecord[];
|
|
444
525
|
readonly externalReconciliations: ExternalReconciliationRecord[];
|
|
445
526
|
readonly outbox: OutboxRecord[];
|
|
446
|
-
constructor(db: TDb);
|
|
527
|
+
constructor(db: TDb, transactionProvider?: MemoryPlatformHostTransactionProvider<TDb>);
|
|
447
528
|
transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
|
|
529
|
+
private runTransactionWithEvents;
|
|
448
530
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
449
531
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
450
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
532
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
451
533
|
recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
|
|
452
534
|
beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
|
|
453
535
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
@@ -543,7 +625,7 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
|
|
|
543
625
|
transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
|
|
544
626
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
545
627
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
546
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
628
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
547
629
|
recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
|
|
548
630
|
beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
|
|
549
631
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
@@ -583,6 +665,10 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
|
|
|
583
665
|
listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
|
|
584
666
|
}
|
|
585
667
|
|
|
668
|
+
declare const PARAMETER_DIGEST_ALGORITHM: "fabric-canonical-json-sha256-v1";
|
|
669
|
+
declare function canonicalJson(value: unknown): string;
|
|
670
|
+
declare function digestParameters(parameters: unknown): string;
|
|
671
|
+
|
|
586
672
|
/**
|
|
587
673
|
* Durable store-backed dispatch: the pending invocation row is the queue item.
|
|
588
674
|
* Repeated dispatches are safe because the workflow id is stable per invocation.
|
|
@@ -593,4 +679,4 @@ declare function runPlatformActionWorkerCycle<TDb>(options: PlatformActionWorker
|
|
|
593
679
|
/** Poll until aborted. Each iteration is bounded and waits without busy-spinning. */
|
|
594
680
|
declare function runPlatformActionWorker<TDb>(options: PlatformActionWorkerOptions<TDb>): Promise<void>;
|
|
595
681
|
|
|
596
|
-
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 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 };
|
|
682
|
+
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
|
@@ -2,6 +2,38 @@ import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTie
|
|
|
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 = "sdui" | "api" | "agent" | "worker" | "system";
|
|
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
|
}
|
|
@@ -377,11 +436,26 @@ interface PlatformHostOptions<TDb> {
|
|
|
377
436
|
adapters?: readonly AdapterImplementation[];
|
|
378
437
|
dispatcher?: PlatformActionDispatcher;
|
|
379
438
|
services?: FabricRuntimeServices;
|
|
439
|
+
idempotency?: {
|
|
440
|
+
conflictMode?: "audit-only" | "enforce";
|
|
441
|
+
onConflict?(conflict: IdempotencyConflict): void;
|
|
442
|
+
onLegacyRecord?(invocation: ActionInvocationRecord): void;
|
|
443
|
+
};
|
|
444
|
+
provenance?: {
|
|
445
|
+
auditAttributeAllowlist?: readonly string[];
|
|
446
|
+
maxAttributes?: number;
|
|
447
|
+
maxValueLength?: number;
|
|
448
|
+
redactAuditAttributes?(attributes: NamespacedAttributes): NamespacedAttributes;
|
|
449
|
+
onTrace?(provenance: InvocationProvenance): void;
|
|
450
|
+
};
|
|
380
451
|
/** Requires an outbox-capable store; every canonical event is then appended with delivery state. */
|
|
381
452
|
outbox?: {
|
|
382
453
|
producerModuleVersion(actionId: ActionId, actionVersion: number): string;
|
|
383
454
|
classifyPayload(event: AssetEventEnvelope): EventPayloadClassification;
|
|
455
|
+
includeProvenance?(event: AssetEventEnvelope, classification: EventPayloadClassification): boolean;
|
|
384
456
|
traceContext?(event: AssetEventEnvelope): Record<string, string> | undefined;
|
|
457
|
+
/** Host lifecycle events are excluded by default; opt in only after making their payload audit-safe. */
|
|
458
|
+
shouldPublish?(event: AssetEventEnvelope): boolean;
|
|
385
459
|
};
|
|
386
460
|
/** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
|
|
387
461
|
hitlEvaluator?: AgentActionPolicyEvaluator;
|
|
@@ -433,8 +507,15 @@ interface GovernedActionHost {
|
|
|
433
507
|
|
|
434
508
|
declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost;
|
|
435
509
|
|
|
510
|
+
interface MemoryPlatformHostTransactionProvider<TDb> {
|
|
511
|
+
snapshot(db: TDb): TDb;
|
|
512
|
+
restore(db: TDb, snapshot: TDb): void;
|
|
513
|
+
}
|
|
436
514
|
declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb>, GovernancePlatformHostStore<TDb>, OutboxPlatformHostStore<TDb> {
|
|
437
515
|
readonly db: TDb;
|
|
516
|
+
readonly transactionalOutbox: boolean;
|
|
517
|
+
transactionWithEvents?: <TResult>(run: (transaction: PlatformHostMutationTransaction<TDb>) => Promise<TResult>) => Promise<TResult>;
|
|
518
|
+
private transactionTail;
|
|
438
519
|
readonly invocations: ActionInvocationRecord[];
|
|
439
520
|
readonly policyEvaluations: PolicyEvaluationRecord[];
|
|
440
521
|
readonly adapterInvocations: AdapterInvocationRecord[];
|
|
@@ -443,11 +524,12 @@ declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostSto
|
|
|
443
524
|
readonly executionAttestations: ExecutionAttestationRecord[];
|
|
444
525
|
readonly externalReconciliations: ExternalReconciliationRecord[];
|
|
445
526
|
readonly outbox: OutboxRecord[];
|
|
446
|
-
constructor(db: TDb);
|
|
527
|
+
constructor(db: TDb, transactionProvider?: MemoryPlatformHostTransactionProvider<TDb>);
|
|
447
528
|
transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
|
|
529
|
+
private runTransactionWithEvents;
|
|
448
530
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
449
531
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
450
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
532
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
451
533
|
recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
|
|
452
534
|
beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
|
|
453
535
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
@@ -543,7 +625,7 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
|
|
|
543
625
|
transaction<TResult>(run: (db: TDb) => Promise<TResult>): Promise<TResult>;
|
|
544
626
|
createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
|
|
545
627
|
getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
|
|
546
|
-
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
|
|
628
|
+
updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation">>): Promise<void>;
|
|
547
629
|
recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
|
|
548
630
|
beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
|
|
549
631
|
appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
|
|
@@ -583,6 +665,10 @@ declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostS
|
|
|
583
665
|
listEvents(tenantId: string, spaceId: string): Promise<AssetEventEnvelope[]>;
|
|
584
666
|
}
|
|
585
667
|
|
|
668
|
+
declare const PARAMETER_DIGEST_ALGORITHM: "fabric-canonical-json-sha256-v1";
|
|
669
|
+
declare function canonicalJson(value: unknown): string;
|
|
670
|
+
declare function digestParameters(parameters: unknown): string;
|
|
671
|
+
|
|
586
672
|
/**
|
|
587
673
|
* Durable store-backed dispatch: the pending invocation row is the queue item.
|
|
588
674
|
* Repeated dispatches are safe because the workflow id is stable per invocation.
|
|
@@ -593,4 +679,4 @@ declare function runPlatformActionWorkerCycle<TDb>(options: PlatformActionWorker
|
|
|
593
679
|
/** Poll until aborted. Each iteration is bounded and waits without busy-spinning. */
|
|
594
680
|
declare function runPlatformActionWorker<TDb>(options: PlatformActionWorkerOptions<TDb>): Promise<void>;
|
|
595
681
|
|
|
596
|
-
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 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 };
|
|
682
|
+
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 };
|