Enterprise Admin Suite Completion Implementation Plan

For agentic workers: Implement this plan in disjoint domain assignments. The user explicitly requires all implementation code first, then all new tests, then one progressive verification pass. This overrides the usual per-task test-first workflow. Do not run repeated broad suites while building.

Goal: Complete every unconditional capability and acceptance requirement in the original enterprise blueprint, with honest readiness for capabilities requiring provider configuration or real operational evidence.

Architecture: Extend the existing governed command/RPC/receipt architecture in place. Every new privileged operation uses fresh staff authority, exact revisions, idempotent command identity, transactional audit, and independent review where the existing risk policy requires it. Reuse canonical commerce/finance workers; do not add parallel money or identity authorities.

Tech stack: React/Vite, Express/TypeScript, Supabase/Postgres, existing queues, @debelu/core and @debelu/ui; Node22/npm10 minimum.

Spec: ../specs/2026-10-03-enterprise-command-center-design.md and ./2026-10-03-enterprise-command-center-roadmap.md.

Global constraints

• One Debelu marketplace with centrally configured dynamic campuses. Separate independent tenants, microservices, native admin apps, speculative currencies and autonomous operators remain conditional as explicitly stated in the original blueprint.
• Preserve existing journal, payment intent, payout reference, refund, privacy, approval and audit history; never edit installed migrations.
• Monetary thresholds, budgets, retention, provider choices and recovery objectives are operator-configured, versioned and reviewed. Unknown policy blocks dependent execution; do not invent business approval.
• Public clients never receive service credentials. No provider messages, charges, transfers, destructive customer actions or production restore experiments as build probes.
• Allocate migration files with the Supabase CLI; apply through MCP only after final release gates. Root coordinates migration order and shared router/navigation edits.
• Preserve unrelated working-tree deletions and untracked configuration documents. No mass formatting or dependency churn.

Delivery sequence

1. Deploy the existing passing release immediately. Record custom-domain assets, application revision and backend readiness; do not rerun already-passing CI for the same tree.
2. Build every work package below. Agents do not write or run new tests in this stage. Use source inspection and lightweight syntax/type diagnostics only when needed to unblock implementation; do not launch broad suites.
3. Once every implementation package is integrated, write focused acceptance/regression tests against the complete contracts, not trivial implementation mirrors. Group shared fixtures and authority/race checks instead of duplicating them per component.
4. Run one progressive pass: static/type/lint → unit/contract → representative SQL → native migration/concurrency → builds → authenticated safe-environment browser journeys/accessibility. Stop dependent stages if prerequisites fail; collect independent failures in the same pass.
5. Correct all collected failures as one batch, then repeat the progressive pass on the corrected exact commit. No interim full-suite loops.
6. Apply final migrations through MCP, merge passing release, deploy applications and verify matching live revisions. Complete the original acceptance matrix. Report operator-dependent evidence explicitly; do not relabel an unverified outcome as 100% ready.

Review focus

• Existing sessions and queued work after staff revocation: fresh authorization must deny sensitive effects.
• Partial bulk/import/provider failures: preserve exact intent and receipt; unknown external outcomes never create replacement sends/transfers.
• Cross-campus guessed identifiers, exports and background jobs: scope applies at the authoritative boundary.
• Old inventory/orders and policy revisions: preserve historical evidence, prospective validation and compensating corrections.
• Missing credentials, retention policies or backup evidence: render actionable unknown/configuration states, never fabricated success.

Build work packages

1. Staff sessions and access readiness

Files: new StaffSessionService/routes/client and StaffSessionsPanel, additive migration; existing middleware/auth.ts for request session enforcement; access-governance integration coordinated by root.

Contract: authenticated server extracts the verified session identity; staff can inspect their own sessions, and eligible global security staff can revoke a target staff session with AAL2, reason, exact revision and immutable receipt. No raw tokens, refresh secrets or unrestricted auth.sessions browser access. Revocation is enforced against existing tokens at subsequent requests and sensitive execution. Display MFA, access provenance and invitation delivery readiness without claiming mailbox delivery.

• [ ] Implement session inventory/revocation and lifecycle controls.
• [ ] Add an additive action-capability policy overlay for separately grantable canonical RPC/HTTP actions, explicit denies and independently reviewed role/actor policy versions. Existing domain authority remains mandatory; an overlay grant never broadens underlying permissions.
• [ ] Add tests during the later test stage: target ownership, stale revision, self/other sessions, revoked existing token, expiry and private metadata.

2. Campus operational policy

Files: CampusPolicyService/routes/client, CampusPolicyPanel, additive migration; existing campus-registry/campus-operations contracts and checkout/onboarding/category discovery effects.

Contract: versioned policy per registry campus covers local holidays, enabled categories, onboarding state, responsible staff, effective dates and geographic overlap observations. Global canManageCampuses/AAL2 reviews changes; campus operators only see allowed campuses. Holidays/category policies must affect actual supported commerce paths, not just an editor.

• [ ] Implement policies, impact preview and actual consumers.
• [ ] Later tests: removed campus, overlapping geometry, policy effective date, holiday boundaries, existing orders and category restrictions.

3. Governed imports

Files: DataImportService/routes/client, DataImportPanel, additive migration, typed adapters for declared supported entities.

Contract: create immutable validated import proposal with schema/mapping, source digest, row count, dry-run impact and per-row errors. Independent approval binds exact validated rows/current resource revisions; execution uses domain commands, per-row receipts and resumable eligible failures. Initial adapters cover catalog attributes and campus operational policies; extend registry only through canonical commands. Reject monetary/profile/security columns. Separate scope/export grants, bounded payloads, cancellation and private source expiry.

• [ ] Implement import lifecycle and adapter integration.
• [ ] Later tests: forbidden fields, stale row, partial success, replay, cancellation, unauthorized campus, digest mismatch.

4. Shared queues, record investigation and bulk work

Files: command workspace service/panel; shared bulk job module and components; order/product/ticket supported adapters; AdminLayout/navigation wiring.

Contract: stable URL filters, personal/team views, scoped sorting/columns and return navigation; record timeline/linked evidence with canonical identifiers. Bulk proposals freeze selected IDs and revisions; preview exact count/impact, review where required, execution progress, per-item failures and retry only eligible items. Add assignment handover, conflict and SLA observations across supported domains rather than fictitious universal operations.

• [ ] Implement queue/detail/bulk integration.
• [ ] Later tests: preserved filters, frozen selection, concurrent claims, partial jobs, keyboard navigation and denied totals.

5. Line-level returns and refund completion

Files: return/refund services and schemas, RMA/finance panels, canonical payment/refund workers, additive migration.

Contract: bind eligibility/inspection/return quantities to purchased order lines and captured funding. Independent refund proposals enforce cumulative amount ceiling and journal conservation. Wallet refunds use canonical receipts; provider refunds use one stable intent, verified provider API/callback outcomes and reconciliation. Settled-order recovery requires declared approved funding/policy and compensating journal entries; absent authority/policy stays blocked. A return cannot claim dispatch, delivery or refund without corresponding evidence.

• [ ] Implement line-level return/refund states and exact effect paths.
• [ ] Later tests: concurrent partial refunds, previous refunds, settlement race, provider timeout, duplicate event, insufficient recovery funding.

6. Financial policy and close

Files: versioned FinancePolicyService and simulation, existing financial-period/reconciliation/wallet/payout execution boundaries.

Contract: reviewed configurable amount/velocity/hold/bank-change rules and historical policy binding; deterministic simulation against frozen representative evidence. Statement matching distinguishes journal/payment/transfer/provider-fee evidence. Add chargeback investigation with independent disposition, canonical funding/receipt, and subsequent compensating corrections. Period evidence sealing remains distinct from a true journal period lock; implement safe correction semantics without silently blocking provider callbacks.

• [ ] Implement policy consumers, financial exceptions and correction workflow.
• [ ] Later tests: execution after policy change, velocity race, bank change, fee mismatch, closed period correction and canonical callback continuity.

7. Inventory and search quality

Files: InventoryExceptionService, SearchQualityService, panels, supported reservation/index adapters.

Contract: inspect actual availability/reservation conflicts, create accountable seller corrections and reviewed adjustments that preserve active reservations. Index failure evidence includes real source/index version and eligible retry; absence of an indexing provider is explicit. Controlled ranking changes reuse reviewed merchandising; do not label a cache flush as verified reindexing.

• [ ] Implement exception queues and actual supported correction/reindex effects.
• [ ] Later tests: concurrent checkout/reservation, stale quantity, replay and missing/failed index provider.

8. Fraud and moderation evidence

Files: fraud case/rule services, moderation evidence integration, panels and additive migration.

Contract: explainable alerts with model/rule/version/provenance, observed evidence, review and false-positive disposition. Versioned rules can be simulated against declared data; no automatic money/access effects. Connect existing cases/KYC/sanctions/appeals with field masking and independent action policies.

• [ ] Implement rule simulation, alerts and reviewer outcomes.
• [ ] Later tests: signal versus fact, cross-campus evidence, false positives, changed provenance and independent appeal.

9. Communications and growth accounting

Files: existing campaign/promotion/notification schemas, worker gates and admin panels; new budget and conversion observation services.

Contract: reviewed cost budgets, reservations and eligibility/consent/suppression at dispatch, schedule/cancel rules, truthful delivery receipts. Promotions declare stacking/exclusions/refund/usage policy at canonical checkout/refund boundaries. Conversion reporting uses reproducible scoped exposure/event definitions and explicit attribution limitations. Credential readiness is metadata only; selected channels require controlled recipient evidence.

• [ ] Implement budget/suppression/promotion effects and reporting.
• [ ] Later tests: simultaneous budget reservations, cancellation during dispatch, refund precedence, consent withdrawal and missing provider receipts.

10. Incidents, jobs and safe replay

Files: IncidentService, job/callback dead-letter adapters, panels, existing dependency cockpit and maintenance workers.

Contract: accountable incident ownership/timeline/runbook execution; real queue lag/retry/dead-letter observations, immutable replay proposals bound to event identity and current state. Use canonical workers with existing dispatch fences; never blindly replay uncertain financial effects. Add configured synthetic journeys in a safe environment and outcome receipts.

• [ ] Implement incident handling and supported job replay consumers.
• [ ] Later tests: duplicate event, changed canonical state, frozen worker, owner handover and partial incident recovery.

11. Data retention and recovery operations

Files: existing privacy/inventory/execution/recovery services, protected download/outbox and retention policy adapters.

Contract: typed retention policy and hold checks per owned system, private delivery evidence and exact storage version processing; complete case scope only after reviewed results. Backup catalog/readiness includes identity, access/retention, measured isolated restoration, authorization/ledger/audit/storage/job comparisons and declared RPO/RTO. Real provider/storage evidence is collected, never inferred from local fixture success. No production restore without a separately authorized destination.

• [ ] Implement remaining policy adapters and operator evidence capture/verification paths.
• [ ] Later tests: hold race, expired evidence/download, partial storage failures, replay and measured recovery invariants.

12. Integration registry and bounded automation

Files: IntegrationRegistryService, scoped service actor contracts, AutomationService, panels, additive migrations.

Contract: registry owner/purpose/scopes, credential presence/rotation metadata, callback health, rate/cost policies. Rules have reviewed versions, simulation, capped actions and kill switch, dispatch through ordinary domain commands. Reporting/SIEM adapters provide scoped protected outputs when configured. SSO/provisioning and AI remain conditional in the original plan; expose honest configured readiness rather than inventing an identity provider or autonomous actions.

• [ ] Implement registry, bounded simulation/execution and supported output adapters.
• [ ] Later tests: unauthorized service scopes, kill switch, stale rule, unknown outcome and private evidence redaction.

13. Performance, accessibility and acceptance matrix

Files: docs/enterprise-suite-acceptance-matrix.md, representative load profiles, authenticated browser fixtures, docs/command-center-implementation-status.md.

Contract: map every original blueprint requirement to source/effect/acceptance/evidence. Measure agreed representative volumes and scope skew; configurable objectives remain uncommitted until measured/accepted. Run staff task journeys with permitted test accounts in a safe environment, keyboard/zoom/reduced-motion/focus and inaccessible-field behavior. Review complete branch once, correct all findings in a batch.

• [ ] Replace overstated completion claim with this authoritative matrix and actual progress.
• [ ] After all code is integrated, create the consolidated regression/native/browser test package and execute the progressive pass.
• [ ] Mark full implementation complete only when every unconditional requirement has an implemented effect and passing acceptance evidence; list real provider/operator enablement separately.

Parallel ownership and integration

First agents own packages1,2,3 respectively. Root owns server.ts, AdminLayout.tsx, admin-navigation.ts, shared exports and the acceptance matrix. Agents create domain router/panel files and report required wiring instead of editing shared integration files. Each agent records its contracts, migrations, remaining work and future test cases in a concise domain note. Root dispatches packages4–12 as slots open. No agent applies hosted migrations, pushes, merges, runs broad tests or commits others' files.

14. Canonical intelligence and governed alerts (full-plan audit correction)

Original blueprint7A requires more than legacy owner totals. Implement scoped metrics with explicit definition, canonical source, calculation window, observation time and drill-through; distinguish captured GMV, recorded released fees, fulfillment cohorts and current exposure. Missing conversion telemetry must be unavailable rather than inferred or zero.

Implement a deduplicated alert inbox with current evidence, acknowledgement, owner, escalation and exact-revision resolution evidence. Recovering a dependency must not silently close outstanding operator work. Keep scope checks at every read and effect; register new session/action RPC contracts. Migration71 and typed service/routes/panel are required before the test stage.

Later acceptance: canonical metric cohorts and unavailable sources; denied scope/totals; deduplicated recurrence; independent concurrent ownership/acknowledgement; stale changes; no closure without evidence; replay and audit atomicity.

15. Vendor re-verification and support attachment screening

Original blueprint7B requires a re-verification lifecycle beyond initial enrollment. Extend the canonical KYC domain with accountable reviewer, missing evidence, reasoned current-object review, independent completion and prospective marketplace/payout eligibility guards. Preserve historical commerce and provider callback ingestion. Migration72 must register session and restrictive action capabilities; an internal review never claims external provider verification.

Support attachments require actual bytes and immutable source-bound screening observations, not a path check alone. Module70 adds bounded byte/type screening and an optional authenticated scanner adapter. Configured scanner failures remain unknown and block dependent access; absent antivirus configuration remains explicitly unverified. Reply insertion and protected download must check the same current source evidence.

Later acceptance: changed document race, ownership/scope and self-review denial, revocation during queued effect, screened bytes versus declared type, expired/changed storage object and unavailable or malformed scanner responses.