Documentation-only technical design for a future seed importer. It defines architecture, contracts, safety gates, and failure handling without creating runtime importer code.
Design sections
8
architecture, data, validation, audit, failure, testing
Runtime services
0
no service or worker created
Write contracts
0
no database writer approved
Blocked mutations
10
Phase 156-159 locks remain
Purpose
Phase 160 translates the approved seed-import idea into architecture lanes, draft contracts, validation sequence, failure modes, and test expectations. It prepares engineers for a future scope review without executing any import.
Runtime lock
The future importer remains blocked from PO, GRN, inventory, invoice, ledger, wallet, payout, settlement, confirmed order, and runtime import mutation until later approved gates exist.
Architecture lanes
Accept a seed pack envelope and readiness evidence for validation planning.
Inputs
Outputs
Blocked
Cannot accept production tenant payload or unsafe mutation request.
Define the validation stages a future importer must pass before any write is even considered.
Inputs
Outputs
Blocked
Cannot bypass backend permission or maker-checker approval.
Map seed groups to existing backend concepts without merging operational truth into product identity.
Inputs
Outputs
Blocked
Cannot map shop listing as inventory or customer demand as order.
Document what a later writer might need, while keeping Phase 160 no-write.
Inputs
Outputs
Blocked
Cannot create tables, services, queues, workers, jobs, or migrations.
Define request ids, actor ids, reviewer notes, retained evidence, and report packets.
Inputs
Outputs
Blocked
Cannot silently approve or delete blocked evidence.
Define threat controls for cross-tenant imports, mutation injection, fake wallet claims, and permission bypass.
Inputs
Outputs
Blocked
Cannot relax financial, inventory, ledger, or customer-data boundaries.
Draft contracts
These are documentation names for future review. They are not DTOs, database models, route handlers, or queue messages.
Plan draft is metadata only and cannot be executed.
Mapping draft cannot create linked operational records.
Validation report stays advisory until a future implementation gate exists.
Audit packet cannot replace backend auth, legal, or finance approval.
Validation pipeline
Read source pack, dry-run report, readiness desk decision, and maker-checker approval packet.
Stop if evidence chain is missing.
Normalize schemaVersion, packId, tenantScope, importPolicy, entities, relationships, and blockedMutations.
Stop if schema is unknown.
Confirm demo_only scope and design-only mode before any future runtime is considered.
Stop if scope is production, cross-tenant, or unclear.
Compare stable seed keys and decide create, compare, skip, or conflict behavior in documentation.
Stop if duplicate handling is undefined.
Check product, actor, RFQ, quote, listing, demand, logistics, and payment-evidence ordering.
Stop if downstream records appear before upstream truth.
Reject PO, GRN, inventory, invoice, ledger, wallet, payout, settlement, and confirmed order mutation requests.
Stop if any runtime mutation is requested.
Produce design readiness, warnings, open questions, and future implementation checklist.
Report only; no writer is produced.
Failure modes
Detection
tenantScope is not demo_only or does not match approved scope.
Response
Block design progression and archive evidence.
Detection
Payload contains any blocked mutation such as wallet.balanceMutate or inventoryMovement.post.
Response
Reject request, require security note, and preserve report.
Detection
Stable keys exist but conflict behavior is missing or contradictory.
Response
Request design changes before implementation planning.
Detection
Backend role required for a future step is not specified.
Response
Block approval until permission owner is defined.
Detection
A downstream record has no source entity or dependency reference.
Response
Mark as missing dependency and stop writer design.
Testing plan
Pass with warnings only, no write target produced.
Report duplicate-safe comparison behavior, no duplicate creation.
Critical block before mapping or persistence planning.
Dependency block before listing, demand, or payment evidence planning.
Warning or block until backend permission owner is defined.
Documentation checklist
Purpose and non-goals are stated.
Source evidence chain is linked.
Architecture lanes are defined.
Draft contracts are named without implementing code.
Validation pipeline is ordered.
Failure modes and responses are documented.
Testing plan is documented.
All runtime mutation locks remain active.
No service, API, worker, queue, migration, or database writer is created.
Technical design packet
{
"technicalDesignId": "seed_importer_tdd_001",
"phase": "Phase 160",
"sourceApprovalGate": "FAEDA-SEED-IMPORT-APPROVAL-001",
"sourceApprovalPacket": "seed_import_approval_gate_001",
"designOnly": true,
"noRuntimeImporter": true,
"noDatabaseWrites": true,
"noMigrations": true,
"architectureLanes": [
"Input lane",
"Validation lane",
"Mapping lane",
"Persistence lane",
"Audit lane",
"Security lane"
],
"draftContracts": [
"SeedImportPlanDraft",
"SeedEntityMappingDraft",
"SeedValidationReport",
"SeedImportAuditPacket"
],
"validationSteps": [
"Load approved design evidence",
"Normalize envelope",
"Verify tenant and mode",
"Resolve idempotency keys",
"Validate dependency graph",
"Apply mutation locks",
"Generate design report"
],
"blockedMutations": [
"purchaseOrder.issue",
"goodsReceipt.approve",
"inventoryMovement.post",
"supplierInvoice.accept",
"threeWayMatch.autoApprove",
"payable.approve",
"partnerPayment.execute",
"ledger.post",
"wallet.balanceMutate",
"customerOrder.confirm"
],
"nextAllowedGate": "implementation_scope_review_only"
}Hard rules
Phase 160 creates documentation only.
No route handler, API endpoint, backend service, worker, queue, cron, migration, or database writer may be created here.
Technical design cannot approve runtime import execution.
Technical design must preserve all Phase 156-159 mutation locks.
Next gate can review implementation scope only; it still must not run an importer.
Next build gate
The next safe step is a combined role readiness sprint: scope review, QA matrix, demo personas, permissions, dashboards, workbenches, seed binding, and functional-lite role checks.