PROPOSAL — a commercial-state architecture for NIKO

Short answer

PROPOSAL — NOT IMPLEMENTED. NIKO's current repository already contains commercial states, event types and stored records for opportunities, payments and commission statements. It also contains signed Action Briefs, a hash-chained audit trail, an event outbox and a durable customer-plane snapshot. Those pieces are real. They do not yet form the versioned commercial-state projection proposed here.

WHAT EXISTS TODAY: customer-plane.json stores campaigns, candidates, evidence, messages, threads, opportunities, payments, commissionStatements, suppressions, audit records and outbox events. Records and events already carry stable IDs; events already expose explicit operational, evaluation and learning views; the master state map records progress and the runtime records follow-up obligations. These are narrow implemented primitives, not the unified rebuildable CommercialState projection proposed here.

WHAT IS PROPOSED: one rebuildable CommercialState projection per commercial episode, derived from canonical events and joined by stable references. It would expose verified phase, evidence, unresolved contradictions, next permitted action, outcome status and projection version. It would not become a second source of truth, a new memory system or permission authority.

Status and scope

PROPOSAL — NOT IMPLEMENTED. This article is an architecture proposal produced after inspecting the current NIKO repository. Publishing it changes no runtime code, database, production worker, event schema, inference route, send policy or commercial decision. There is no migration and no runtime change in this handoff.

The proposal addresses one narrow problem: commercial facts are already represented across candidates, threads, opportunities, payments, commission statements, audit records and events, but a reader or runtime component has no single rebuildable projection that says what commercial phase is verified, which evidence supports it, what contradicts it, and which action is permitted next. The answer must be a projection over existing truth, not another mutable source of truth.

WHAT EXISTS TODAY — verified in the repository

The LocalCustomerStore initializes and persists customer-plane.json. Its current schema includes campaigns, candidates, evidence, messages, threads, opportunities, payments, commissionStatements, suppressions, an audit array, an event outbox, local events, release packets and watchdog alerts. Store methods append opportunity, payment and commission-statement records after tenant checks. The snapshot is rewritten atomically through a temporary file; this is a durable local JSON snapshot, not a transactional event database.

Material event types already cover opportunity_created, opportunity_progressed, opportunity_lost, customer_won, payment_pending, cash_verified, cash_collected, commission_calculated, commission_created and deal_won. Events carry an ID, schema version, occurrence time, tenant, payload and multiple views. The audit trail is hash-chained to the previous audit hash. The outbox and audit structures provide durable evidence and ordering primitives, while temporal projection failures are recorded rather than silently discarded.

The master state map already defines opportunity_tracking, revenue_reconciliation, commission_due, closed_measured, closed_lost and disputed states, with allowed actions and next states. Policy currently prohibits pricing commitments by default and requires signed Action Briefs for sends. Local Mother creates and verifies bounded signed Action Briefs with evidence references, permitted and prohibited actions, policy version, inference configuration and release pin.

WHAT DOES NOT EXIST TODAY

There is no unified CommercialState aggregate of the larger form proposed in this article. No current object joins a candidate, conversation thread, opportunity, payment and commission statement into one rebuildable, versioned commercial episode with a deterministic cross-entity reduction rule. The arrays and narrow fields show that records exist; their presence alone does not prove a coherent, current or terminal commercial state.

Narrow parts of the vocabulary are implemented already: records and events have stable identifiers, events separate claims into operational, demonstration, evaluation and learning views, the state map records progress, and follow-up obligations can be represented in canonical events and runtime state. Ongoing runtime work may make those fields and obligation recovery more explicit. That does not make the unified projection, its reducer, or its shadow-rebuild migration complete.

The current addOpportunity, addPayment and addCommissionStatement methods append tenant-bound records, but the audited store layer does not itself show one episode-wide optimistic version and deterministic reconciliation across every commercial record. Generic state transitions validate a from-state, to-state and action against the master map; they do not by themselves reconcile every commercial record into the larger projection proposed here.

There is also no general scarce-resource lease manager of the form proposed in article 38 or unified cross-entity completion projection of the form discussed in article 39. The worker exposes heartbeat and checkpoint metrics for its current discovery loop, but process-alive and activity counters are not a commercial-state proof.

WHAT IS PROPOSED — the CommercialState projection

Create one rebuildable projection per commercial episode. Its identity would be stable and tenant-bound: episodeId, tenantId, prospectKey, candidateId, threadId and opportunityId where available. Its provenance header would carry projectionVersion, reducerVersion, lastCanonicalEventId, lastOccurredAt and rebuiltAt. Deleting and rebuilding the projection from canonical events must produce the same result.

The body would separate facts from interpretation. VERIFIED FACTS would include identity resolution, evidence references, signed Action Brief IDs, transport acceptance, delivery observations, reply IDs, meeting evidence, opportunity records, payment-rail references and cash-verification evidence. DERIVED STATE would include phase, phaseConfidence, diagnosticCompletion, nextPermittedActions, missingEvidence, contradictions and staleDependencies. A model may propose an interpretation; only deterministic reducers and authoritative provider observations may advance verified fields.

Suggested phases are DISCOVERY, EVIDENCE_READY, BRIEF_READY, CONTACT_ATTEMPTED, DELIVERY_OBSERVED, CONVERSATION_ACTIVE, OPPORTUNITY_OPEN, COMMITMENT_OBSERVED, PAYMENT_PENDING, CASH_VERIFIED, CLOSED_LOST and SUPPRESSED. These are not a replacement for the existing master map. They are a public and operational reading of evidence across several existing entities. Phase advancement should be monotonic unless a superseding event explicitly records correction or reversal.

Command, fact and projection must remain different

A command is an authorized attempt: send this message, offer this meeting, request payment verification. A fact is what an authoritative boundary observed: provider accepted the send, a reply was received, a meeting record exists, the payment rail verified settled cash. The projection is a deterministic reading of those facts. Collapsing these creates familiar errors: a requested send becomes a sent email, a provider acceptance becomes delivery, a meeting offer becomes a booking, or payment_pending becomes cash_verified.

Each command should carry commandId, episodeId, expectedProjectionVersion, Action Brief or policy authority, dependency digest and idempotency key. Each effect result should carry the command ID, provider observation, occurred time and evidence reference. If the expected version or dependency digest has changed, the command becomes INVALID_PLAN and returns for re-projection. Retrying must not create a second external effect.

Invariants that should be mechanical

One: no verified identity means no commercial reasoning. Two: no evidence means no Action Brief. Three: no valid signed Action Brief means no external action. Four: provider acceptance is not delivery. Five: an inbound message is not a positive reply until normalized and classified, and classification is not customer intent without the underlying message evidence. Six: an opportunity is not a win. Seven: payment_pending is not cash. Eight: only an authoritative payment observation can set CASH_VERIFIED. Nine: suppression and opt-out close every send path. Ten: a correction supersedes history; it never deletes the original event.

Authority is separate from state. Memory, a CRM field, model output, replay score or diagnostic completion score may describe or propose commercial state. None may manufacture permission to send, change price, book, charge, mark cash verified, or declare Experiment Zero complete. Root policy and signed action authority remain outside the projection.

Dense feedback without self-deception

Attach typed feedback to the episode without letting feedback mutate state directly. A feedback record should name the observed failure, candidate cause, evidence, bounded proposed change, local check, end-to-end check and decision. UNKNOWN or mixed attribution produces NO_LEARNING_SIGNAL. Replay may score a proposed reducer or decision only on recorded branches. An unseen action remains LIVE EVIDENCE REQUIRED.

A continuous diagnosticCompletion field can explain which verified stages exist, but it must never be summed into a probability of closing. Weights should be diagnostic and versioned, not a hidden sales forecast. CASH_VERIFIED stays binary and external. This follows Android Bench 2.0's useful separation between pass and completion while avoiding its task-specific judges and private dataset as commercial authorities.

Migration plan — only after shadow evidence

Phase 0 is this proposal and a schema review. Phase 1 would implement a pure reducer over copied, privacy-safe test fixtures and historical canonical events. Phase 2 would rebuild shadow projections and compare them against existing records without serving or gating any production action. Phase 3 would add invariant tests, superseding-event tests, idempotency tests, stale-dependency tests and reconciliation alerts. Only after mismatches are understood could a separately approved migration expose the projection to runtime readers.

Rollback is deletion and rebuild of the derived projection, never deletion or rewriting of canonical history. The existing worker stays live under its current law during design and shadow validation. External sending remains governed by the existing policy and operational state. This article authorizes no production migration.

Privacy and publication boundary

The public projection must expose only aggregate phase and proof class. It must not publish prospect identity, addresses, private messages, raw prompts, Mother internals, credentials, private graph data, payment identifiers or commercially sensitive terms. Public status should say what class of evidence exists and what remains unproven, not who the counterpart is.

Private evidence references stay tenant-local. Release-safe telemetry may carry opaque IDs, counts, coarse status and deterministic proof bands. Any public route must continue to distinguish historical totals, current worker health, provider acceptance, delivery, replies, opportunities and cash rather than compressing them into one optimistic number.

Practical test: rebuild one episode and prove every transition

Using privacy-safe fixtures, build a sequence that includes resolved identity, evidence, a signed brief, provider acceptance, delayed delivery evidence, a reply, an opportunity, payment pending and cash verification. Shuffle delivery order while preserving occurred-at timestamps. Rebuild twice and require byte-equivalent CommercialState output, one effect per idempotency key, and an evidence reference for every verified phase.

Then inject five adversarial events: a duplicate send result, cash_verified without a payment-rail reference, an opt-out followed by send_authorized, a stale Action Brief after evidence changes, and a model narration that says the deal is won. The reducer must deduplicate the first and reject or quarantine the other four without rewriting canonical history.

What remains unknown

• Whether one commercial episode can be defined cleanly when several contacts, threads, opportunities or payment attempts belong to the same account.
• Which diagnostic completion dimensions help operators without becoming an uncalibrated close-probability score.
• How much projection and reconciliation complexity the current one-customer experiment justifies before commercial evidence exists.
• Whether shadow rebuilding over current history exposes contradictions that require new canonical event types.
• Whether this proposal should ever be implemented; it must earn that decision through observed production need rather than architectural preference.

Primary sources

• Ernesta Labs research: agent fleets need a coordinator and dense feedback
• Ernesta Labs research: replay is not reality
• Ernesta Labs minimal runtime synthesis
• Experiment Zero public status boundary