dev-procfile/report/00-progress.md

# Darano discovery progress

Updated: 2026-08-28 (Asia/Tehran)

## Step 1 — workspace inventory

- The workspace is an aggregate of independent repositories: `api`, `auth`, `wallet`, `GL`, `ui`, `AdminPanel`, `proto`, `DevOps`, `docs`, `alert`, and Kuknos node scripts.
- `api` is the public REST gateway; Go backends communicate over gRPC. The customer UI is Next.js. The admin surface is Django and currently has direct database access.
- Prior-machine planning and refactoring records are present in `dev-procfile/`. They include completed work on a transactional outbox and event-driven wallet transaction processing, plus unfinished GL and admin-integration work.
- Repository-specific instructions were read before analysis. Existing user changes will be preserved.

## Next checks

- Reconcile TODO claims with current code and Git history.
- Trace business domains and every user transaction entry point through settlement.
- Audit GL capabilities and the Kuknos/GL source-of-truth switch.
- Run and assess relevant test suites.
- Compare the staging product with the implemented UI/API where access permits.
- Produce the final concise report and mind map in this directory.

## Current limitation

- The interactive browser surface is unavailable in this session. Staging-site inspection will use read-only web access; any authenticated-only behavior may require user-provided access or screenshots.

## Step 2 — recovered-work reconciliation

- The tracker is internally consistent with Git history for `wallet`, `auth`, and `proto`: their refactor branches contain the cited commits.
- The local `GL` checkout is misleadingly on `main` (initial README/license only). The complete GL implementation and explorer are present, identically, on `origin/dev` and `origin/feat/refactor-v1` at `32e7b6b`.
- The root `Procfile` does not start GL or its explorer, and the checked-in stage compose/config does not deploy or configure GL. Therefore “start the main app and write alongside Stellar” is not true for the current aggregate startup/deployment despite the service and wallet adapters existing on feature branches.
- The accepted GL design deliberately excludes automatic failover. It defines `MIRROR`, future admin-authorized `DEGRADED_LEDGER`, and `RECONCILE`, but only mirror recording is implemented so far.
- The event pipeline is real code, not merely a plan: transaction persistence atomically creates a per-type outbox event; Watermill/RabbitMQ dispatches it; an idempotent inbox handler runs the legacy processor; retries and deadbox handling exist. It starts only in wallet service mode.

## Early risks to verify

- GL journals currently originate from Wallet `float64` amounts formatted to seven decimal places; GL itself correctly expects fixed-point decimal strings. This boundary can preserve pre-existing rounding error and is weaker than the stated `numeric(38,18)` invariant.
- Transaction lifecycle event version is hard-coded to `1`, while the idempotency key hashes the payload. Multiple state changes for one transaction may conflict with GL's unique source-transaction/event-version constraint; this needs a test/code-path check.
- The transaction-event consumer reports success alerts even when it receives a duplicate event for a transaction already marked successful. Inbox idempotency prevents repeat handling after a succeeded inbox claim, but crash windows around notification vs. inbox completion need review.

## Step 3 — staging-flow reconciliation

- User screenshots confirm available/locked/total balances, asset actions, transaction history, market maker/taker purchase, ICO purchase from a selected maker, legal agreement acceptance, verified Sheba accounts, IRT withdrawal, and referrals.
- Product clarification adds five required workflows: Kuknos subscription, bank-deposit ingestion, IPG confirmation, admin-approved IRT withdrawal, and third-party collateral locks.
- Every transaction may require SMS, TOTP, or email 2FA plus a versioned agreement/contract/policy acceptance. These are prerequisites and immutable audit evidence, not incidental UI steps.
- GL was switched from `main` to the canonical `feat/refactor-v1` branch. Its tracked license was restored after a checkout filesystem anomaly; the pre-existing `.DS_Store` was preserved.

## Step 4 — availability policy

- GL is confirmed as a mandatory transaction dependency. There is no GL operational failover mode: GL failure must halt every value-changing workflow until recovery.
- `/health` must become critical/not-ready and the incident/recovery transitions must be reported through OpenTelemetry logs (with metrics/traces recommended for correlation).
- Current behavior violates this policy: Wallet health is unconditional success, GL remains `Serving=true` when its database ping fails, API health does not aggregate GL, and the asynchronous ledger dispatcher only logs/retries while transactions continue.
- Automatic acceptance policy for third-party collateral transactions is out of scope and retained as a future feature.

## Step 5 — authority and Kuknos mode

- GL is the primary append-only financial source of truth. Kuknos is the secondary settlement and verification source.
- Normal operation requires both. GL outage always halts transactions. Kuknos outage also halts transactions until an authorized operator explicitly enables GL-only `KUKNOS_DISABLED` mode through AdminPanel or configuration.
- The mode may not switch automatically. Its actor, reason, time, previous/new state, and recovery/reconciliation must be auditable and sent through OpenTelemetry.
- Append-only enforcement is present in GL database triggers and reversal validation.

## Step 6 — implementation

- Implemented the GL/Kuknos fail-closed gate at mutation RPC, transaction worker, health, and Kuknos subscription boundaries.
- Added the explicit configuration switch `network.kuknos-enabled`; no automatic switch or automatic acceptance policy was added.
- Corrected GL database readiness, API HTTP 503 health propagation, and structured OTel-compatible incident/recovery logs.
- Wallet and GL full test suites pass. Details and remaining atomicity/deployment limits are in `05-availability-implementation.md`.