ahmido
a09cc6ca8d
## Summary - Add Spec 435 backend-only Exchange structured output envelope and target normalizer readiness helpers for transportRule, remoteDomain, and inboundConnector. - Add deterministic hash input/readiness handling and no-promotion guard coverage. - Add Spec 435 spec, plan, tasks, checklist, and implementation report artifacts. ## Validation - git diff --cached --check - cd apps/platform && php artisan test --filter=Spec435 --compact ## Product Surface / Deployment - Livewire v4 compliance unchanged. - Filament provider registration unchanged under apps/platform/bootstrap/providers.php. - Global search unchanged; no resources added or modified. - Destructive/high-impact actions: none. - Asset strategy: none; no filament:assets requirement for this slice. - Browser proof: N/A - no rendered UI surface changed. - Deployment impact: no env vars, migrations, queues, scheduler, storage, assets, or Dokploy runtime behavior changes. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #502
152 lines
6.1 KiB
Markdown
152 lines
6.1 KiB
Markdown
# Requirements Checklist: Exchange Structured Output and Target Normalizer Readiness
|
|
|
|
**Purpose**: Preparation and implementation-readiness checklist for Spec 435.
|
|
**Created**: 2026-07-08
|
|
**Feature**: `specs/435-exchange-structured-output-target-normalizer-readiness/spec.md`
|
|
|
|
## Prerequisites
|
|
|
|
- [x] Spec 434 merge-ready proof is required before implementation.
|
|
- [x] Spec 434 adapter boundary, identity hard-stop, content-only writer guard, empty collection no-fake-evidence policy, generic Graph preservation, no UI, no migration, and no `tenant_id` are recorded as prerequisite proof.
|
|
- [x] Spec 433 credential/permission readiness, client-secret blocking, scoped/current `Exchange.ManageAsApp`, combined readiness, provider capability support, and runner-gate consumption are recorded as prerequisite proof.
|
|
- [x] Spec 432 runner boundary, process executor abstraction, output guard, timeout/concurrency guards, sanitized OperationRun context, no raw stdout/stderr outside approved paths, no UI, no migration, and no `tenant_id` are recorded as prerequisite proof.
|
|
- [x] Spec 430 command contracts exist for `Get-TransportRule`, `Get-RemoteDomain`, and `Get-InboundConnector`.
|
|
|
|
## Scope
|
|
|
|
- [x] Structured output only.
|
|
- [x] Normalizer readiness only.
|
|
- [x] Targets limited to `transportRule`, `remoteDomain`, and `inboundConnector`.
|
|
- [x] No evidence rows.
|
|
- [x] No content-backed promotion.
|
|
- [x] No compare/render.
|
|
- [x] No certification.
|
|
- [x] No restore.
|
|
- [x] No customer claim.
|
|
- [x] No UI.
|
|
- [x] No jobs/schedules/listeners.
|
|
- [x] No migration.
|
|
- [x] No `tenant_id`.
|
|
|
|
## Structured Output
|
|
|
|
- [x] Structured envelope requirement exists.
|
|
- [x] Raw stdout/stderr exclusion requirement exists.
|
|
- [x] Shape states are defined or mapped to repo-canonical equivalents.
|
|
- [x] Malformed output must block.
|
|
- [x] Scalar output must block.
|
|
- [x] Warning-prefixed output must block or classify safely.
|
|
- [x] Binary/non-UTF8 output must block.
|
|
- [x] Oversized output must block.
|
|
- [x] Non-zero exit must block.
|
|
- [x] Timeout must block.
|
|
- [x] Empty collection is distinguishable from failure states.
|
|
|
|
## Target Normalizers
|
|
|
|
- [x] `transportRule` readiness is required.
|
|
- [x] `remoteDomain` readiness must complete or explicitly block.
|
|
- [x] `inboundConnector` readiness must complete or explicitly block.
|
|
- [x] Volatile fields must be handled.
|
|
- [x] Sensitive fields must be handled.
|
|
- [x] Ordering must be deterministic.
|
|
- [x] Hash input rules must be defined.
|
|
- [x] Normalized payload previews are test-only/in-memory and not persisted.
|
|
|
|
## Identity
|
|
|
|
- [x] Stable identity rules are required.
|
|
- [x] Display-name-only identity must block.
|
|
- [x] Derived/domain-only identity must block unless proven safe.
|
|
- [x] Duplicate identity must block.
|
|
- [x] Missing identity must block.
|
|
- [x] Unsupported identity must block.
|
|
- [x] Identity-unproven state must block.
|
|
- [x] Explicit blocker states are required.
|
|
|
|
## Redaction
|
|
|
|
- [x] `transportRule` sensitive fields must be classified.
|
|
- [x] `remoteDomain` sensitive fields must be classified.
|
|
- [x] `inboundConnector` IPs, hosts, certificate names, comments, and routing metadata must be protected or potentially sensitive.
|
|
- [x] Protected config must not enter OperationRun context/logs/summaries.
|
|
- [x] Credential material must be absent.
|
|
- [x] Customer output must remain absent.
|
|
|
|
## Hash
|
|
|
|
- [x] Hash input determinism is required.
|
|
- [x] Material changes must be detected.
|
|
- [x] Volatile changes must be ignored.
|
|
- [x] Provider ordering must be handled deterministically where order is not meaningful.
|
|
- [x] Target type and normalizer version handling are required.
|
|
- [x] Hash input must exclude raw output, OperationRun context, runtime timestamps, PowerShell session metadata, credential metadata, and permission metadata.
|
|
|
|
## Empty Collection
|
|
|
|
- [x] Empty collection must be distinguished from failures.
|
|
- [x] Empty collection must create no resource row.
|
|
- [x] Empty collection must create no evidence row.
|
|
- [x] Durable collection proof is deferred.
|
|
|
|
## No Promotion
|
|
|
|
- [x] No `tenant_configuration_resource_evidence` rows.
|
|
- [x] No raw Exchange payload persisted as evidence.
|
|
- [x] No normalized Exchange payload persisted as evidence.
|
|
- [x] No content-backed state.
|
|
- [x] No comparable state.
|
|
- [x] No renderable state.
|
|
- [x] No certified state.
|
|
- [x] No restore-ready state.
|
|
- [x] No customer-ready state.
|
|
|
|
## Product Surface / Trigger
|
|
|
|
- [x] No routes.
|
|
- [x] No Filament pages/resources/widgets.
|
|
- [x] No Livewire components.
|
|
- [x] No Blade views.
|
|
- [x] No navigation.
|
|
- [x] No asset changes.
|
|
- [x] No global search changes.
|
|
- [x] No job trigger.
|
|
- [x] No schedule trigger.
|
|
- [x] No listener trigger.
|
|
- [x] Browser N/A.
|
|
|
|
## Architecture
|
|
|
|
- [x] Uses existing Exchange adapter/readiness architecture.
|
|
- [x] No migration.
|
|
- [x] No `tenant_id` ownership truth.
|
|
- [x] No Exchange-specific evidence table.
|
|
- [x] No Exchange mini-platform.
|
|
- [x] No legacy shim.
|
|
- [x] No fallback reader.
|
|
- [x] No dual write.
|
|
|
|
## Validation
|
|
|
|
- [x] Focused Spec 435 unit tests pass.
|
|
- [x] Focused Spec 435 feature tests pass.
|
|
- [x] Spec 434 regression passes.
|
|
- [x] Spec 433 regression passes.
|
|
- [x] Spec 432/431/430 regression passes.
|
|
- [x] Spec 415/417/419/420/426/427 regression passes.
|
|
- [x] Provider capability registry/evaluation regression passes.
|
|
- [x] Pint passes.
|
|
- [x] `git diff --check` passes.
|
|
- [x] `git status --short` is documented.
|
|
|
|
## Final Candidate Gate
|
|
|
|
- [x] PASS for preparation.
|
|
- [x] PASS for implementation.
|
|
- [ ] PASS WITH CONDITIONS for implementation.
|
|
- [ ] FAIL.
|
|
|
|
Preparation PASS rationale: `spec.md`, `plan.md`, and `tasks.md` define a bounded, testable, no-application-implementation package. Implementation PASS requires all applicable unchecked runtime validation items above to be checked with evidence.
|
|
|
|
FAIL if evidence rows are created, content-backed promotion occurs, raw stdout/stderr is treated as evidence, remoteDomain identity is faked, inboundConnector protected config leaks, unsafe output passes readiness, unsafe identity passes readiness, UI/routes/jobs/schedules/listeners are added, migration is added without amendment, `tenant_id` ownership truth is introduced, an Exchange-specific evidence table appears, or tests do not prove normalizer readiness safety.
|