feat: close autonomous operations for blocked products

2026-09-22 14:51:54 -03:00
parent dca4847c21
commit 3a36ac630b
16 changed files with 666 additions and 3 deletions
@@ -1,5 +1,14 @@
 # AI Project State

+## Autonomous operations closure V1 (2026-09-22)
+
+`AUTONOMOUS_OPERATIONS_CLOSURE_VALIDATED` — the Agent now models per-product
+operational states, keeps safe blocked products in a deduplicated Hub registry,
+retries only when input evidence/context changes, and auto-resolves blockers
+after a later successful evaluation. Partial processing keeps heartbeat and new
+jobs healthy. `AUTONOMOUSLY_PROCESSABLE_PRODUCTS=35066` despite
+`SAFE_BLOCKED_PRODUCTS=194`; no AI or Firebird write is required for operation.
+
 ## Autonomous fiscal completion V1 (2026-09-22)

 `AUTONOMOUS_FISCAL_COMPLETION_V1_MEASURED` — requiredness matrix and pure
@@ -0,0 +1,121 @@
+# Autonomous Operations Closure V1
+
+## Final Status
+
+```text
+STATUS=OPERATIONALLY_CLOSURE_VALIDATED
+TOTAL_PRODUCTS=35066
+FISCALLY_COMPLETE=34872
+FISCALLY_INCOMPLETE=194
+AUTONOMOUSLY_CORRECTABLE_PRODUCTS=34872
+SAFE_BLOCKED_PRODUCTS=194
+AUTONOMOUSLY_PROCESSABLE_PRODUCTS=35066
+AUTONOMOUS_OPERATION_RATE=100%
+INSTALLATION_REQUIRES_OPERATOR_TO_CONTINUE=false
+AGENT_HEALTH=HEALTHY
+```
+
+The 194 incomplete products are isolated safe exceptions. They do not stop
+processing of the other 34,872 products, heartbeat, new jobs, reconnection, or
+future deterministic corrections.
+
+## Product States
+
+The operational contract has exactly seven states:
+
+`COMPLETE`, `CORRECTED`, `BLOCKED_MISSING_EVIDENCE`, `BLOCKED_CONFLICT`,
+`BLOCKED_COMPANY_CONTEXT`, `BLOCKED_SCHEMA`, and `FAILED_TECHNICAL`.
+
+Blocked products never receive uncertain writes. Technical failures are kept
+separate and retryable. A blocked product becoming complete on a later
+evaluation closes its registry blockers automatically.
+
+## Blocked Registry
+
+The Hub now has a deduplicated `blocked_products` registry with tenant,
+company, product, GTIN, description, blocker type, field, reason, evidence,
+input fingerprint, timestamps, retry count, retry schedule, resolution time,
+and resolution source.
+
+Available API operations:
+
+- `GET /v1/blockers`
+- `GET /v1/blockers/export.csv`
+- `POST /v1/blockers/reprocess`
+- `POST /v1/blockers/{id}/resolve`
+
+The same blocker/input fingerprint is a cache hit and does not create another
+row or notification. Reprocessing is eligible when the product/context,
+dataset, KB, engine input, or retry schedule changes.
+
+## Current Residual
+
+```text
+CFOP_BLOCKERS_BEFORE=79
+CFOP_BLOCKERS_AFTER=79
+ST_BLOCKERS_BEFORE=57
+ST_BLOCKERS_AFTER=57
+ICMS_RATE_BLOCKERS_BEFORE=53
+ICMS_RATE_BLOCKERS_AFTER=53
+CSOSN_BLOCKERS_BEFORE=27
+CSOSN_BLOCKERS_AFTER=27
+HUMAN_COMPANY_BLOCKERS=4
+HUMAN_PRODUCT_BLOCKERS=190
+```
+
+No requiredness rule was weakened to increase the operation rate. The remaining
+fields require facts not proven by the current ERP evidence. The four company
+blockers remain context ambiguity; they were not converted into defaults.
+
+## Simulations
+
+The offline 20,000-product simulation passed:
+
+- 19,900 complete products processed.
+- 100 safe blocked products preserved.
+- `AGENT_HEALTH=HEALTHY`.
+- Heartbeat and new jobs continue.
+- Second pass is idempotent.
+
+The new-evidence simulation passed:
+
+`BLOCKED_MISSING_EVIDENCE -> COMPLETE -> blocker resolved`.
+
+## Go-Live Policy
+
+```text
+BLOCKED_REGISTRY_READY=true
+BLOCKER_DEDUP_READY=true
+AUTO_RETRY_READY=true
+AUTO_RESOLUTION_READY=true
+EXCEPTION_QUEUE_READY=true
+AI_REQUIRED_FOR_MANDATORY_COMPLETENESS=0
+EXTERNAL_PROVIDER_REQUIRED_FOR_MANDATORY_COMPLETENESS=0
+AI_WRITE_ALLOWED=false
+FIREBIRD_AI_WRITES=0
+CAN_RUN_UNATTENDED_ON_CLIENTS=true
+CAN_DEPLOY_WITHOUT_AI=true
+```
+
+This is an operational go/no-go assessment only. No deployment was performed.
+
+## Remaining Gaps
+
+- 194 products remain safely blocked by missing evidence or company context.
+- No deterministic write was required or executed in this closure.
+- AI remains optional enrichment for 511 items.
+- Real client deployment, infrastructure preflight, and production credentials
+  remain outside this mission.
+
+## Verdict
+
+`VERDICT=AGENT_CAN_CONTINUE_UNATTENDED_WITH_SAFE_PER_PRODUCT_EXCEPTIONS`
+
+## Verification
+
+```text
+FULL_TESTS=tests 324 passed, 1 skipped
+CENTRAL_TESTS=230 passed, 1 warning
+AGENT_TESTS=44 passed
+DIFF_CHECK=PASS
+```
@@ -0,0 +1,37 @@
+{
+  "artifact": "AUTONOMOUS_OPERATION_HEALTH_V1",
+  "status": "PASS_WITH_SAFE_BLOCKED_PRODUCTS",
+  "TOTAL_PRODUCTS": 35066,
+  "COMPLETE": 34872,
+  "CORRECTED": 0,
+  "SAFE_BLOCKED": 194,
+  "FAILED": 0,
+  "coverage_percent": 99.44675754,
+  "AUTONOMOUSLY_CORRECTABLE_PRODUCTS": 34872,
+  "SAFE_BLOCKED_PRODUCTS": 194,
+  "AUTONOMOUSLY_PROCESSABLE_PRODUCTS": 35066,
+  "AUTONOMOUS_OPERATION_RATE": 1.0,
+  "INSTALLATION_REQUIRES_OPERATOR_TO_CONTINUE": false,
+  "AGENT_HEALTH": "HEALTHY",
+  "CFOP_BLOCKERS_BEFORE": 79,
+  "CFOP_BLOCKERS_AFTER": 79,
+  "ST_BLOCKERS_BEFORE": 57,
+  "ST_BLOCKERS_AFTER": 57,
+  "ICMS_RATE_BLOCKERS_BEFORE": 53,
+  "ICMS_RATE_BLOCKERS_AFTER": 53,
+  "CSOSN_BLOCKERS_BEFORE": 27,
+  "CSOSN_BLOCKERS_AFTER": 27,
+  "BLOCKED_REGISTRY_READY": true,
+  "BLOCKER_DEDUP_READY": true,
+  "AUTO_RETRY_READY": true,
+  "AUTO_RESOLUTION_READY": true,
+  "EXCEPTION_QUEUE_READY": true,
+  "AI_REQUIRED_FOR_MANDATORY_COMPLETENESS": 0,
+  "EXTERNAL_PROVIDER_REQUIRED_FOR_MANDATORY_COMPLETENESS": 0,
+  "AI_WRITE_ALLOWED": false,
+  "FIREBIRD_AI_WRITES": 0,
+  "LARGE_DATABASE_SIMULATION": "PASS",
+  "BLOCKED_TO_RESOLVED_SIMULATION": "PASS",
+  "new_writes": 0,
+  "second_pass_writes": 0
+}
@@ -0,0 +1,62 @@
+# Autonomous Operation Policy V1
+
+## Operational Contract
+
+Each product ends in exactly one state:
+
+- `COMPLETE`
+- `CORRECTED`
+- `BLOCKED_MISSING_EVIDENCE`
+- `BLOCKED_CONFLICT`
+- `BLOCKED_COMPANY_CONTEXT`
+- `BLOCKED_SCHEMA`
+- `FAILED_TECHNICAL`
+
+`COMPLETE` and `CORRECTED` products continue normally. Blocked products never
+receive uncertain writes. `FAILED_TECHNICAL` is retried by the job system and
+does not stop processing of other products.
+
+## Partial Processing
+
+The Agent processes every product independently and reports per-product state
+counts. Safe blocked products do not stop processing, heartbeat, new jobs, or
+reconnection. `AGENT_HEALTH=HEALTHY` is valid when `SAFE_BLOCKED > 0` and
+`FAILED_TECHNICAL=0`.
+
+## Go-Live Gate
+
+`GO_LIVE_ALLOWED=true` only when all are true:
+
+- preflight passes;
+- company context is resolved;
+- mandatory infrastructure is healthy;
+- no unsafe write path is available;
+- blockers are explicitly registered as safe blocked states;
+- technical failures are below the configured threshold.
+
+One hundred percent product completeness is not required to start an Agent.
+This policy authorizes no deployment by itself.
+
+## Blocker Registry And Retry
+
+The Hub stores one blocker per stable fingerprint with tenant/company/product,
+field, evidence, timestamps, retry count, next retry, and resolution source.
+Identical input fingerprints are `BLOCK_CACHE_HIT` and do not create duplicate
+rows, notifications, AI work items, or external calls. Reprocessing occurs when
+product/context/dataset/KB/engine input changes or a retry schedule is due.
+
+The exception API supports listing/filtering, CSV export, reprocess job creation,
+and explicit resolution. A successful later evaluation automatically closes all
+unresolved blockers for that product.
+
+## Current Policy Facts
+
+```text
+AI_REQUIRED_FOR_MANDATORY_COMPLETENESS=0
+EXTERNAL_PRODUCT_PROVIDER_REQUIRED_FOR_MANDATORY_COMPLETENESS=0
+AI_WRITE_ALLOWED=false
+FIREBIRD_AI_WRITES=0
+```
+
+The 511 AI work items are optional enrichment. No provider purchase, AI call,
+or fiscal inference is needed for operational start under this policy.
@@ -0,0 +1,21 @@
+{
+  "artifact": "AUTONOMOUS_OPERATION_SIMULATION_V1",
+  "mode": "OFFLINE_NO_FIREBIRD_NO_AI",
+  "large_database": {
+    "products": 20000,
+    "complete": 19900,
+    "safe_blocked": 100,
+    "failed_technical": 0,
+    "agent_health": "HEALTHY",
+    "autonomously_processable": 20000,
+    "idempotent_second_pass": true,
+    "heartbeat_and_new_jobs_continue": true
+  },
+  "blocked_to_resolved": {
+    "before": "BLOCKED_MISSING_EVIDENCE",
+    "after": "COMPLETE",
+    "blocker_resolved": true
+  },
+  "ai_calls": 0,
+  "unsafe_writes": 0
+}