Bind the Real Boundary

Course boundary: Optional Komal learning material. Not required by Abhyaas. NOT FOR LIVE CERTIFICATION BANK. All systems and records in this module are synthetic and local.

The first module created permission to investigate. This module converts that permission into an implementable boundary. You will follow one synthetic technician intent across equipment reconciliation, data validation, evidence retrieval, inventory state, policy, approval, audit, and response. The goal is not broad feature coverage. It is one consequential path whose contracts and failures are visible end to end.

Demonstration: the happy path is not the boundary

Run:

npm run course:fde -- --module 02

The demonstration reports two executions. The first reaches ready-for-review. The second stops at equipment-match because the ticket contains an ambiguous equipment reference. Compare the traces.

The implementation boundary includes both outcomes. If the architecture diagram contains only the successful route, it omits the state that protects the system from acting on an unbound identity. A failure is part of the contract when callers, operators, or users must respond to it.

Inspect the companion modules named in the trace:

contracts -> environment -> authorization -> evidence
inventory -> bounded model -> qualified approval -> policy
audit -> telemetry -> response

Do not interpret this list as a mandated service decomposition. It is a responsibility and evidence decomposition. Several responsibilities could share a runtime while retaining separate contracts and owners.

Scenario walkthrough: from logical boxes to customer work

The team proposes this architecture sentence:

Orchid Assist runs in the customer environment and integrates with their systems.

That sentence hides the work. Expand it across six boundaries:

1. Structural: which component owns equipment reconciliation, evidence selection, inventory access, policy, approval, audit, and response?
2. Runtime: where does each component execute, and what identity, network, configuration, secret, capacity, and regional constraints apply?
3. Data: what fields cross each interface, with what semantics, lineage, freshness, retention, and invalid-state behavior?
4. Trust: which principal can perform which operation on which resource, tenant, and region, until what expiry?
5. Failure: what happens when each dependency rejects, times out, returns malformed data, or has ambiguous completion?
6. Responsibility: who builds, operates, supports, approves change, and makes the formal decision for each boundary?

Your architecture is incomplete if customer IT or platform is the answer to every responsibility. Team labels do not specify code, runtime, control, support, or decision ownership.

Guided lab: produce OA-05 and a vertical-slice contract

Step 1: define the intent envelope

Use this provider-neutral envelope:

{
  "intentId": "INTENT-SYNTHETIC-02",
  "correlationId": "CORR-SYNTHETIC-02",
  "tenant": "orchid-synthetic",
  "region": "west-synthetic",
  "actor": "technician-synthetic",
  "operation": "request-inspection-evidence",
  "ticketId": "TICKET-SYNTHETIC-02",
  "equipmentReference": "PUMP-7"
}

Add preconditions, accepted states, rejected states, and unknown states. State which fields are identifiers versus display labels. Define how a caller can safely retry and how conflicting reuse of intentId is rejected.

Step 2: make data quality semantic

Define structural and semantic validation separately. Structural validation can establish required fields and types. Semantic validation must address tenant, region, equipment identity, evidence approval, version/freshness, and whether the requested operation is meaningful for the equipment state.

Include cases for:

• missing equipment reference;
• multiple equipment candidates;
• equipment in another tenant or region;
• stale approved evidence;
• inventory response missing completion state;
• duplicate intent with identical semantics;
• duplicate intent with different semantics.

Step 3: bind authorization to the operation

Create one allowed and three denied authorization records. Every record must evaluate principal, resource, operation, tenant, region, qualification, and expiry. Include a technically authenticated principal that is denied because it lacks regional or qualification scope.

Step 4: allocate failure behavior

For each external seam, record:

dependency
observable request state
possible completion states
timeout meaning
safe retry rule
reconciliation method
user-visible fallback
operator signal
owner

Never translate timeout directly into failed when the external side effect may have completed. Preserve unknown until reconciliation can establish a terminal state.

Step 5: produce the boundary map

Create OA-05 Architecture, Interfaces, Data, Environment, AI, and Governance. At minimum it must show the representative intent, every trust transition, data minimization decision, deterministic control, human authority, audit record, telemetry seam, failure return, and named owner.

Debugging drill: four defects, one misleading symptom

The synthetic user sees No approved evidence available. The defect may be:

• the equipment reference is ambiguous;
• the equipment is confirmed but belongs to a different region;
• evidence exists but is stale or not approved for the operation;
• the evidence service timed out after receiving the request.

Design the next discriminating observation for each branch. A useful diagnostic tree asks for evidence that divides hypotheses; it does not restart the entire request or blame the user.

Then inspect the module output. It contains a boundaryReview array. For every rejected record, write the smallest contract or responsibility change that would make the state explicit. Do not repair a missing semantic state with logging alone.

Project checkpoint: vertical-slice coverage test

Your slice passes when it crosses all of these dimensions:

Dimension	Required evidence
real intent and state	versioned request and terminal/unknown outcomes
representative interface	validated input/output/error contract
representative data	tenant, region, identity, provenance, freshness
external boundary	adapter with reject/timeout/unknown behavior
identity and authorization	operation-scoped decision with denial evidence
policy or AI	deterministic control outside any model
audit and telemetry	allowlisted, correlation-safe records
environment/configuration	validated region and secret-free configuration
controlled failure	safe visible fallback and owner

If any row is replaced with a promise to build it later, the slice is not end to end.

Completion evidence

Submit the intent envelope, semantic-state table, four authorization records, dependency failure table, boundary map, and a trace from one accepted and one safely blocked execution. A reviewer must be able to explain why the blocked execution did not call downstream evidence or inventory dependencies.

Prohibited overclaims

Passing local contracts does not prove real identity-provider behavior, customer network reachability, production data quality, dependency availability, security approval, performance, accessibility, or operational support. It proves only that the synthetic boundary is explicit and executable.