prizmkit 1.1.166 → 1.1.167
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/bundled/VERSION.json +3 -3
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/prizmkit-deploy/SKILL.md +97 -153
- package/bundled/skills/prizmkit-deploy/references/capability-contract.md +59 -110
- package/bundled/skills/prizmkit-deploy/references/deploy-record-schema.json +134 -667
- package/bundled/skills/prizmkit-deploy/references/deployment-declaration-schema.json +78 -191
- package/bundled/skills/prizmkit-deploy/references/legacy-migration.md +50 -69
- package/bundled/skills/prizmkit-deploy/references/policy-and-execution.md +104 -138
- package/bundled/skills/prizmkit-deploy/references/real-resource-test-policy.md +6 -6
- package/bundled/skills/prizmkit-deploy/references/verification-and-recovery.md +76 -115
- package/bundled/skills/prizmkit-deploy/scripts/validate-deploy-artifact.py +96 -171
- package/package.json +1 -1
|
@@ -1,164 +1,125 @@
|
|
|
1
|
-
# Deployment Verification and Recovery
|
|
1
|
+
# Deployment Verification and Recovery
|
|
2
2
|
|
|
3
|
-
Use this
|
|
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
|
-
##
|
|
5
|
+
## Minimum Sufficient Verification
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Build the observation set from the selected Profile and actual target. Each observation contains:
|
|
8
8
|
|
|
9
9
|
```text
|
|
10
|
-
|
|
10
|
+
name, required, status, evidence
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
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
|
-
|
|
15
|
+
```text
|
|
16
|
+
PASSED, FAILED, INACCESSIBLE, NOT_APPLICABLE
|
|
17
|
+
```
|
|
22
18
|
|
|
23
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
34
|
+
For redeploy, observe:
|
|
48
35
|
|
|
49
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
46
|
+
On an ordinary failure, keep the desired release fixed and preserve evidence about the last proven action. Then:
|
|
64
47
|
|
|
65
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
60
|
+
## Failure Boundaries
|
|
79
61
|
|
|
80
|
-
###
|
|
62
|
+
### Before a Write
|
|
81
63
|
|
|
82
|
-
|
|
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
|
-
###
|
|
66
|
+
### Before Handoff
|
|
85
67
|
|
|
86
|
-
|
|
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
|
-
###
|
|
70
|
+
### After Handoff
|
|
89
71
|
|
|
90
|
-
|
|
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
|
-
###
|
|
74
|
+
### Required Health Failure
|
|
93
75
|
|
|
94
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
82
|
+
## Unknown Outcome
|
|
105
83
|
|
|
106
|
-
|
|
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
|
-
|
|
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
|
-
|
|
91
|
+
Never infer “not applied” from a missing response. Never rerun a material producer merely to reconstruct history.
|
|
115
92
|
|
|
116
|
-
|
|
93
|
+
## Interruption and Resume
|
|
117
94
|
|
|
118
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
101
|
+
## Terminal Decision
|
|
132
102
|
|
|
133
|
-
|
|
103
|
+
Return exactly one status:
|
|
134
104
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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
|
-
|
|
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
|
-
|
|
113
|
+
## Final Result
|
|
148
114
|
|
|
149
|
-
|
|
115
|
+
Return and, when valid, persist one concise result containing:
|
|
150
116
|
|
|
151
|
-
|
|
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
|
-
|
|
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.
|
|
@@ -1,10 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
|
-
"""Validate non-sensitive semantic invariants for PrizmKit Deploy artifacts.
|
|
2
|
+
"""Validate non-sensitive semantic invariants for PrizmKit Deploy v2 artifacts.
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
host-neutral path rules that are awkward to express or easy to regress in a
|
|
7
|
-
schema alone. Diagnostics contain stable codes and JSON paths, never values.
|
|
4
|
+
JSON Schema validation remains mandatory. This read-only standard-library companion
|
|
5
|
+
checks cross-field rules and emits only bounded stable codes plus JSON paths.
|
|
8
6
|
"""
|
|
9
7
|
|
|
10
8
|
from __future__ import annotations
|
|
@@ -21,13 +19,6 @@ from typing import Any, Iterable, Mapping, Sequence
|
|
|
21
19
|
|
|
22
20
|
MAX_INPUT_BYTES = 1024 * 1024
|
|
23
21
|
MAX_ERRORS = 50
|
|
24
|
-
VERIFICATION_LAYERS = {
|
|
25
|
-
"command_or_platform",
|
|
26
|
-
"runtime_or_release",
|
|
27
|
-
"configured_health",
|
|
28
|
-
"external_url",
|
|
29
|
-
"startup_logs",
|
|
30
|
-
}
|
|
31
22
|
FORBIDDEN_FIELDS = {
|
|
32
23
|
"value",
|
|
33
24
|
"secret_value",
|
|
@@ -43,7 +34,7 @@ _DRIVE_PREFIX = re.compile(r"^[A-Za-z]:")
|
|
|
43
34
|
|
|
44
35
|
|
|
45
36
|
class DuplicateKeyError(ValueError):
|
|
46
|
-
"""Raised for a duplicate object key without retaining its
|
|
37
|
+
"""Raised for a duplicate object key without retaining its content."""
|
|
47
38
|
|
|
48
39
|
|
|
49
40
|
@dataclass(frozen=True, order=True)
|
|
@@ -62,9 +53,8 @@ class ErrorCollector:
|
|
|
62
53
|
self._errors: set[ValidationError] = set()
|
|
63
54
|
|
|
64
55
|
def add(self, code: str, path: str) -> None:
|
|
65
|
-
if len(self._errors)
|
|
66
|
-
|
|
67
|
-
self._errors.add(ValidationError(code=code, path=path))
|
|
56
|
+
if len(self._errors) < MAX_ERRORS:
|
|
57
|
+
self._errors.add(ValidationError(code=code, path=path))
|
|
68
58
|
|
|
69
59
|
def result(self) -> list[dict[str, str]]:
|
|
70
60
|
return [error.as_dict() for error in sorted(self._errors)]
|
|
@@ -97,44 +87,30 @@ def _load_json(path: Path) -> tuple[Any | None, list[dict[str, str]]]:
|
|
|
97
87
|
return None, [{"code": "INVALID_JSON", "path": "$"}]
|
|
98
88
|
|
|
99
89
|
|
|
100
|
-
def
|
|
90
|
+
def _iter_list(value: Any) -> Iterable[tuple[int, Any]]:
|
|
91
|
+
if isinstance(value, list):
|
|
92
|
+
return enumerate(value)
|
|
93
|
+
return ()
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _is_project_relative_path(value: Any) -> bool:
|
|
101
97
|
if not isinstance(value, str) or not value or len(value) > 512:
|
|
102
98
|
return False
|
|
103
|
-
if value == ".":
|
|
104
|
-
return allow_root
|
|
105
99
|
if value.startswith("/") or _DRIVE_PREFIX.match(value) or "\\" in value:
|
|
106
100
|
return False
|
|
107
101
|
if any(unicodedata.category(character) in {"Cc", "Cs"} for character in value):
|
|
108
102
|
return False
|
|
109
|
-
|
|
110
|
-
return all(part not in {"", ".", ".."} for part in parts)
|
|
111
|
-
|
|
103
|
+
return all(part not in {"", ".", ".."} for part in value.split("/"))
|
|
112
104
|
|
|
113
|
-
def _is_legacy_deploy_path(value: Any) -> bool:
|
|
114
|
-
return _is_project_relative_path(value) and str(value).startswith(".prizmkit/deploy/")
|
|
115
105
|
|
|
116
|
-
|
|
117
|
-
def _iter_list(value: Any) -> Iterable[tuple[int, Any]]:
|
|
118
|
-
if not isinstance(value, list):
|
|
119
|
-
return ()
|
|
120
|
-
return enumerate(value)
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
def _check_path_list(
|
|
124
|
-
value: Any,
|
|
125
|
-
path: str,
|
|
126
|
-
errors: ErrorCollector,
|
|
127
|
-
*,
|
|
128
|
-
legacy: bool = False,
|
|
129
|
-
) -> None:
|
|
130
|
-
predicate = _is_legacy_deploy_path if legacy else _is_project_relative_path
|
|
106
|
+
def _check_path_list(value: Any, path: str, errors: ErrorCollector) -> None:
|
|
131
107
|
for index, item in _iter_list(value):
|
|
132
|
-
if not
|
|
108
|
+
if not _is_project_relative_path(item):
|
|
133
109
|
errors.add("UNSAFE_MANAGED_PATH", f"{path}[{index}]")
|
|
134
110
|
|
|
135
111
|
|
|
136
|
-
def _check_forbidden_fields(value: Any,
|
|
137
|
-
pending: list[tuple[Any, str]] = [(value,
|
|
112
|
+
def _check_forbidden_fields(value: Any, errors: ErrorCollector) -> None:
|
|
113
|
+
pending: list[tuple[Any, str]] = [(value, "$")]
|
|
138
114
|
while pending:
|
|
139
115
|
current, current_path = pending.pop()
|
|
140
116
|
if isinstance(current, Mapping):
|
|
@@ -154,7 +130,7 @@ def _check_forbidden_fields(value: Any, path: str, errors: ErrorCollector) -> No
|
|
|
154
130
|
)
|
|
155
131
|
|
|
156
132
|
|
|
157
|
-
def
|
|
133
|
+
def _unique_identities(
|
|
158
134
|
value: Any,
|
|
159
135
|
path: str,
|
|
160
136
|
field: str,
|
|
@@ -174,44 +150,35 @@ def _check_unique_names(
|
|
|
174
150
|
return seen
|
|
175
151
|
|
|
176
152
|
|
|
177
|
-
def
|
|
178
|
-
value: Any,
|
|
179
|
-
path: str,
|
|
180
|
-
profiles: set[str],
|
|
181
|
-
errors: ErrorCollector,
|
|
182
|
-
) -> None:
|
|
183
|
-
if value is not None and isinstance(value, str) and value not in profiles:
|
|
184
|
-
errors.add("DANGLING_PROFILE_REFERENCE", path)
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
def _check_terminal_result(value: Any, path: str, errors: ErrorCollector) -> None:
|
|
153
|
+
def _check_result(value: Any, path: str, errors: ErrorCollector) -> None:
|
|
188
154
|
if not isinstance(value, Mapping):
|
|
189
155
|
return
|
|
190
156
|
verification = value.get("verification")
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
157
|
+
names = _unique_identities(
|
|
158
|
+
verification,
|
|
159
|
+
f"{path}.verification",
|
|
160
|
+
"name",
|
|
161
|
+
"DUPLICATE_VERIFICATION_OBSERVATION",
|
|
162
|
+
errors,
|
|
163
|
+
)
|
|
164
|
+
if isinstance(verification, list) and not names:
|
|
165
|
+
errors.add("EMPTY_VERIFICATION", f"{path}.verification")
|
|
194
166
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
):
|
|
211
|
-
errors.add(
|
|
212
|
-
"SUCCEEDED_REQUIRED_LAYER_NOT_PASSED",
|
|
213
|
-
f"{path}.verification[{index}]",
|
|
214
|
-
)
|
|
167
|
+
if value.get("status") != "SUCCEEDED":
|
|
168
|
+
return
|
|
169
|
+
for index, item in _iter_list(verification):
|
|
170
|
+
if (
|
|
171
|
+
isinstance(item, Mapping)
|
|
172
|
+
and item.get("required") is True
|
|
173
|
+
and item.get("status") != "PASSED"
|
|
174
|
+
):
|
|
175
|
+
errors.add(
|
|
176
|
+
"SUCCEEDED_REQUIRED_OBSERVATION_NOT_PASSED",
|
|
177
|
+
f"{path}.verification[{index}]",
|
|
178
|
+
)
|
|
179
|
+
desired = value.get("desired_release")
|
|
180
|
+
if desired is not None and value.get("live_release") != desired:
|
|
181
|
+
errors.add("SUCCEEDED_RELEASE_MISMATCH", f"{path}.live_release")
|
|
215
182
|
|
|
216
183
|
|
|
217
184
|
def _validate_record(data: Any, errors: ErrorCollector) -> None:
|
|
@@ -219,87 +186,43 @@ def _validate_record(data: Any, errors: ErrorCollector) -> None:
|
|
|
219
186
|
errors.add("ROOT_NOT_OBJECT", "$")
|
|
220
187
|
return
|
|
221
188
|
|
|
222
|
-
|
|
223
|
-
if isinstance(project, Mapping):
|
|
224
|
-
_check_path_list(
|
|
225
|
-
project.get("native_config_files"),
|
|
226
|
-
"$.project.native_config_files",
|
|
227
|
-
errors,
|
|
228
|
-
)
|
|
229
|
-
|
|
230
|
-
profiles_value = data.get("profiles")
|
|
231
|
-
profiles = _check_unique_names(
|
|
232
|
-
profiles_value,
|
|
233
|
-
"$.profiles",
|
|
234
|
-
"id",
|
|
235
|
-
"DUPLICATE_PROFILE_ID",
|
|
236
|
-
errors,
|
|
237
|
-
)
|
|
238
|
-
for index, profile in _iter_list(profiles_value):
|
|
239
|
-
if isinstance(profile, Mapping):
|
|
240
|
-
_check_path_list(
|
|
241
|
-
profile.get("native_config_files"),
|
|
242
|
-
f"$.profiles[{index}].native_config_files",
|
|
243
|
-
errors,
|
|
244
|
-
)
|
|
245
|
-
|
|
246
|
-
_check_unique_names(
|
|
189
|
+
_unique_identities(
|
|
247
190
|
data.get("secret_references"),
|
|
248
191
|
"$.secret_references",
|
|
249
192
|
"name",
|
|
250
193
|
"DUPLICATE_SECRET_REFERENCE",
|
|
251
194
|
errors,
|
|
252
195
|
)
|
|
253
|
-
|
|
254
|
-
current = data.get("current")
|
|
255
|
-
if isinstance(current, Mapping):
|
|
256
|
-
_check_profile_reference(
|
|
257
|
-
current.get("profile_id"),
|
|
258
|
-
"$.current.profile_id",
|
|
259
|
-
profiles,
|
|
260
|
-
errors,
|
|
261
|
-
)
|
|
262
|
-
|
|
263
196
|
latest = data.get("latest_result")
|
|
264
|
-
|
|
265
|
-
_check_profile_reference(
|
|
266
|
-
latest.get("profile_id"),
|
|
267
|
-
"$.latest_result.profile_id",
|
|
268
|
-
profiles,
|
|
269
|
-
errors,
|
|
270
|
-
)
|
|
271
|
-
_check_terminal_result(latest, "$.latest_result", errors)
|
|
272
|
-
|
|
273
|
-
for index, history in _iter_list(data.get("history")):
|
|
274
|
-
if isinstance(history, Mapping):
|
|
275
|
-
_check_profile_reference(
|
|
276
|
-
history.get("profile_id"),
|
|
277
|
-
f"$.history[{index}].profile_id",
|
|
278
|
-
profiles,
|
|
279
|
-
errors,
|
|
280
|
-
)
|
|
197
|
+
_check_result(latest, "$.latest_result", errors)
|
|
281
198
|
|
|
282
199
|
recovery = data.get("recovery")
|
|
283
|
-
if isinstance(
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
errors,
|
|
289
|
-
|
|
200
|
+
if not isinstance(latest, Mapping) and recovery is not None:
|
|
201
|
+
errors.add("ORPHAN_RECOVERY", "$.recovery")
|
|
202
|
+
if isinstance(latest, Mapping):
|
|
203
|
+
status = latest.get("status")
|
|
204
|
+
if status == "WAITING_USER" and not isinstance(recovery, Mapping):
|
|
205
|
+
errors.add("WAITING_USER_RECOVERY_REQUIRED", "$.recovery")
|
|
206
|
+
if status in {"SUCCEEDED", "FAILED"} and recovery is not None:
|
|
207
|
+
errors.add("TERMINAL_RECOVERY_FORBIDDEN", "$.recovery")
|
|
208
|
+
if status == "WAITING_USER" and isinstance(recovery, Mapping):
|
|
209
|
+
if recovery.get("operation") != latest.get("operation"):
|
|
210
|
+
errors.add("RECOVERY_OPERATION_MISMATCH", "$.recovery.operation")
|
|
211
|
+
if recovery.get("desired_release") != latest.get("desired_release"):
|
|
212
|
+
errors.add(
|
|
213
|
+
"RECOVERY_DESIRED_RELEASE_MISMATCH",
|
|
214
|
+
"$.recovery.desired_release",
|
|
215
|
+
)
|
|
290
216
|
|
|
291
|
-
|
|
292
|
-
if
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
errors,
|
|
301
|
-
legacy=True,
|
|
302
|
-
)
|
|
217
|
+
current = data.get("current")
|
|
218
|
+
if (
|
|
219
|
+
isinstance(latest, Mapping)
|
|
220
|
+
and latest.get("status") == "SUCCEEDED"
|
|
221
|
+
and isinstance(current, Mapping)
|
|
222
|
+
and latest.get("desired_release") is not None
|
|
223
|
+
and current.get("release_identity") != latest.get("desired_release")
|
|
224
|
+
):
|
|
225
|
+
errors.add("CURRENT_RELEASE_MISMATCH", "$.current.release_identity")
|
|
303
226
|
|
|
304
227
|
|
|
305
228
|
def _validate_declaration(data: Any, errors: ErrorCollector) -> None:
|
|
@@ -308,14 +231,26 @@ def _validate_declaration(data: Any, errors: ErrorCollector) -> None:
|
|
|
308
231
|
return
|
|
309
232
|
|
|
310
233
|
_check_path_list(data.get("native_config_files"), "$.native_config_files", errors)
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
234
|
+
profiles_value = data.get("profiles")
|
|
235
|
+
profiles = _unique_identities(
|
|
236
|
+
profiles_value,
|
|
237
|
+
"$.profiles",
|
|
314
238
|
"id",
|
|
315
239
|
"DUPLICATE_PROFILE_ID",
|
|
316
240
|
errors,
|
|
317
241
|
)
|
|
318
|
-
|
|
242
|
+
for index, profile in _iter_list(profiles_value):
|
|
243
|
+
if isinstance(profile, Mapping):
|
|
244
|
+
_check_path_list(
|
|
245
|
+
profile.get("native_config_files"),
|
|
246
|
+
f"$.profiles[{index}].native_config_files",
|
|
247
|
+
errors,
|
|
248
|
+
)
|
|
249
|
+
default_profile = data.get("default_profile")
|
|
250
|
+
if isinstance(default_profile, str) and default_profile not in profiles:
|
|
251
|
+
errors.add("DANGLING_DEFAULT_PROFILE", "$.default_profile")
|
|
252
|
+
|
|
253
|
+
_unique_identities(
|
|
319
254
|
data.get("secret_references"),
|
|
320
255
|
"$.secret_references",
|
|
321
256
|
"name",
|
|
@@ -323,25 +258,10 @@ def _validate_declaration(data: Any, errors: ErrorCollector) -> None:
|
|
|
323
258
|
errors,
|
|
324
259
|
)
|
|
325
260
|
|
|
326
|
-
for index, command in _iter_list(data.get("commands")):
|
|
327
|
-
if (
|
|
328
|
-
isinstance(command, Mapping)
|
|
329
|
-
and not _is_project_relative_path(command.get("working_directory"), allow_root=True)
|
|
330
|
-
):
|
|
331
|
-
errors.add("UNSAFE_MANAGED_PATH", f"$.commands[{index}].working_directory")
|
|
332
|
-
|
|
333
|
-
for index, hint in _iter_list(data.get("capability_hints")):
|
|
334
|
-
if isinstance(hint, Mapping):
|
|
335
|
-
_check_path_list(
|
|
336
|
-
hint.get("evidence_files"),
|
|
337
|
-
f"$.capability_hints[{index}].evidence_files",
|
|
338
|
-
errors,
|
|
339
|
-
)
|
|
340
|
-
|
|
341
261
|
|
|
342
262
|
def validate(kind: str, data: Any) -> list[dict[str, str]]:
|
|
343
263
|
errors = ErrorCollector()
|
|
344
|
-
_check_forbidden_fields(data,
|
|
264
|
+
_check_forbidden_fields(data, errors)
|
|
345
265
|
if kind == "record":
|
|
346
266
|
_validate_record(data, errors)
|
|
347
267
|
else:
|
|
@@ -351,7 +271,7 @@ def validate(kind: str, data: Any) -> list[dict[str, str]]:
|
|
|
351
271
|
|
|
352
272
|
def _parser() -> argparse.ArgumentParser:
|
|
353
273
|
parser = argparse.ArgumentParser(
|
|
354
|
-
description="Validate semantic invariants for one PrizmKit Deploy artifact."
|
|
274
|
+
description="Validate semantic invariants for one PrizmKit Deploy v2 artifact."
|
|
355
275
|
)
|
|
356
276
|
parser.add_argument("--kind", choices=("record", "declaration"), required=True)
|
|
357
277
|
parser.add_argument("path", type=Path)
|
|
@@ -362,8 +282,13 @@ def main(argv: Sequence[str] | None = None) -> int:
|
|
|
362
282
|
args = _parser().parse_args(argv)
|
|
363
283
|
data, load_errors = _load_json(args.path)
|
|
364
284
|
errors = load_errors or validate(args.kind, data)
|
|
365
|
-
|
|
366
|
-
|
|
285
|
+
print(
|
|
286
|
+
json.dumps(
|
|
287
|
+
{"valid": not errors, "errors": errors},
|
|
288
|
+
ensure_ascii=False,
|
|
289
|
+
separators=(",", ":"),
|
|
290
|
+
)
|
|
291
|
+
)
|
|
367
292
|
return 0 if not errors else 1
|
|
368
293
|
|
|
369
294
|
|