agent-passport-system 4.0.0 → 4.1.1
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/README.md +37 -34
- package/dist/src/core/canonical-jcs.d.ts +11 -0
- package/dist/src/core/canonical-jcs.d.ts.map +1 -1
- package/dist/src/core/canonical-jcs.js +39 -0
- package/dist/src/core/canonical-jcs.js.map +1 -1
- package/dist/src/core/reversibility-fold.d.ts +425 -0
- package/dist/src/core/reversibility-fold.d.ts.map +1 -0
- package/dist/src/core/reversibility-fold.js +513 -0
- package/dist/src/core/reversibility-fold.js.map +1 -0
- package/dist/src/types/execution-envelope.d.ts +7 -0
- package/dist/src/types/execution-envelope.d.ts.map +1 -1
- package/package.json +4 -4
|
@@ -0,0 +1,425 @@
|
|
|
1
|
+
/** What evidence actually establishes about an effect's reversibility.
|
|
2
|
+
* `unresolved` is an honest "not known yet", never silently upgraded. */
|
|
3
|
+
export type RealizedClass = 'tentative' | 'compensable' | 'irreversible' | 'unresolved';
|
|
4
|
+
/** The conservative class admission and the gateway act on. There is no
|
|
5
|
+
* `unresolved` here: the projection below folds it to `irreversible`. */
|
|
6
|
+
export type EnforcementClass = 'tentative' | 'compensable' | 'irreversible';
|
|
7
|
+
/** Pure projection realized -> enforcement (spec section 0).
|
|
8
|
+
* `unresolved` becomes `irreversible` (conservative, fail-closed). Every
|
|
9
|
+
* other value is the identity. This is the ONLY place `unresolved` is
|
|
10
|
+
* mapped to `irreversible`; realized truth is never rewritten. */
|
|
11
|
+
export declare function enforcementFrom(realized: RealizedClass): EnforcementClass;
|
|
12
|
+
/** The externality bucket an effect falls in. These values mirror the RAPV0
|
|
13
|
+
* TaskClassification.externality vocabulary (src/types/reputation-authority.ts)
|
|
14
|
+
* minus 'none'; a caller may pass RAPV0 values, and 'none' or an absent value
|
|
15
|
+
* is treated as unbound (see EffectFacts.externality). This is pattern reuse,
|
|
16
|
+
* not a shared type: reversibility is not a scalar of the effect location. */
|
|
17
|
+
export type EffectExternality = 'internal' | 'external-reversible' | 'external-irreversible';
|
|
18
|
+
/** Finality of an external effect. Used to decide whether an irreversible
|
|
19
|
+
* verdict is definitive or only an upper bound (spec section 4). */
|
|
20
|
+
export type FinalityState = 'settled' | 'pending' | 'expired' | 'contradicted';
|
|
21
|
+
/** A reversal-right attestation fact. To count, the signer MUST be a domain
|
|
22
|
+
* other than the acting principal (spec section 4). This step models the
|
|
23
|
+
* fact; it verifies no signature. A signer equal to the acting principal is
|
|
24
|
+
* self-attestation and does not establish the right. */
|
|
25
|
+
export interface ReversalRightFact {
|
|
26
|
+
/** Identity/domain that attested the reversal right. */
|
|
27
|
+
signer: string;
|
|
28
|
+
}
|
|
29
|
+
/** The raw facts a classifier consumes for one effect. Every field is
|
|
30
|
+
* optional: absence is meaningful and generally fails toward unresolved or,
|
|
31
|
+
* once the externality bucket is known, toward irreversible (fail-closed).
|
|
32
|
+
* This is the classifier input, not a receipt wire shape. */
|
|
33
|
+
export interface EffectFacts {
|
|
34
|
+
/** The externality bucket. Absent (undefined) means unbound / missing and
|
|
35
|
+
* classifies as unresolved. A caller mapping RAPV0 'none' should pass it
|
|
36
|
+
* as undefined here. */
|
|
37
|
+
externality?: EffectExternality;
|
|
38
|
+
/** RESERVED for the deferred v4 section 10 four-object subsystem. Not consumed
|
|
39
|
+
* by the v0 classifier: v0 has no external-compensable path, so the acting
|
|
40
|
+
* principal plays no part in v0 classification. */
|
|
41
|
+
actingPrincipal?: string;
|
|
42
|
+
/** Who can invoke reversal (recovery_controller), a carried raw fact. Not
|
|
43
|
+
* consumed by the v0 classifier (v0 external is irreversible-only). */
|
|
44
|
+
recoveryController?: string | null;
|
|
45
|
+
/** RESERVED for the deferred v4 section 10 four-object subsystem. Not consumed
|
|
46
|
+
* by the v0 classifier. In v0 no reversal-right can ground compensability;
|
|
47
|
+
* external compensability is a future profile, not a v0 branch. */
|
|
48
|
+
reversalRight?: ReversalRightFact | null;
|
|
49
|
+
/** Finality of an external-irreversible effect. Only 'settled' contributes
|
|
50
|
+
* to a definitive (non-upper-bound) irreversible verdict. */
|
|
51
|
+
finalityState?: FinalityState;
|
|
52
|
+
/** Whether the target/counterparty binding is verified, for external-
|
|
53
|
+
* irreversible effects. Both finality and this must hold to drop the
|
|
54
|
+
* upper_bound label. */
|
|
55
|
+
targetBindingVerified?: boolean;
|
|
56
|
+
/** A producer-declared recovery mechanism reference. Carried as raw data only:
|
|
57
|
+
* in v0 it derives NOTHING about the class (v4 s4 / s4.1). A self-declared ref
|
|
58
|
+
* is self-attestation, so it cannot mint compensability; internal-compensable
|
|
59
|
+
* requires a verifier-checked recovery result that v0 defers. */
|
|
60
|
+
recoveryMechanismRef?: string | null;
|
|
61
|
+
}
|
|
62
|
+
/** Deterministic reason codes for the v0 profile. One per mapping rule, so a
|
|
63
|
+
* verifier and an auditor read the same explanation for the same facts. Part of
|
|
64
|
+
* the profile's authoritative content (its reason-code set). */
|
|
65
|
+
export type ReasonCode = 'RM_V0_UNBOUND' | 'RM_V0_INTERNAL_DEFINITIVE' | 'RM_V0_INTERNAL_UPPER_BOUND' | 'RM_V0_EXTERNAL_DEFINITIVE' | 'RM_V0_EXTERNAL_UPPER_BOUND';
|
|
66
|
+
/** The result of a classification. The RealizedClass is the mapping output;
|
|
67
|
+
* `label` carries the section-4 upper_bound annotation, present only when an
|
|
68
|
+
* external verdict is not backed by verified finality and target binding; and
|
|
69
|
+
* `reason` is the deterministic reason code for the rule that fired. */
|
|
70
|
+
export interface ClassificationResult {
|
|
71
|
+
realized: RealizedClass;
|
|
72
|
+
label?: 'upper_bound';
|
|
73
|
+
reason: ReasonCode;
|
|
74
|
+
}
|
|
75
|
+
/** A versioned mapping profile: a pure function from raw effect facts to a
|
|
76
|
+
* RealizedClass, addressed by a stable id. */
|
|
77
|
+
export interface ClassificationProfile {
|
|
78
|
+
id: string;
|
|
79
|
+
classify: (facts: EffectFacts) => ClassificationResult;
|
|
80
|
+
}
|
|
81
|
+
/** Stable id of the v0 mapping profile. Chosen value; the spec fixes no
|
|
82
|
+
* literal, only that classification_profile_id must be bound. */
|
|
83
|
+
export declare const REVERSIBILITY_MAPPING_V0_ID = "reversibility-mapping-v0";
|
|
84
|
+
/** The v0 mapping rules (v4 sections 4, 4.1, 10), as a pure function.
|
|
85
|
+
*
|
|
86
|
+
* v0 has NO external-compensable path. External compensability is a FUTURE
|
|
87
|
+
* profile (reversibility-mapping-v1) built on the deferred four-object subsystem
|
|
88
|
+
* of v4 section 10, never a branch inside the v0 profile. v4 section 10 rejects
|
|
89
|
+
* the domain-separation-without-authority model (a non-empty reversal-right
|
|
90
|
+
* signer different from the principal): a registration outside operator control
|
|
91
|
+
* shows only separation, not authority-over-a-mechanism, so it cannot ground
|
|
92
|
+
* compensability. This profile must not behave differently by entry point.
|
|
93
|
+
*
|
|
94
|
+
* - external-irreversible AND external-reversible -> irreversible. Upper bound
|
|
95
|
+
* (label upper_bound) unless finality is settled AND the target binding is
|
|
96
|
+
* verified. The two external buckets are treated identically in v0.
|
|
97
|
+
* - internal -> irreversible, treated exactly like an external-irreversible
|
|
98
|
+
* effect (upper_bound unless finality settled AND target binding verified). A
|
|
99
|
+
* self-declared recovery_mechanism_ref derives nothing (v4 s4 / s4.1), so v0
|
|
100
|
+
* has no internal-compensable path.
|
|
101
|
+
* - unbound / missing externality -> unresolved.
|
|
102
|
+
* v0 therefore emits no compensable outcome at all. */
|
|
103
|
+
export declare function classifyV0(facts: EffectFacts): ClassificationResult;
|
|
104
|
+
/** The v0 profile function object. */
|
|
105
|
+
export declare const reversibilityMappingV0: ClassificationProfile;
|
|
106
|
+
/** The AUTHORITATIVE, canonical content of the v0 profile (v4 section 4): its
|
|
107
|
+
* input schema, mapping rules, reason-code set, and time semantics, and nothing
|
|
108
|
+
* else. No runtime, diagnostic, or human-facing metadata (display name,
|
|
109
|
+
* comments, timestamps) is included, so those can change without changing the
|
|
110
|
+
* content digest. This object is what the digest commits to. */
|
|
111
|
+
export declare const REVERSIBILITY_PROFILE_V0_CONTENT: {
|
|
112
|
+
profile_id: string;
|
|
113
|
+
input_fields: string[];
|
|
114
|
+
externality_values: string[];
|
|
115
|
+
finality_values: string[];
|
|
116
|
+
external_compensable: boolean;
|
|
117
|
+
internal_compensable: boolean;
|
|
118
|
+
rules: ({
|
|
119
|
+
id: string;
|
|
120
|
+
when: string;
|
|
121
|
+
realized: string;
|
|
122
|
+
reason: string;
|
|
123
|
+
label?: undefined;
|
|
124
|
+
} | {
|
|
125
|
+
id: string;
|
|
126
|
+
when: string;
|
|
127
|
+
realized: string;
|
|
128
|
+
label: string;
|
|
129
|
+
reason: string;
|
|
130
|
+
})[];
|
|
131
|
+
reason_codes: string[];
|
|
132
|
+
time_semantics: {
|
|
133
|
+
clock_skew_ms: number;
|
|
134
|
+
finality_source: string;
|
|
135
|
+
target_binding_source: string;
|
|
136
|
+
};
|
|
137
|
+
schema_version: string;
|
|
138
|
+
};
|
|
139
|
+
/** Domain-separated content digest of a profile (v4 section 4):
|
|
140
|
+
* SHA-256( UTF8("APS-REVERSIBILITY-PROFILE-V0") || 0x00 || UTF8(JCS(content)) ).
|
|
141
|
+
* Any language that JCS-canonicalizes the same content reproduces this byte-for-
|
|
142
|
+
* byte. */
|
|
143
|
+
export declare function profileContentDigest(content: unknown): string;
|
|
144
|
+
/** The v0 profile's content digest. */
|
|
145
|
+
export declare const REVERSIBILITY_MAPPING_V0_DIGEST: string;
|
|
146
|
+
/** A registered profile: its function object, its authoritative content, its
|
|
147
|
+
* content digest, and non-authoritative diagnostic metadata that is NOT part of
|
|
148
|
+
* the digest. */
|
|
149
|
+
export interface RegisteredProfile {
|
|
150
|
+
profile: ClassificationProfile;
|
|
151
|
+
content: unknown;
|
|
152
|
+
digest: string;
|
|
153
|
+
/** Diagnostic/human-facing only. Excluded from the digest; may change freely. */
|
|
154
|
+
metadata: {
|
|
155
|
+
display_name: string;
|
|
156
|
+
description: string;
|
|
157
|
+
};
|
|
158
|
+
}
|
|
159
|
+
/** Resolve a mapping profile function by its classification_profile_id. Returns
|
|
160
|
+
* undefined for an unknown id (a distinct event from unbound facts). */
|
|
161
|
+
export declare function getClassificationProfile(id: string): ClassificationProfile | undefined;
|
|
162
|
+
/** Resolve the full registered profile (function, content, digest, metadata). */
|
|
163
|
+
export declare function getRegisteredProfile(id: string): RegisteredProfile | undefined;
|
|
164
|
+
/** The registry's content digest for a profile id, or undefined if unknown. */
|
|
165
|
+
export declare function getProfileDigest(id: string): string | undefined;
|
|
166
|
+
/** The set of registered profile ids. */
|
|
167
|
+
export declare function registeredProfileIds(): string[];
|
|
168
|
+
/** The outcome of checking a declared (id, digest) against the registry. Unknown
|
|
169
|
+
* id and digest mismatch are DISTINCT failures, never conflated. */
|
|
170
|
+
export type ProfileBindingCheck = {
|
|
171
|
+
ok: true;
|
|
172
|
+
digest: string;
|
|
173
|
+
} | {
|
|
174
|
+
ok: false;
|
|
175
|
+
reason: 'unknown_profile';
|
|
176
|
+
classificationProfileId: string;
|
|
177
|
+
} | {
|
|
178
|
+
ok: false;
|
|
179
|
+
reason: 'digest_mismatch';
|
|
180
|
+
classificationProfileId: string;
|
|
181
|
+
declaredDigest: string;
|
|
182
|
+
expectedDigest: string;
|
|
183
|
+
};
|
|
184
|
+
/** Check a declared profile id + content digest against the immutable registry.
|
|
185
|
+
* An id not in the registry fails unknown_profile; a known id whose declared
|
|
186
|
+
* digest does not equal the registry digest fails digest_mismatch. */
|
|
187
|
+
export declare function verifyProfileBinding(id: string, declaredDigest: string): ProfileBindingCheck;
|
|
188
|
+
/** Where an effect lands. Coarser than the classifier's externality bucket:
|
|
189
|
+
* the reversible-vs-irreversible distinction for an external effect is not a
|
|
190
|
+
* field an author sets, it is recomputed from the recovery facts (spec Q4:
|
|
191
|
+
* reversibility is not a scalar of the effect location). */
|
|
192
|
+
export type EffectScope = 'internal' | 'external';
|
|
193
|
+
/** Whether the effect's facts are established yet. Carried per section 3 and
|
|
194
|
+
* consumed by the two-stage lifecycle (a later step), not by this recompute. */
|
|
195
|
+
export type EvidenceStatus = 'resolved' | 'pending' | 'unavailable' | 'conflicted';
|
|
196
|
+
/** One instantiated effect. Raw facts only. */
|
|
197
|
+
export interface EffectInstantiationElement {
|
|
198
|
+
effect_scope: EffectScope;
|
|
199
|
+
effect_target_ref: string;
|
|
200
|
+
finality_state: FinalityState;
|
|
201
|
+
recovery_mechanism_ref: string | null;
|
|
202
|
+
recovery_controller: string | null;
|
|
203
|
+
recovery_deadline: string | null;
|
|
204
|
+
evidence_status: EvidenceStatus;
|
|
205
|
+
classification_profile_id: string;
|
|
206
|
+
/** The content digest of the profile named by classification_profile_id (v4
|
|
207
|
+
* section 4). A recompute checks it against the immutable registry: a
|
|
208
|
+
* mismatch fails distinctly from an unknown profile. Binding the id to the
|
|
209
|
+
* digest proves which profile CONTENT governed the classification. */
|
|
210
|
+
classification_profile_digest: string;
|
|
211
|
+
/** Content-addressed request/action identity of the execution instance this
|
|
212
|
+
* effect belongs to (v4 section 2). Sourced from the carrying receipt's
|
|
213
|
+
* action_ref (ExecutionEnvelope.action_ref, the APS correlation key). A
|
|
214
|
+
* stable, signed binding so an effect state cannot be transplanted between
|
|
215
|
+
* receipts. */
|
|
216
|
+
action_ref: string;
|
|
217
|
+
/** Stable unique id of the specific execution instance (v4 section 2). Sourced
|
|
218
|
+
* from the carrying receipt's per-instance id (ExecutionEnvelope.action_id or
|
|
219
|
+
* RAPV0.receipt_id). Distinguishes two instances that share a content-
|
|
220
|
+
* addressed action_ref. */
|
|
221
|
+
action_instance_id: string;
|
|
222
|
+
/** Stable id for this effect across its lifecycle stages (v4 section 2).
|
|
223
|
+
* Precedence is defined by lineage under this id, never by array position. */
|
|
224
|
+
effect_id: string;
|
|
225
|
+
/** Hash of the prior signed state of THIS effect, or null on the first state.
|
|
226
|
+
* Chains an effect's lineage so a later state references its predecessor. */
|
|
227
|
+
predecessor_effect_state_hash: string | null;
|
|
228
|
+
/** Monotonic position within THIS effect's own lineage (not the array). */
|
|
229
|
+
sequence: number;
|
|
230
|
+
/** Optional cache ONLY. Never trusted. A verifier recomputes the realized
|
|
231
|
+
* class and any mismatch fails verification (verifyAssertedClass). */
|
|
232
|
+
asserted_realized_class?: RealizedClass;
|
|
233
|
+
}
|
|
234
|
+
/** The effect-instantiation block: the effect vector (v0). */
|
|
235
|
+
export interface EffectInstantiationBlock {
|
|
236
|
+
instantiated_effects: EffectInstantiationElement[];
|
|
237
|
+
}
|
|
238
|
+
/** RAPV0 TaskClassification.externality value space. Declared here to avoid
|
|
239
|
+
* coupling this primitive to the reputation type; the values mirror
|
|
240
|
+
* src/types/reputation-authority.ts TaskClassification.externality. */
|
|
241
|
+
export type RapvExternality = 'none' | 'internal' | 'external-reversible' | 'external-irreversible';
|
|
242
|
+
/** Map an RAPV0 externality onto the value used for EffectFacts.externality.
|
|
243
|
+
* 'none' or absent -> undefined (unbound), which classifies unresolved.
|
|
244
|
+
* internal -> internal. Both external buckets -> external-irreversible: the
|
|
245
|
+
* legacy 'external-reversible' taxonomy carried a stronger meaning than v0
|
|
246
|
+
* grants, so it is NOT passed through as-is; mapping it to external-irreversible
|
|
247
|
+
* keeps it from being a backdoor into compensability (v4 s4/s10). This is a pure
|
|
248
|
+
* adapter, not an import-and-couple. */
|
|
249
|
+
export declare function rapvExternalityToEffectFacts(externality: RapvExternality | null | undefined): EffectExternality | undefined;
|
|
250
|
+
/** Verifier-supplied context for a recompute. Facts a verifier establishes
|
|
251
|
+
* out of band. Everything defaults to the fail-closed value when absent. */
|
|
252
|
+
export interface RecomputeOptions {
|
|
253
|
+
/** HARD RULE: an author NEVER sets this from the block. Only a verifier that
|
|
254
|
+
* checked the resource_confirmation_ref cryptographic commitment (a later
|
|
255
|
+
* step) may pass true. Absent or false keeps an external-irreversible effect
|
|
256
|
+
* at irreversible + upper_bound. */
|
|
257
|
+
targetBindingVerified?: boolean;
|
|
258
|
+
}
|
|
259
|
+
/** The outcome of a recompute. An unknown classification_profile_id is a
|
|
260
|
+
* DISTINCT failure from unbound facts: it is surfaced, never silently
|
|
261
|
+
* classified as unresolved. */
|
|
262
|
+
export type RecomputeOutcome = {
|
|
263
|
+
status: 'recomputed';
|
|
264
|
+
classificationProfileId: string;
|
|
265
|
+
result: ClassificationResult;
|
|
266
|
+
} | {
|
|
267
|
+
status: 'unknown_profile';
|
|
268
|
+
classificationProfileId: string;
|
|
269
|
+
} | {
|
|
270
|
+
status: 'profile_digest_mismatch';
|
|
271
|
+
classificationProfileId: string;
|
|
272
|
+
declaredDigest: string;
|
|
273
|
+
expectedDigest: string;
|
|
274
|
+
};
|
|
275
|
+
/** Recompute the realized class for one effect element. Resolves the mapping
|
|
276
|
+
* profile by classification_profile_id; an unknown id is surfaced as its own
|
|
277
|
+
* failure and is NOT classified. Otherwise runs the profile over the element's
|
|
278
|
+
* facts and returns the ClassificationResult. */
|
|
279
|
+
export declare function recomputeEffect(element: EffectInstantiationElement, options?: RecomputeOptions): RecomputeOutcome;
|
|
280
|
+
/** Recompute every effect in a block, per element. No folding or collapsing to
|
|
281
|
+
* a maximum here (that is the fold, a later step). */
|
|
282
|
+
export declare function recomputeBlock(block: EffectInstantiationBlock, options?: RecomputeOptions): RecomputeOutcome[];
|
|
283
|
+
/** The result of checking an element's asserted cache class against the
|
|
284
|
+
* recompute. Absent cache passes. A present cache that differs from the
|
|
285
|
+
* recomputed realized class fails. An unknown profile cannot be verified. */
|
|
286
|
+
export type AssertedClassCheck = {
|
|
287
|
+
ok: true;
|
|
288
|
+
recomputed: ClassificationResult;
|
|
289
|
+
} | {
|
|
290
|
+
ok: false;
|
|
291
|
+
reason: 'mismatch';
|
|
292
|
+
asserted: RealizedClass;
|
|
293
|
+
recomputed: RealizedClass;
|
|
294
|
+
} | {
|
|
295
|
+
ok: false;
|
|
296
|
+
reason: 'unknown_profile';
|
|
297
|
+
classificationProfileId: string;
|
|
298
|
+
} | {
|
|
299
|
+
ok: false;
|
|
300
|
+
reason: 'profile_digest_mismatch';
|
|
301
|
+
classificationProfileId: string;
|
|
302
|
+
declaredDigest: string;
|
|
303
|
+
expectedDigest: string;
|
|
304
|
+
};
|
|
305
|
+
/** Verify an element's asserted cache class (if any) against the recompute.
|
|
306
|
+
* A cache is a convenience only and is never trusted: a mismatch fails. An
|
|
307
|
+
* unknown profile or a profile-digest mismatch cannot be verified and surfaces
|
|
308
|
+
* distinctly. */
|
|
309
|
+
export declare function verifyAssertedClass(element: EffectInstantiationElement, options?: RecomputeOptions): AssertedClassCheck;
|
|
310
|
+
/** Provisional stage. Append-only. */
|
|
311
|
+
export interface ExecutionStageReceipt {
|
|
312
|
+
stage: 'execution';
|
|
313
|
+
action_ref: string;
|
|
314
|
+
run_id: string;
|
|
315
|
+
/** The provisional class facts. */
|
|
316
|
+
effect_instantiation: EffectInstantiationBlock;
|
|
317
|
+
/** Stage-level evidence status. Provisional receipts are always pending. */
|
|
318
|
+
evidence_status: 'pending';
|
|
319
|
+
/** The enforcement class that GOVERNED admission, recorded by the gateway that
|
|
320
|
+
* admitted the action. Never rewritten by any later stage. */
|
|
321
|
+
admitted_enforcement_class: EnforcementClass;
|
|
322
|
+
created_at: string;
|
|
323
|
+
}
|
|
324
|
+
export interface ReconciliationSignature {
|
|
325
|
+
algorithm: 'Ed25519';
|
|
326
|
+
public_key: string;
|
|
327
|
+
value: string;
|
|
328
|
+
}
|
|
329
|
+
/** Audit stage. Hash-linked to an execution receipt and signed. Carries the
|
|
330
|
+
* refined realized class, which has NO enforcement power. */
|
|
331
|
+
export interface ReconciliationStageReceipt {
|
|
332
|
+
stage: 'reconciliation';
|
|
333
|
+
/** SHA-256 hash-link to the execution receipt this refines. */
|
|
334
|
+
execution_receipt_hash: string;
|
|
335
|
+
action_ref: string;
|
|
336
|
+
/** Audit-time realized class. Never gates admission. */
|
|
337
|
+
realized_class: RealizedClass;
|
|
338
|
+
/** Refined evidence status after reconciliation. */
|
|
339
|
+
evidence_status: 'resolved' | 'unavailable' | 'conflicted';
|
|
340
|
+
reconciled_at: string;
|
|
341
|
+
signature: ReconciliationSignature;
|
|
342
|
+
}
|
|
343
|
+
/** SHA-256 (over strict JCS bytes) of an execution receipt. Any change to the
|
|
344
|
+
* execution receipt changes this hash, so a hash-link detects a rewrite. */
|
|
345
|
+
export declare function hashExecutionReceipt(receipt: ExecutionStageReceipt): string;
|
|
346
|
+
export interface CreateReconciliationInput {
|
|
347
|
+
realized_class: RealizedClass;
|
|
348
|
+
evidence_status: 'resolved' | 'unavailable' | 'conflicted';
|
|
349
|
+
reconciled_at: string;
|
|
350
|
+
signerPrivateKey: string;
|
|
351
|
+
signerPublicKey: string;
|
|
352
|
+
}
|
|
353
|
+
/** Create a reconciliation receipt hash-linked to an execution receipt and
|
|
354
|
+
* signed over its canonical body. Does not touch the execution receipt. */
|
|
355
|
+
export declare function createReconciliationReceipt(execution: ExecutionStageReceipt, input: CreateReconciliationInput): ReconciliationStageReceipt;
|
|
356
|
+
export interface TransitionCheck {
|
|
357
|
+
ok: boolean;
|
|
358
|
+
errors: string[];
|
|
359
|
+
}
|
|
360
|
+
/** Validate a reconciliation against its execution receipt. Rejects a broken
|
|
361
|
+
* hash-link (a rewritten execution receipt), an invalid signature, a stage
|
|
362
|
+
* that is not pending, and any non-monotonic realized class. */
|
|
363
|
+
export declare function validateTransition(execution: ExecutionStageReceipt, reconciliation: ReconciliationStageReceipt): TransitionCheck;
|
|
364
|
+
/** The enforcement class that GOVERNED admission. This reads ONLY the execution
|
|
365
|
+
* receipt: the reconciliation's realized class is audit-time truth and carries
|
|
366
|
+
* no enforcement power, so a consumer cannot read the final class as the one
|
|
367
|
+
* that gated the action. */
|
|
368
|
+
export declare function admittedEnforcementClass(execution: ExecutionStageReceipt): EnforcementClass;
|
|
369
|
+
/** The signed authoritative fields of one effect state as a null-free object
|
|
370
|
+
* (v4 section 2). It commits to every signed field: effect_id, sequence,
|
|
371
|
+
* predecessor_effect_state_hash, the raw effect facts, classification_profile_id,
|
|
372
|
+
* classification_profile_digest, the evidence status, and the receipt/action
|
|
373
|
+
* binding (action_ref, action_instance_id). The asserted class is signed content
|
|
374
|
+
* and part of the state identity, so it is included when present, but it is
|
|
375
|
+
* non-authoritative for classification (a verifier recomputes). Computed
|
|
376
|
+
* verification outputs, the state hash itself, and out-of-object signatures are
|
|
377
|
+
* excluded: the builder reads only the known signed fields, so an extra property
|
|
378
|
+
* on the element object cannot enter the preimage. Only non-null fields are
|
|
379
|
+
* included, the same parity-safe rule the profile content follows, because the
|
|
380
|
+
* SDK JCS implementations diverge on null-valued keys. */
|
|
381
|
+
export declare function effectStatePreimage(el: EffectInstantiationElement): Record<string, unknown>;
|
|
382
|
+
/** Domain-separated hash of one effect state (v4 section 2):
|
|
383
|
+
* SHA-256( UTF8("APS-REVERSIBILITY-EFFECT-STATE-V0") || 0x00 || UTF8(JCS(preimage)) )
|
|
384
|
+
* over the null-free preimage of every signed authoritative field. Chains a
|
|
385
|
+
* lineage: a later state's predecessor_effect_state_hash references this. Any
|
|
386
|
+
* language that JCS-canonicalizes the same preimage reproduces it byte-for-byte. */
|
|
387
|
+
export declare function hashEffectState(element: EffectInstantiationElement): string;
|
|
388
|
+
/** Deterministic derivation of an effect_id (v4 section 2):
|
|
389
|
+
* base64url( SHA-256( UTF8("APS-REVERSIBILITY-EFFECT-ID-V0") || 0x00 ||
|
|
390
|
+
* UTF8(JCS({action_ref, action_instance_id, local_effect_id})) ) ), where
|
|
391
|
+
* local_effect_id is unique within the receipt and STABLE across retries (an
|
|
392
|
+
* id, not a nonce). The id is a function of stable inputs, so a retry produces
|
|
393
|
+
* the same effect_id and the same lineage identity. */
|
|
394
|
+
export declare function deriveEffectId(action_ref: string, action_instance_id: string, local_effect_id: string): string;
|
|
395
|
+
/** The typed outcome of lineage validation (v4 section 2, corrected).
|
|
396
|
+
* - ok: a single rooted, gap-free, correctly chained lineage per effect_id.
|
|
397
|
+
* - lineage_incomplete: a gap in sequences, a non-zero origin, or no root
|
|
398
|
+
* (missing states).
|
|
399
|
+
* - lineage_conflicted: a fork, where one predecessor state has two distinct
|
|
400
|
+
* successors.
|
|
401
|
+
* - equivocation: two distinct roots share an effect_id (multiple-roots), or two
|
|
402
|
+
* states occupy the same (effect_id, sequence) with different hashes without a
|
|
403
|
+
* shared predecessor. Named as the provable condition; it is NOT a claim about
|
|
404
|
+
* a semantic collision between unrelated effects.
|
|
405
|
+
* - invalid_state: a state at sequence n>0 whose predecessor_effect_state_hash
|
|
406
|
+
* does not equal the hash of the state at n-1 (a broken chain link). */
|
|
407
|
+
export type LineageStatus = 'ok' | 'lineage_incomplete' | 'lineage_conflicted' | 'equivocation' | 'invalid_state';
|
|
408
|
+
export interface LineageResult {
|
|
409
|
+
status: LineageStatus;
|
|
410
|
+
/** Exact-duplicate states (identical full effect-state hash) removed before
|
|
411
|
+
* the graph checks, aggregated across all effect_ids in the block. */
|
|
412
|
+
duplicate_count: number;
|
|
413
|
+
}
|
|
414
|
+
/** Validate the identity and lineage structure of a block, independent of array
|
|
415
|
+
* order (v4 section 2, corrected). Returns a TYPED status plus a duplicate_count.
|
|
416
|
+
* The block is ok only when every effect_id's lineage is ok; otherwise the
|
|
417
|
+
* status is that of the lexicographically first non-ok effect_id (deterministic).
|
|
418
|
+
* This validates identity only; the lineage-based fold reading (classify from
|
|
419
|
+
* the latest lineage state per effect_id) is the fold, not built here. */
|
|
420
|
+
export declare function validateEffectLineage(block: EffectInstantiationBlock): LineageResult;
|
|
421
|
+
/** The latest valid state per effect_id, but ONLY for an ok lineage. Returns
|
|
422
|
+
* undefined for any non-ok block, so a caller cannot pull a latest state from an
|
|
423
|
+
* incomplete, conflicted, equivocating, or invalid lineage. Order-invariant. */
|
|
424
|
+
export declare function latestValidEffectStates(block: EffectInstantiationBlock): Map<string, EffectInstantiationElement> | undefined;
|
|
425
|
+
//# sourceMappingURL=reversibility-fold.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reversibility-fold.d.ts","sourceRoot":"","sources":["../../../src/core/reversibility-fold.ts"],"names":[],"mappings":"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"}
|