@fro.bot/systematic 3.23.0 → 3.24.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.
@@ -1,126 +0,0 @@
1
- import type { ToolDefinition } from '@opencode-ai/plugin';
2
- import type { OpencodeOperationObserver, RegisteredWorktreeValidationResult } from './opencode-operation-observer.js';
3
- import type { ReceiptClassifier } from './receipt-classifier.js';
4
- import { type ReceiptLedger, type ReceiptOperation } from './receipt-ledger.js';
5
- import { type EvidenceObservationResult, type RuntimeUnitPolicy, type TransitionPrepareResult, type WorkflowReasonCode, type WorkflowStatus } from './workflow-guard.js';
6
- export declare const SYSTEMATIC_WORKFLOW_RECEIPT_METADATA_KEY = "systematic_workflow_receipt";
7
- export interface OpencodeWorkflowGuardConfig {
8
- mode: 'observe' | 'protected' | 'disabled';
9
- debug: boolean;
10
- }
11
- declare const WORKFLOW_GUARD_BLOCKED_ERROR_CODE = "workflow-guard-blocked";
12
- export type WorkflowGuardBlockedError = Error & {
13
- readonly code: typeof WORKFLOW_GUARD_BLOCKED_ERROR_CODE;
14
- readonly reasonCode: WorkflowReasonCode;
15
- };
16
- export declare function createWorkflowGuardBlockedError(reasonCode: WorkflowReasonCode): WorkflowGuardBlockedError;
17
- export declare function isWorkflowGuardBlockedError(value: unknown): value is WorkflowGuardBlockedError;
18
- export declare const WORKFLOW_GUARD_GUIDANCE = "In this OpenCode session the workflow guard is on. Check the workflow guard availability once per execution unit. Guard state is per session; a child session starts `inactive`. `inactive` (reason `no-active-epoch`) means no guarded workflow has started in this session. It is not unavailable and not terminal: load a guarded skill to begin, and do not call `systematic_workflow_start` or `systematic_workflow_complete` before one is active. A completion rejected with `readback-timeout` is retryable: call `systematic_workflow_complete` again at most twice, then report it to the user. Probes listed in `unconfirmedReadbacks` on status output (`local`, `pinned`, or an operation name) are unverified until a later status call confirms them. A completion rejected with `snapshot-blocked` or `stale-receipt` is not terminal. For `snapshot-blocked`, read `blockReason` from the rejection or `snapshotBlock.reasonCode` from status, fix that cause in the worktree without deleting or hiding user files unless the user agrees, and call status to confirm the block is gone (when the rejection names `blockTarget: parent-checkout`, fix the parent checkout and retry completion instead). Files inside submodules and nested repositories count toward the snapshot limits. Operations run while blocked leave no receipts: rerun stale or missing operations, checking remote state before redoing a push or PR, then complete. If the same reason remains after one fix, report it to the user, who can disable the guard through `systematic_workflow_control`. A call the guard skipped or sealed after a timeout has already run: for a local call check the worktree state, for a push or PR creation check remote state (the upstream ref or the open PR), and rerun only if its effect is missing. After a rejected push, check remote state, fix the cause and retry (a first push needs `git push -u`); never force-push or delete a remote ref without the user's approval. If a push may have landed but left no receipt and later pushes are rejected as `resource-mismatch`, report it to the user. A verification that overlapped another local call is not receipted; rerun it alone once every local call from that request has returned. If the guard reports `unavailable` or `guard-unavailable`, treat it as terminal for that unit: do not retry `systematic_workflow_start` or `systematic_workflow_complete`. Use the documented unguarded fallback only when authorized, and report the unavailable state once. `disabled` means the user turned the guard off; do not call the workflow tools.";
19
- export interface OpencodeWorkflowGuardOptions {
20
- config: OpencodeWorkflowGuardConfig;
21
- workspaceIdentity: string;
22
- repositoryIdentity?: string;
23
- worktreeIdentity?: string;
24
- observer?: OpencodeOperationObserver;
25
- classifier?: ReceiptClassifier;
26
- runtimeRequiredOperations?: readonly ReceiptOperation[];
27
- hostReadback?: OpencodeWorkflowHostReadback;
28
- readonly registrationIdentity?: string;
29
- readonly sessionSalt?: Uint8Array;
30
- readonly targetDirectory?: string;
31
- readonly sessionLocation?: string;
32
- /** Injectable clock (epoch milliseconds); defaults to `Date.now`. */
33
- readonly now?: () => number;
34
- /**
35
- * Injectable factory for the observer of a registered linked-worktree target;
36
- * defaults to `createOpencodeOperationObserver`. A test seam: it lets tests
37
- * control a pinned worktree observer's snapshots.
38
- */
39
- readonly createTargetObserver?: (targetDirectory: string) => OpencodeOperationObserver;
40
- }
41
- export interface OpencodeWorkflowChildSession {
42
- readonly sessionId: string;
43
- readonly parentID?: string;
44
- }
45
- export interface OpencodeWorkflowHostReadback {
46
- /**
47
- * Lenient read, used for child-session rollup: a host error or malformed
48
- * payload may be reported as `[]` (nothing to roll up), and only a thrown
49
- * read marks the parent unavailable.
50
- */
51
- readSessionParts(sessionID: string): Promise<ReadonlyArray<unknown>>;
52
- /**
53
- * Strict read of the session's OWN history, used for initialization and
54
- * recovery. Must throw on a host error or malformed payload so a failed read
55
- * can never be mistaken for empty history. Optional only so injected readers
56
- * need no mass edits; when absent, initialization falls back to
57
- * `readSessionParts`, which then carries the same obligation to throw on
58
- * failure.
59
- */
60
- readSessionPartsStrict?(sessionID: string): Promise<ReadonlyArray<unknown>>;
61
- listChildren(sessionID: string): Promise<ReadonlyArray<OpencodeWorkflowChildSession>>;
62
- }
63
- export interface OpencodeWorkflowGuardHooks {
64
- 'tool.execute.before': (input: unknown, output: unknown) => Promise<void>;
65
- 'tool.execute.after': (input: unknown, output: unknown) => Promise<void>;
66
- event: (input: unknown) => Promise<void>;
67
- 'experimental.chat.system.transform': (input: unknown, output: unknown) => Promise<void>;
68
- }
69
- export interface OpencodeWorkflowGuard {
70
- readonly tools: Readonly<Record<string, ToolDefinition>>;
71
- readonly hooks: OpencodeWorkflowGuardHooks;
72
- status(sessionID: unknown): WorkflowStatus;
73
- ledger(sessionID: unknown): ReceiptLedger | undefined;
74
- observeReceipt(sessionID: unknown, input: unknown): EvidenceObservationResult;
75
- prepareTransition(sessionID: unknown, input: unknown): TransitionPrepareResult;
76
- startUnit(sessionID: unknown, input: unknown, policy?: RuntimeUnitPolicy): unknown;
77
- /** @internal Test seam for the snapshot-block helpers. */
78
- snapshotBlock(sessionID: unknown): SnapshotBlockControls;
79
- }
80
- declare const SNAPSHOT_BLOCKING_REASONS: readonly ["file-limit", "file-output-limit", "command-output-limit", "worktree-unstable"];
81
- export type SnapshotBlockReason = (typeof SNAPSHOT_BLOCKING_REASONS)[number];
82
- /** @internal Exported for tests; production call sites use it unexported. */
83
- export declare function isSnapshotBlockingReason(reasonCode: unknown): reasonCode is SnapshotBlockReason;
84
- export type SnapshotBlockClearResult = {
85
- readonly status: 'not-blocked';
86
- } | {
87
- readonly status: 'cleared';
88
- } | {
89
- readonly status: 'still-blocked';
90
- readonly reasonCode: SnapshotBlockReason;
91
- } | {
92
- readonly status: 'stale';
93
- } | {
94
- readonly status: 'timeout';
95
- } | {
96
- readonly status: 'fatal';
97
- };
98
- /**
99
- * @internal Test seam: drives the snapshot-block helpers of one session
100
- * without a hook that sets the block. `set` records a block on the unit's
101
- * effective target and returns false when there is no active unit.
102
- */
103
- export interface SnapshotBlockControls {
104
- set(reasonCode: SnapshotBlockReason): boolean;
105
- current(): {
106
- readonly reasonCode: SnapshotBlockReason;
107
- } | undefined;
108
- clear(): Promise<SnapshotBlockClearResult>;
109
- }
110
- export type LocalOperationTool = 'write' | 'edit' | 'apply_patch' | 'bash';
111
- export interface OpencodeOperationTargetDerivationOptions {
112
- readonly parentTargetRoot: string;
113
- readonly sessionLocation?: string;
114
- readonly validateRegisteredWorktree: (candidateDirectory: string) => RegisteredWorktreeValidationResult;
115
- readonly realPath?: (filePath: string) => string;
116
- }
117
- export type OpencodeOperationTargetDerivationResult = {
118
- readonly status: 'available';
119
- readonly targetRoot: string;
120
- } | {
121
- readonly status: 'unavailable';
122
- readonly reasonCode: 'target-unavailable' | 'command-timeout';
123
- };
124
- export declare function deriveOpencodeOperationTarget(tool: LocalOperationTool, args: unknown, options: OpencodeOperationTargetDerivationOptions): OpencodeOperationTargetDerivationResult;
125
- export declare function createOpencodeWorkflowGuard(options: OpencodeWorkflowGuardOptions): OpencodeWorkflowGuard;
126
- export {};
@@ -1,94 +0,0 @@
1
- export declare const CANONICAL_QUESTION_WORDING: 'Confirm the requested guarded transition.';
2
- export type QuestionPurpose = 'transition' | 'session-disablement';
3
- export type QuestionAnswerClassification = 'affirmative' | 'non-affirmative';
4
- export type QuestionAttestationReasonCode = 'already-bound' | 'already-consumed' | 'already-disabled' | 'call-session-mismatch' | 'challenge-expired' | 'challenge-consumed' | 'invalid-input' | 'no-attestation' | 'non-affirmative' | 'rejected' | 'replay' | 'scope-mismatch' | 'substitution' | 'unknown-challenge' | 'unknown-request';
5
- export interface QuestionAttestationOptions {
6
- clock?: () => number;
7
- maxChallengeAgeMs?: number;
8
- }
9
- export interface QuestionChallengeRecord {
10
- readonly challengeId: string;
11
- readonly sessionId: string;
12
- readonly resourceDigest: string;
13
- readonly transitionKey: string;
14
- readonly purpose: QuestionPurpose;
15
- readonly createdAt: number;
16
- readonly question: {
17
- readonly wording: typeof CANONICAL_QUESTION_WORDING;
18
- readonly args: {
19
- readonly challengeId: string;
20
- readonly purpose: QuestionPurpose;
21
- readonly resourceDigest: string;
22
- readonly transitionKey: string;
23
- };
24
- };
25
- }
26
- export interface QuestionAttestation {
27
- readonly purpose: QuestionPurpose;
28
- readonly sessionId: string;
29
- readonly resourceDigest: string;
30
- readonly transitionKey: string;
31
- readonly requestId: string;
32
- readonly answer: 'affirmed';
33
- readonly timestamp: number;
34
- readonly consumption: 'available' | 'consumed';
35
- }
36
- export type ChallengeResult = {
37
- readonly status: 'pending';
38
- readonly challenge: QuestionChallengeRecord;
39
- } | RejectedResult;
40
- export type BindAskedResult = {
41
- readonly status: 'bound';
42
- readonly challengeId: string;
43
- readonly requestId: string;
44
- } | RejectedResult;
45
- export type ObserveReplyResult = {
46
- readonly status: 'accepted';
47
- readonly attestation: QuestionAttestation;
48
- } | RejectedResult;
49
- export type ObserveRejectResult = {
50
- readonly status: 'rejected';
51
- readonly reasonCode: 'rejected';
52
- } | RejectedResult;
53
- export type ConsumeAttestationResult = {
54
- readonly status: 'consumed';
55
- readonly projection: 'attested' | 'disabled';
56
- readonly attestation: QuestionAttestation;
57
- } | RejectedResult;
58
- export type QuestionAttestationProjection = KnownQuestionAttestationProjection | {
59
- readonly status: 'unknown';
60
- readonly reasonCode: QuestionAttestationReasonCode;
61
- };
62
- interface KnownQuestionAttestationProjection {
63
- readonly status: 'pending' | 'bound' | 'attested' | 'denied' | 'disabled';
64
- readonly challengeId: string;
65
- readonly purpose: QuestionPurpose;
66
- readonly sessionId: string;
67
- readonly resourceDigest: string;
68
- readonly transitionKey: string;
69
- readonly requestId?: string;
70
- readonly consumption?: 'available' | 'consumed';
71
- }
72
- export type SessionDisablementProjection = {
73
- readonly status: 'enabled' | 'pending' | 'bound' | 'disabled';
74
- readonly sessionId: string;
75
- } | {
76
- readonly status: 'unknown';
77
- readonly reasonCode: QuestionAttestationReasonCode;
78
- };
79
- export interface QuestionAttestationMachine {
80
- challenge(input: unknown): ChallengeResult;
81
- bindAsked(input: unknown): BindAskedResult;
82
- observeReply(input: unknown): ObserveReplyResult;
83
- observeReject(input: unknown): ObserveRejectResult;
84
- consumeAttestation(input: unknown): ConsumeAttestationResult;
85
- status(input: unknown): QuestionAttestationProjection;
86
- sessionStatus(input: unknown): SessionDisablementProjection;
87
- }
88
- interface RejectedResult {
89
- readonly status: 'rejected';
90
- readonly reasonCode: QuestionAttestationReasonCode;
91
- }
92
- export declare function classifyQuestionAnswer(answer: unknown): QuestionAnswerClassification;
93
- export declare function createQuestionAttestation(options?: QuestionAttestationOptions): QuestionAttestationMachine;
94
- export {};
@@ -1,44 +0,0 @@
1
- import type { ReceiptClassification, ReceiptContext, ReceiptObservationAfter, ReceiptOperation, TerminalObservation } from './receipt-ledger.js';
2
- export interface ReceiptClassificationInput {
3
- command: string;
4
- terminal: TerminalObservation;
5
- }
6
- export interface ReceiptClassifierOptions {
7
- treeSitterWasmPath?: string;
8
- bashWasmPath?: string;
9
- }
10
- export interface ReceiptClassifier {
11
- classify(input: unknown): Promise<ReceiptClassification>;
12
- classifyOperation?(input: unknown): Promise<ReceiptClassification>;
13
- close(): Promise<void>;
14
- }
15
- export type ReceiptOperationTool = 'edit' | 'write' | 'apply-patch' | 'apply_patch' | 'bash' | 'git' | 'gh' | 'bun' | 'npm';
16
- export type PullRequestObservationState = 'open' | 'closed' | 'merged';
17
- export type CheckObservationState = 'completed-success' | 'completed-failure' | 'pending';
18
- export type ReviewObservationDecision = 'approved' | 'changes-requested' | 'commented' | 'pending';
19
- export interface ReceiptOperationContext extends ReceiptContext {
20
- resourceRevisionIdentity?: string;
21
- }
22
- export interface ReceiptOperationAfter extends ReceiptObservationAfter {
23
- commitClosure?: boolean;
24
- pullRequest?: {
25
- identity: string;
26
- state: PullRequestObservationState;
27
- };
28
- resourceRevisionIdentity?: string;
29
- checkState?: CheckObservationState;
30
- reviewDecision?: ReviewObservationDecision;
31
- }
32
- export interface ReceiptOperationObservation {
33
- callId: string;
34
- operation: ReceiptOperation;
35
- tool: ReceiptOperationTool;
36
- command?: string;
37
- context: ReceiptOperationContext;
38
- after?: ReceiptOperationAfter;
39
- terminal: TerminalObservation;
40
- }
41
- export declare function parseReceiptOperationAfter(input: unknown): ReceiptOperationAfter | undefined;
42
- export declare function parseReceiptOperationObservation(input: unknown): ReceiptOperationObservation | undefined;
43
- export declare function createReceiptClassifier(options?: ReceiptClassifierOptions): ReceiptClassifier;
44
- export type { ReceiptOperation };
@@ -1,146 +0,0 @@
1
- import type { ReceiptDigestDomain, ReceiptReadbackFailureCategory, ReceiptReadbackProgression } from './receipt-readback.js';
2
- export declare const RECEIPT_SCHEMA_VERSION: 2;
3
- export declare const RECEIPT_PROTOCOL_VERSION: 2;
4
- declare const LEGACY_RECEIPT_SCHEMA_VERSION: 1;
5
- declare const LEGACY_RECEIPT_PROTOCOL_VERSION: 1;
6
- export type ReceiptOperation = 'implementation' | 'verification' | 'commit' | 'push' | 'pr-creation' | 'check-readback' | 'review-readback';
7
- export type ReceiptClassificationOutcome = 'accepted' | 'rejected' | 'unavailable';
8
- export type ReceiptAttribution = 'runtime-verified' | 'unattributed';
9
- export type ReceiptResult = 'success' | 'failure' | 'unknown';
10
- export type ReceiptSideEffect = 'required' | 'not-required';
11
- export type TerminalStatus = 'success' | 'failure' | 'cancelled' | 'running' | 'unknown';
12
- export type TerminalOutput = 'empty' | 'non-empty' | 'unknown';
13
- export type DigestDomain = ReceiptDigestDomain;
14
- export type ReceiptReasonCode = 'already-consumed' | 'abandoned-observation' | 'ambiguous-attribution' | 'classification-rejected' | 'classification-unavailable' | 'call-context-conflict' | 'classifier-closed' | 'cross-registration-disputed' | 'capability-mismatch' | 'duplicate-finalization' | 'empty-result' | 'epoch-mismatch' | 'forbidden-field' | 'grammar-incompatible' | 'incomplete-envelope' | 'invalid-observation' | 'invalid-receipt' | 'invalid-terminal-result' | 'no-op-resource' | 'parser-asset-unavailable' | 'parser-failure' | 'prohibited-shell-shape' | 'successful-no-op' | 'terminal-failure' | 'terminal-cancelled' | 'terminal-running' | 'terminal-unknown' | 'unknown-envelope' | 'unknown-receipt' | 'unit-mismatch' | 'unchanged-worktree' | 'unchanged-worktree' | 'unsupported-command' | 'workspace-mismatch' | 'recognized-command';
15
- export interface ReceiptClassification {
16
- outcome: ReceiptClassificationOutcome;
17
- category: ReceiptOperation | null;
18
- attribution: ReceiptAttribution;
19
- result: ReceiptResult;
20
- sideEffect: ReceiptSideEffect;
21
- reasonCode: ReceiptReasonCode;
22
- }
23
- export interface ReceiptContext {
24
- epochId: string;
25
- unitId: string;
26
- workspaceIdentity: string;
27
- repositoryIdentity?: string;
28
- worktreeIdentity?: string;
29
- operationTargetIdentity?: string;
30
- resourceIdentity?: string;
31
- }
32
- export interface ReceiptObservationAfter {
33
- workspaceIdentity: string;
34
- repositoryIdentity?: string;
35
- worktreeIdentity?: string;
36
- operationTargetIdentity?: string;
37
- resourceIdentity?: string;
38
- }
39
- export interface TerminalObservation {
40
- status: TerminalStatus;
41
- output: TerminalOutput;
42
- noOp: boolean;
43
- }
44
- export interface ReceiptLedgerOptions {
45
- registrationIdentity?: string;
46
- capabilityFlags?: readonly string[];
47
- sessionSalt?: Uint8Array;
48
- }
49
- export interface ReceiptLedgerMetadata {
50
- schemaVersion: typeof RECEIPT_SCHEMA_VERSION;
51
- protocolVersion: typeof RECEIPT_PROTOCOL_VERSION;
52
- registrationDigest: string;
53
- capabilityFlags: readonly string[];
54
- }
55
- export interface CanonicalReceiptFields {
56
- receiptId: string;
57
- registrationDigest: string;
58
- callDigest: string;
59
- epochDigest: string;
60
- unitDigest: string;
61
- workspaceDigest: string;
62
- repositoryDigest?: string;
63
- worktreeDigest?: string;
64
- operationTargetIdentity?: string;
65
- resourceDigest?: string;
66
- operation: ReceiptOperation;
67
- result: 'success';
68
- source: 'runtime-verified';
69
- consumption: 'available' | 'consumed';
70
- timestamp: number;
71
- }
72
- export interface ReceiptEnvelope {
73
- schemaVersion: typeof RECEIPT_SCHEMA_VERSION | typeof LEGACY_RECEIPT_SCHEMA_VERSION;
74
- protocolVersion: typeof RECEIPT_PROTOCOL_VERSION | typeof LEGACY_RECEIPT_PROTOCOL_VERSION;
75
- registrationDigest: string;
76
- capabilityFlags: readonly string[];
77
- compatibility: 'compatible';
78
- canonical: CanonicalReceiptFields;
79
- }
80
- export type PrepareObservationResult = {
81
- status: 'prepared';
82
- preparationId: string;
83
- } | {
84
- status: 'duplicate' | 'rejected';
85
- reasonCode: ReceiptReasonCode;
86
- };
87
- export type FinalizeObservationResult = {
88
- status: 'finalized';
89
- receipt: ReceiptEnvelope;
90
- } | {
91
- status: 'rejected';
92
- reasonCode: ReceiptReasonCode;
93
- };
94
- export type AbandonObservationResult = {
95
- status: 'abandoned';
96
- } | {
97
- status: 'rejected';
98
- reasonCode: ReceiptReasonCode;
99
- };
100
- export type ConsumeReceiptResult = {
101
- status: 'consumed';
102
- receipt: ReceiptEnvelope;
103
- } | {
104
- status: 'rejected';
105
- reasonCode: ReceiptReasonCode;
106
- };
107
- export type RecoverReceiptResult = {
108
- status: 'recovered' | 'duplicate';
109
- receipt: ReceiptEnvelope;
110
- } | {
111
- status: 'rejected';
112
- category: ReceiptReadbackFailureCategory;
113
- };
114
- export type RecoverReadbackResult = {
115
- status: 'recovered' | 'duplicate';
116
- receipts: readonly ReceiptEnvelope[];
117
- progression: ReceiptReadbackProgression;
118
- } | {
119
- status: 'rejected';
120
- category: ReceiptReadbackFailureCategory;
121
- };
122
- export type EnvelopeValidationResult = {
123
- compatibility: 'compatible';
124
- envelope: ReceiptEnvelope;
125
- } | {
126
- compatibility: 'unavailable' | 'rejected';
127
- reasonCode: ReceiptReasonCode;
128
- };
129
- export interface ReceiptLedger {
130
- readonly metadata: ReceiptLedgerMetadata;
131
- digestIdentity(domain: DigestDomain, identity: string): string;
132
- prepareObservation(input: unknown): PrepareObservationResult;
133
- finalizeObservation(input: unknown): FinalizeObservationResult;
134
- abandonObservation(input: unknown): AbandonObservationResult;
135
- consumeReceipt(receiptId: unknown, context: unknown): ConsumeReceiptResult;
136
- recoverReceipt(input: unknown, operationTargetIdentity?: string): RecoverReceiptResult;
137
- recoverReadback(input: readonly unknown[], operationTargetIdentity?: string): RecoverReadbackResult;
138
- getProgressionState(): ReceiptReadbackProgression;
139
- validateEnvelope(input: unknown): EnvelopeValidationResult;
140
- getEnvelope(receiptId: unknown): ReceiptEnvelope | undefined;
141
- listReceipts(): readonly ReceiptEnvelope[];
142
- getSessionSalt(): Uint8Array;
143
- }
144
- export declare function isLocalOperation(operation: ReceiptOperation): operation is 'implementation' | 'verification' | 'commit';
145
- export declare function createReceiptLedger(options?: ReceiptLedgerOptions): ReceiptLedger;
146
- export {};
@@ -1,186 +0,0 @@
1
- import type { ReceiptEnvelope, ReceiptLedgerMetadata, ReceiptOperation } from './receipt-ledger.js';
2
- export declare const RECEIPT_READBACK_SCHEMA_VERSION: 2;
3
- export declare const RECEIPT_READBACK_PROTOCOL_VERSION: 2;
4
- declare const LEGACY_RECEIPT_READBACK_SCHEMA_VERSION: 1;
5
- type ReceiptReadbackVersion = typeof RECEIPT_READBACK_SCHEMA_VERSION | typeof LEGACY_RECEIPT_READBACK_SCHEMA_VERSION;
6
- export type ReceiptDigestDomain = 'repository' | 'worktree' | 'resource' | 'workspace' | 'epoch' | 'unit' | 'call' | 'registration';
7
- export type ReceiptProgressionStateName = 'started' | 'completed';
8
- export type ReceiptEpochFamily = 'work' | 'shipping';
9
- export interface ReceiptResourceScope {
10
- readonly operation: ReceiptOperation;
11
- readonly resourceIdentity: string;
12
- }
13
- export type ReceiptReadbackFailureCategory = 'malformed' | 'forbidden-field' | 'unknown-kind' | 'unknown-schema' | 'unknown-protocol' | 'unknown-capability' | 'integrity-mismatch' | 'missing-mint' | 'control-before-mint' | 'conflicting-marker' | 'out-of-order' | 'cross-registration' | 'capability-mismatch' | 'salt-mismatch' | 'receipt-mismatch' | 'progression-mismatch' | 'inconsistent-evidence' | 'missing-internal-id' | 'identity-digest-mismatch' | 'conflicting-seed' | 'missing-seed';
14
- export interface ReceiptMintMarker {
15
- readonly kind: 'mint';
16
- readonly schemaVersion: ReceiptReadbackVersion;
17
- readonly protocolVersion: ReceiptReadbackVersion;
18
- readonly envelope: ReceiptEnvelope;
19
- readonly sessionSalt: string;
20
- readonly integrity: string;
21
- }
22
- export interface ReceiptConsumeMarker {
23
- readonly kind: 'control';
24
- readonly schemaVersion: ReceiptReadbackVersion;
25
- readonly protocolVersion: ReceiptReadbackVersion;
26
- readonly registrationDigest: string;
27
- readonly capabilityFlags: readonly string[];
28
- readonly control: 'consume';
29
- readonly receiptId: string;
30
- readonly transitionDigest: string;
31
- readonly timestamp: number;
32
- readonly integrity: string;
33
- }
34
- export interface ReceiptEpochProgressionMarker {
35
- readonly kind: 'control';
36
- readonly schemaVersion: ReceiptReadbackVersion;
37
- readonly protocolVersion: ReceiptReadbackVersion;
38
- readonly registrationDigest: string;
39
- readonly capabilityFlags: readonly string[];
40
- readonly control: 'progression';
41
- readonly target: 'epoch';
42
- readonly epochId: string;
43
- readonly epochDigest: string;
44
- readonly family: ReceiptEpochFamily;
45
- readonly state: ReceiptProgressionStateName;
46
- readonly transitionDigest: string;
47
- readonly timestamp: number;
48
- readonly sessionSalt: string;
49
- readonly integrity: string;
50
- }
51
- export interface ReceiptUnitProgressionMarker {
52
- readonly kind: 'control';
53
- readonly schemaVersion: ReceiptReadbackVersion;
54
- readonly protocolVersion: ReceiptReadbackVersion;
55
- readonly registrationDigest: string;
56
- readonly capabilityFlags: readonly string[];
57
- readonly control: 'progression';
58
- readonly target: 'unit';
59
- readonly epochId: string;
60
- readonly epochDigest: string;
61
- readonly unitId: string;
62
- readonly unitDigest: string;
63
- readonly family: ReceiptEpochFamily;
64
- readonly requiredOperations: readonly ReceiptOperation[];
65
- readonly resourceScopes: readonly ReceiptResourceScope[];
66
- readonly pinnedOperationTargetIdentity?: string;
67
- readonly state: ReceiptProgressionStateName;
68
- readonly transitionDigest: string;
69
- readonly timestamp: number;
70
- readonly sessionSalt: string;
71
- readonly integrity: string;
72
- }
73
- export type ReceiptProgressionMarker = ReceiptEpochProgressionMarker | ReceiptUnitProgressionMarker;
74
- export type ReceiptControlMarker = ReceiptConsumeMarker | ReceiptProgressionMarker;
75
- export type ReceiptMarker = ReceiptMintMarker | ReceiptControlMarker;
76
- export type ReceiptProgressionMarkerInput = {
77
- readonly target: 'epoch';
78
- readonly state: ReceiptProgressionStateName;
79
- readonly epochId: string;
80
- readonly family: ReceiptEpochFamily;
81
- readonly transitionDigest: string;
82
- readonly timestamp?: number;
83
- } | {
84
- readonly target: 'unit';
85
- readonly state: ReceiptProgressionStateName;
86
- readonly epochId: string;
87
- readonly unitId: string;
88
- readonly family: ReceiptEpochFamily;
89
- readonly requiredOperations: readonly ReceiptOperation[];
90
- readonly resourceScopes: readonly ReceiptResourceScope[];
91
- readonly pinnedOperationTargetIdentity?: string;
92
- readonly transitionDigest: string;
93
- readonly timestamp?: number;
94
- };
95
- export interface ReceiptProgressionProjectionSource {
96
- readonly metadata: ReceiptLedgerMetadata | (() => ReceiptLedgerMetadata);
97
- readonly getSessionSalt: () => Uint8Array;
98
- readonly digestIdentity: (domain: ReceiptDigestDomain, identity: string) => string;
99
- }
100
- export interface ReceiptReadbackExpectation {
101
- readonly registrationDigest: string;
102
- readonly capabilityFlags: readonly string[];
103
- readonly sessionSalt: Uint8Array;
104
- readonly source?: 'runtime-verified';
105
- /**
106
- * When present, legacy v1 mint markers are rejected because they cannot
107
- * authenticate a foreign/worktree target. Absence retains the narrow v1
108
- * parent-target recovery shim; callers must validate that parent separately.
109
- */
110
- readonly operationTargetIdentity?: string;
111
- }
112
- export type ReceiptEpochProgressionSnapshot = {
113
- readonly target: 'epoch';
114
- readonly state: ReceiptProgressionStateName;
115
- readonly epochId: string;
116
- readonly epochDigest: string;
117
- readonly family: ReceiptEpochFamily;
118
- readonly transitionDigest: string;
119
- };
120
- export type ReceiptUnitProgressionSnapshot = {
121
- readonly target: 'unit';
122
- readonly state: ReceiptProgressionStateName;
123
- readonly epochId: string;
124
- readonly epochDigest: string;
125
- readonly unitId: string;
126
- readonly unitDigest: string;
127
- readonly family: ReceiptEpochFamily;
128
- readonly requiredOperations: readonly ReceiptOperation[];
129
- readonly resourceScopes: readonly ReceiptResourceScope[];
130
- readonly pinnedOperationTargetIdentity?: string;
131
- readonly transitionDigest: string;
132
- };
133
- export type ReceiptProgressionSnapshot = ReceiptEpochProgressionSnapshot | ReceiptUnitProgressionSnapshot;
134
- export interface ReceiptReadbackProgression {
135
- readonly epoch: ReceiptEpochProgressionSnapshot | null;
136
- readonly unit: ReceiptUnitProgressionSnapshot | null;
137
- }
138
- export interface ReceiptReadbackState {
139
- readonly registrationDigest: string;
140
- readonly receipts: readonly ReceiptEnvelope[];
141
- readonly progression: ReceiptReadbackProgression;
142
- }
143
- export type ReceiptMarkerValidation = {
144
- readonly status: 'valid';
145
- readonly marker: ReceiptMarker;
146
- } | {
147
- readonly status: 'rejected';
148
- readonly category: ReceiptReadbackFailureCategory;
149
- };
150
- export type ReceiptReadbackResult = {
151
- readonly status: 'reconstructed';
152
- readonly state: ReceiptReadbackState;
153
- } | {
154
- readonly status: 'rejected';
155
- readonly category: ReceiptReadbackFailureCategory;
156
- };
157
- export type ReceiptReadbackSeedResult = {
158
- readonly status: 'empty';
159
- } | {
160
- readonly status: 'ready';
161
- readonly sessionSalt: Uint8Array;
162
- readonly registrationDigest: string;
163
- readonly capabilityFlags: readonly string[];
164
- } | {
165
- readonly status: 'repair-required';
166
- readonly category: ReceiptReadbackFailureCategory;
167
- };
168
- export declare function digestReceiptIdentity(domain: ReceiptDigestDomain, identity: string, sessionSalt: Uint8Array): string;
169
- export declare function validateReceiptMarker(input: unknown): ReceiptMarkerValidation;
170
- /**
171
- * Filters a raw marker array, retaining only markers that belong to the given
172
- * registrationDigest. Markers that cannot be parsed (malformed, unknown schema,
173
- * etc.) are retained as-is so that downstream callers can fail-closed on them.
174
- *
175
- * Use this before extractReceiptReadbackSeed / foldReceiptReadback when the
176
- * shared metadata array may contain markers from multiple concurrent
177
- * registrations (e.g. dual-registration in a single OpenCode session).
178
- */
179
- export declare function filterMarkersByRegistration(markers: readonly unknown[], ownRegistrationDigest: string): unknown[];
180
- export declare function extractReceiptReadbackSeed(inputs: readonly unknown[]): ReceiptReadbackSeedResult;
181
- export declare function projectReceiptMintMarker(receipt: unknown, sessionSalt: Uint8Array): ReceiptMintMarker | undefined;
182
- export declare function projectReceiptConsumptionMarker(receipt: unknown, transitionDigest: string, timestamp?: number): ReceiptConsumeMarker | undefined;
183
- export declare function projectReceiptProgressionMarker(source: ReceiptProgressionProjectionSource, input: ReceiptProgressionMarkerInput): ReceiptProgressionMarker | undefined;
184
- export declare function foldReceiptReadback(inputs: readonly unknown[], expectation: ReceiptReadbackExpectation): ReceiptReadbackResult;
185
- export declare function receiptReadbackExpectationFromMetadata(metadata: ReceiptLedgerMetadata, sessionSalt: Uint8Array, operationTargetIdentity?: string): ReceiptReadbackExpectation;
186
- export {};