prizmkit 1.1.166 → 1.1.169

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,164 +1,125 @@
1
- # Deployment Verification and Recovery Contract
1
+ # Deployment Verification and Recovery
2
2
 
3
- Use this contract after each planned step, after any failure or interruption, and before selecting a terminal status. Verification observes actual state; it does not infer success from a command exit, API acceptance, or user action alone.
3
+ Use this reference after an action, when a required observation fails, after an unknown write outcome or interruption, and before returning a deployment result. Verification observes actual state; it does not infer success from a zero exit, accepted request, healthy old release, or repeated execution of a stronger producer.
4
4
 
5
- ## Layered Verification
5
+ ## Minimum Sufficient Verification
6
6
 
7
- Evaluate all five layers and record each named layer exactly once:
7
+ Build the observation set from the selected Profile and actual target. Each observation contains:
8
8
 
9
9
  ```text
10
- PASSED, FAILED, INACCESSIBLE, NOT_APPLICABLE
10
+ name, required, status, evidence
11
11
  ```
12
12
 
13
- | Layer | Evidence | Applicability rule |
14
- |---|---|---|
15
- | `command_or_platform` | Exit/result plus target-native operation identity and completion state, not merely request acceptance | Applicable to every executed automated action; manual-only operations explain `NOT_APPLICABLE`. |
16
- | `runtime_or_release` | Intended process/service/container/release exists, has expected identity/version, and is in the required state | Applicable when the operation creates, starts, stops, restarts, promotes, or rolls back a runtime/release. |
17
- | `configured_health` | Every configured required project health check meets its explicit expectation | Applicable when a health boundary exists; absence is reported and never replaced with an invented endpoint. |
18
- | `external_url` | Intended externally observed endpoint reaches the expected release/behavior through the real traffic path | Applicable when an external URL is configured and accessible from the controller boundary. |
19
- | `startup_logs` | Bounded, redacted project-owned startup window contains no planned fatal condition | Applicable when startup output exists and access is authorized; specify time and/or line bound. |
13
+ Status is one of:
20
14
 
21
- For every layer store whether it is required and a concise redacted evidence statement. `INACCESSIBLE` and `NOT_APPLICABLE` are not passes. A required layer must be `PASSED` for `SUCCEEDED`; required `FAILED`, `INACCESSIBLE`, or `NOT_APPLICABLE` prevents success. Optional inaccessible or inapplicable layers remain visible in residual risk. Before persisting or trusting the result, validate the complete record with both `${SKILL_DIR}/references/deploy-record-schema.json` and `${SKILL_DIR}/scripts/validate-deploy-artifact.py --kind record` so omitted, duplicate, or contradictory layers fail closed.
15
+ ```text
16
+ PASSED, FAILED, INACCESSIBLE, NOT_APPLICABLE
17
+ ```
22
18
 
23
- A configured required health check failing after an otherwise successful command makes the operation `FAILED`. Do not downgrade it to a warning.
19
+ Use configured project-native health and external paths when they exist. Do not invent a conventional health URL or port. When no dedicated health boundary exists, the minimum deployment evidence is:
24
20
 
25
- ## Evidence Rules
21
+ 1. the selected target operation completed rather than merely being accepted;
22
+ 2. the expected runtime/release identity exists;
23
+ 3. the intended live/offline state is observed;
24
+ 4. a bounded startup/log observation has no known fatal condition when such output exists and is accessible.
26
25
 
27
- - Re-observe state after the action; do not reuse pre-action evidence as proof of a postcondition.
28
- - Bind release/runtime observations to the intended target profile and release identity.
29
- - Distinguish controller result, target-control-plane result, and target workload state.
30
- - Use actual configured ports/endpoints and target-native identities.
31
- - Bound all output. Persist only concise summaries, never raw command output or full logs.
32
- - Redact Secret-bearing URLs, headers, environment assignments, tokens, keys, cookies, connection strings, and user-identified patterns before display or storage.
33
- - If evidence may be sensitive and reliable redaction is unavailable, mark the layer `INACCESSIBLE` and provide a manual verification action.
26
+ A local development Profile may succeed on that minimum. A Profile policy may require configured health, an external URL, or the real traffic path; every required observation must be `PASSED`. `INACCESSIBLE` and `NOT_APPLICABLE` remain truthful results, not passes.
34
27
 
35
- ## Terminal Status Decision
28
+ Reuse current project-native build/test/package evidence only when it matches source/release, toolchain, selected command scope, target assumptions, and terminal result. Verification consumes producer evidence and observes runtime postconditions; it does not rerun the producer.
36
29
 
37
- Exactly one terminal status is returned:
30
+ Bind every observation to the selected Profile, target fingerprint, and desired release. Bound and redact evidence. Persist concise statements, never raw output or full logs.
38
31
 
39
- | Status | Required condition |
40
- |---|---|
41
- | `SUCCEEDED` | All planned steps completed, all required applicable verification layers are `PASSED`, no effect remains unknown, and the required sole-record update was verified. |
42
- | `FAILED` | Confirmed execution occurred but a step, required verification layer, rollback attempt, cleanup required for correctness, or required local-record update failed. Report actual live state. |
43
- | `BLOCKED` | Safe continuation cannot be established because capability/evidence/authorization is absent, input conflicts, plan validity changed, an unknown effect remains indeterminate, or destructive impact cannot be bounded. |
44
- | `WAITING_USER` | Execution is safely paused for an exact confirmation, login, MFA, browser approval, manual action, or separately authorized test boundary. Minimal recovery is available when its write was confirmed. |
45
- | `CANCELLED` | The operator cancelled; no further unconfirmed action ran, and confirmed safe cleanup plus residual-resource reporting completed. |
32
+ ## Convergence Verification
46
33
 
47
- Partial completion is never `SUCCEEDED`. A release can be live while the operation is `FAILED`; say both. A control-plane “accepted,” queued, or zero-exit response is not success until required layers pass.
34
+ For redeploy, observe:
48
35
 
49
- ## Final Result
36
+ - desired live release identity and expected replicas;
37
+ - actual live/traffic selector and whether old/new units receive traffic;
38
+ - bounded rollback releases retained by Profile policy;
39
+ - persistent data and shared dependencies preserved;
40
+ - exact superseded, failed, temporary, orphaned, and locked resources required to be absent.
50
41
 
51
- Return and, when confirmed, persist the complete terminal result defined by `${SKILL_DIR}/references/deploy-record-schema.json` and accepted by the shipped semantic validator:
42
+ Do not mark old live superseded before the desired candidate reaches handoff. Success requires desired live plus the expected retained/retired inventory. A healthy desired release with required old runtime/orphans remaining is not converged. Unknown ownership remains one shared/ownership decision and prevents destructive cleanup.
52
43
 
53
- - terminal status and operation;
54
- - target profile and immutable plan identity;
55
- - start/finish boundary and concise summary;
56
- - observed live state and release identity;
57
- - rollback availability: `VERIFIED`, `UNVERIFIED`, `ABSENT`, `UNKNOWN`, or `NOT_APPLICABLE`;
58
- - every verification layer with required flag, status, and evidence;
59
- - residual releases, processes, artifacts, locks, migrations, traffic state, and other project-owned resources;
60
- - local-record update result;
61
- - exact recovery guidance and relevant next operations.
44
+ ## Forward Progress
62
45
 
63
- Report inaccessible or inapplicable layers explicitly. Never fill missing evidence with `PASSED`.
46
+ On an ordinary failure, keep the desired release fixed and preserve evidence about the last proven action. Then:
64
47
 
65
- ## Failure Handling
48
+ 1. stop only actions that depend on the failed postcondition;
49
+ 2. observe current target, live selector, runtime, data, and exact owned temporary resources;
50
+ 3. classify a possible write as applied, not applied, or indeterminate;
51
+ 4. perform already-authorized cleanup that cannot harm old live, persistent data, or shared resources;
52
+ 5. choose the smallest bounded diagnostic action;
53
+ 6. repair deployment configuration, restart, or redeploy the same desired release when current evidence proves that next action;
54
+ 7. return `WAITING_USER` with one action when no automatic forward action remains.
66
55
 
67
- At the first failed step or required layer:
56
+ A temporary return to the previous release is not deployment success. Use emergency isolation or temporary old traffic only to contain data damage, security exposure, or continuing user harm. The desired release remains pending until it becomes live and converged or no safe path exists.
68
57
 
69
- 1. stop dependent actions and plan expansion;
70
- 2. bound and redact the failure evidence;
71
- 3. observe current target/release/runtime/data/traffic state read-only;
72
- 4. classify every planned write as proven applied, proven not applied, or indeterminate;
73
- 5. perform only cleanup already authorized by the immutable plan and safe in the observed state;
74
- 6. determine rollback availability from current evidence;
75
- 7. select `FAILED`, `BLOCKED`, or `WAITING_USER` truthfully;
76
- 8. preserve residual resources needed for diagnosis unless confirmed cleanup says otherwise.
58
+ Each individual action has a finite attempt/resource budget. Forward progress can choose a different proven action after a budget is exhausted, but it never converts retries into an unbounded loop.
77
59
 
78
- Never automatically replay an indeterminate write. Follow the `unknown_outcome_inspection` step. Only proven read-only or idempotent actions may use bounded retry.
60
+ ## Failure Boundaries
79
61
 
80
- ### Failure Before Any Write
62
+ ### Before a Write
81
63
 
82
- If a precondition or capability fails before execution, live state remains unchanged. Return `BLOCKED` when continuation lacks evidence/authorization or `FAILED` when confirmed execution itself failed. Do not create a misleading release/history event file.
64
+ A failed prerequisite or capacity check leaves target live state unchanged. Choose a smaller safe action, request one exact human action, or return `FAILED` when the desired release cannot be made deployable and no continuation exists. Report any exact temporary resource already created.
83
65
 
84
- ### Failure After a Write
66
+ ### Before Handoff
85
67
 
86
- State the applied/unknown effects, current live release, health, traffic, data state, residual resources, and whether old/new units coexist. A healthy previous release does not erase a failed candidate operation.
68
+ Keep the proven old release live. Diagnose or clean only the exact failed candidate resources authorized by the deployment envelope. Do not delete old live to force progress.
87
69
 
88
- ### Failed Health
70
+ ### After Handoff
89
71
 
90
- Required health failure always fails the operation. If traffic/live selection changed, inspect actual live state and apply only a pre-confirmed verified rollback; otherwise stop and offer the verified rollback or manual recovery.
72
+ Observe the actual selector and both release states before repair, retirement, or emergency traffic protection. Prefer repair/restart/redeploy of desired. Never remove persistent/shared dependencies or hide failed convergence by deleting unexplained resources.
91
73
 
92
- ### Local Record Failure
74
+ ### Required Health Failure
93
75
 
94
- If the live target changed but the required `.prizmkit/deploy/deploy.json` update or read-back validation failed:
76
+ A required health failure prevents `SUCCEEDED`, but it does not force terminal rollback. Observe current state and continue through a different bounded forward action when available. Emergency protection remains temporary and does not complete the desired deployment.
95
77
 
96
- - return `FAILED`;
97
- - report that the target may be live and local state is stale;
98
- - preserve the candidate temporary/legacy evidence without overwriting uncertain files;
99
- - require read-only target rediscovery before any later record repair or deployment;
100
- - never replay the deployment to repair the record.
78
+ ### Profile Record Failure
101
79
 
102
- ## Rollback
80
+ A Profile record failure does not authorize replaying target writes or rolling back a healthy desired release. Report actual live/convergence state and that local evidence is stale, preserve the rejected candidate record, and rediscover target state before a later record repair. The conversation result may describe a live successful target while separately reporting the record failure; never claim the record was updated.
103
81
 
104
- A rollback is `VERIFIED` only when current evidence establishes:
82
+ ## Unknown Outcome
105
83
 
106
- - exact prior release/configuration/data identity;
107
- - required artifacts/state still exist and match the target;
108
- - rollback action and authorization are available;
109
- - compatibility with the current persistent-data state;
110
- - rollback verification and restore-on-rollback-failure behavior.
84
+ After timeout, disconnect, or interruption during a possible write:
111
85
 
112
- `UNVERIFIED`, `UNKNOWN`, or `ABSENT` rollback is not offered as an automated safety guarantee.
86
+ 1. inspect target state using the planned project-scoped read-only observation;
87
+ 2. if applied, verify postconditions without replay;
88
+ 3. if not applied, retry only when the action is proven idempotent and its budget remains;
89
+ 4. if indeterminate, return `WAITING_USER` with the exact inspection/replay decision and duplicate-effect warning.
113
90
 
114
- A rollback may run automatically only when it was explicitly part of the confirmed immutable failure plan and its preconditions still match. Otherwise show the exact rollback plan/effects and obtain confirmation. Rollback itself uses all applicable verification layers. Failed rollback leaves the operation `FAILED` and reports both attempted states.
91
+ Never infer “not applied” from a missing response. Never rerun a material producer merely to reconstruct history.
115
92
 
116
- When rollback is absent, do not block a deploy that received exact `NO_RELIABLE_ROLLBACK` risk acceptance. On failure, provide live-state evidence, residual resources, the earliest safe manual stop point, and a concrete manual recovery procedure. Do not claim the old release can be restored.
93
+ ## Interruption and Resume
117
94
 
118
- ## Interruption and Unknown Remote State
95
+ Load only the selected Profile record's current, latest result, minimal recovery, and bounded observations. Then rediscover project revision, target fingerprint, authentication identity, desired release eligibility, actual live/candidate inventory, selector, owned residuals, configured health, and relevant tool capability.
119
96
 
120
- A process/session interruption does not reveal whether the target wrote state. On recovery:
97
+ Resume from the first unproven current→desired action. Do not reconstruct commands from history summaries. When observed identity/effects differ, discard the stale proposed action and derive the next action from current evidence. If another operation already targets the same Profile/desired release, attach to it rather than creating a candidate.
121
98
 
122
- 1. validate the sole local record with both schema and semantic validation without dropping unknown data;
123
- 2. load only `plan_id`, Secret-free plan digest, operation/profile, last proven step, minimal confirmation receipts, pending checkpoint, and bounded observations from `recovery`;
124
- 3. rediscover project revision, target identity, authentication identity, tool capability/version, native configuration, actual ports, live/release/runtime/data/traffic state, health boundary, and rollback evidence affected by the plan;
125
- 4. recompile the complete candidate plan from current authoritative evidence and compare its Secret-free digest with the stored immutable digest; never reconstruct actions from history summaries;
126
- 5. inspect each possibly executed write before replay;
127
- 6. continue only from the first unproven step when earlier postconditions are proven and every required confirmation receipt matches the digest; when a receipt is absent or cannot be validated, request fresh confirmation;
128
- 7. compile and preview a new plan when identity, command/action, effect, risk, scope, or evidence assumption changed;
129
- 8. clear recovery only after a verified terminal result is safely recorded.
99
+ A human “done” response is a signal to revalidate the pending postcondition, not proof. Clear recovery only after `SUCCEEDED` or a non-resumable `FAILED` result is recorded.
130
100
 
131
- Do not reconstruct commands from history summaries. Do not infer “not applied” from a missing client response. Do not claim concurrent session safety; this procedure assumes one operator.
101
+ ## Terminal Decision
132
102
 
133
- ## Human Checkpoint Recovery
103
+ Return exactly one status:
134
104
 
135
- For login, MFA, browser approval, confirmation, or another manual action:
136
-
137
- - record `WAITING_USER`, exact non-sensitive action, and expected postcondition;
138
- - never store a password, token, challenge, browser cookie, one-time code, approval URL containing credentials, or raw authentication output;
139
- - after the user reports completion, re-run the planned read-only identity/authorization/postcondition probes;
140
- - remain `WAITING_USER` or become `BLOCKED` when revalidation fails;
141
- - resume only when the immutable plan and target identity still match.
142
-
143
- The user's “done” is a signal to revalidate, not verification itself.
105
+ | Status | Condition |
106
+ |---|---|
107
+ | `SUCCEEDED` | Desired release is live when deployment applies, all required observations pass, required inventory converges, and no effect needed for correctness remains unknown. |
108
+ | `WAITING_USER` | One identity, target, irreversible-data, shared/ownership, source-fix, or indeterminate-outcome action can resume the same desired operation. |
109
+ | `FAILED` | No safe continuation exists, the desired release is unsupported/unrecoverable within scope, or the user stopped the operation. |
144
110
 
145
- ## Bounded Retry
111
+ A release may be live while a Profile record update failed; state both facts. A healthy old release, completed rollback, or partially live candidate never converts an incomplete desired deployment to `SUCCEEDED`.
146
112
 
147
- Retry only when the immutable plan identifies the action as proven read-only or idempotent, the error as transient, the maximum attempts as greater than the current attempt, and the stop condition as unmet. Report each attempt without a duration promise.
113
+ ## Final Result
148
114
 
149
- Never retry automatically after authentication denial, invalid input, migration uncertainty, destructive failure, required health failure, plan mismatch, or an indeterminate write.
115
+ Return and, when valid, persist one concise result containing:
150
116
 
151
- ## Deterministic Recovery Cases
117
+ - status and operation;
118
+ - selected Profile and target reference;
119
+ - desired and actual live release;
120
+ - each selected verification observation with required/status/evidence;
121
+ - bounded residual resources and rollback availability;
122
+ - one exact pending action for `WAITING_USER` or evidence-backed reason for `FAILED`;
123
+ - Profile record update outcome in the conversation summary.
152
124
 
153
- | Observed case | Terminal/result behavior |
154
- |---|---|
155
- | Command result passed; required configured health failed | `FAILED`; report actual live state and verified rollback availability |
156
- | External URL required but controller cannot access it | `FAILED` or `BLOCKED` according to whether execution occurred; layer is `INACCESSIBLE`, never `PASSED` |
157
- | Startup logs do not exist for this target | Layer is `NOT_APPLICABLE` with reason |
158
- | Login or browser approval is required | `WAITING_USER`; persist minimal checkpoint only after confirmed record write |
159
- | Possible write timed out; inspection proves applied | Do not replay; continue verification from the proven postcondition |
160
- | Possible write timed out; inspection proves not applied | Retry only within confirmed idempotent policy |
161
- | Possible write timed out; inspection is indeterminate | `BLOCKED` or `WAITING_USER`; replay needs dedicated confirmation |
162
- | Rollback is verified after failed required health | Offer or run only according to confirmed rollback policy, then verify rollback |
163
- | Rollback is absent after partial release | `FAILED` with live state, residual resources, and manual recovery |
164
- | Live release is healthy but sole-record write failed | `FAILED`; state target-live/local-record-stale and rediscover before repair |
125
+ Do not persist unrelated conversation, confirmation transcripts, raw diagnostics, credentials, or full logs. Secret values and credential-bearing URLs/headers/environment assignments are omitted before display or storage.