Phase 176FAEDA-EVIDENCE-STORAGE-PERMISSION-DESIGN-001contract design only

Evidence Data Contract Design

A schema-first design gate for evidence metadata, storage references, audit fields, redaction markers, review decisions, and retention signals before any storage implementation exists.

Permission gate QA evidence Control Provider boundary

Metadata fields

identity, scope, proof, status

Storage refs

future object references only

Audit fields

created, classified, reviewed

Runtime writes

no table or file creation

Evidence record identity

Stable evidence ID, phase source, role scope, subject scope, route source, and proof type.

Every future evidence record can be traced back to the QA gate that produced it.

Storage reference

References future storage objects without creating buckets, upload APIs, download APIs, or files.

Storage can be swapped later without changing review truth.

Privacy and redaction

Privacy class, sensitivity reason, redaction markers, forbidden content flags, and demo-safe status.

No CNIC, wallet PIN, provider secret, live credential, or customer-private data leaks by contract.

Review decision

Structured decisions for draft review, hold, rejected, approved internal, approved demo-safe, or restored.

Manual review stays visible, auditable, and maker-checker ready.

Audit and retention

Created, classified, redacted, reviewed, exported, deleted, restored, and retention review markers.

Future storage can follow data protection and audit rules without guesswork.

Contract boundary

Defines required fields and blocked mutations while leaving runtime implementation for later approval gates.

Phase 176 produces design truth, not database truth.

Metadata schema

Evidence record fields

evidenceId

string

required: yessystem

Stable unique record key.

sourcePhase

string

required: yessystem

Example: Phase 174, 175, or 176.

sourceGateCode

string

required: yessystem

Gate or page code that created the evidence candidate.

sourceRoute

string

required: yessystem

Route that evidence is about.

roleScope

enum

required: yesreviewer

Supplier, Manufacturer, Wholesaler, Retailer, Customer, Rider, Founder/Admin, or System.

subjectType

enum

required: yesreviewer

route, module, role, order, payment, ledger, inventory, PO, GRN, invoice, support.

subjectIdRef

string|null

required: conditionalsystem

Reference only; no private payload copied into evidence.

title

string

required: yesreviewer

Human-readable evidence title.

summary

string

required: yesreviewer

Short safe summary for QA review.

proofType

enum

required: yesreviewer

Allowed from Phase 174 proof types: , , , , , .

storageLane

enum

required: yesreviewer

Allowed lanes: visual-screenshot, review-note, boundary-proof, mobile-proof, review-decision.

privacyClass

enum

required: yessecurity

Allowed classes: Public-safe, Internal, Restricted, Forbidden.

sensitivityReason

string

required: conditionalsecurity

Required when privacy class is Internal, Restricted, or Forbidden.

captureMode

enum

required: yessystem

manual-note, screenshot-reference, mobile-proof, boundary-proof, decision-record.

captureTimestamp

datetime

required: yessystem

When evidence was captured or referenced.

createdByRef

string

required: yessystem

Actor reference, not full profile.

status

enum

required: yesreviewer

Draft, hold, approved, rejected, deleted pending retention, or restored.

References, not files

storageProviderKey

string|null

Future provider alias only; never provider credentials.

bucketOrContainerRef

string|null

Future logical container reference, not a public URL.

objectKeyRef

string|null

Future object key reference after upload is approved.

redactedObjectKeyRef

string|null

Separate future reference for redacted copy.

checksumSha256

string|null

Integrity hash once storage exists.

mimeType

string|null

Allowlisted content type, not trusted from browser alone.

byteSize

number|null

Size limit check once uploads exist.

dimensions

object|null

Width and height for visual evidence only.

signedViewPolicyRef

string|null

Future signed-view policy reference, not the signed URL itself.

Audit contract

Who touched what, when, and why

createdAt/createdBy

Who created the evidence record candidate.

classifiedAt/classifiedBy

Who assigned privacy and sensitivity.

redactedAt/redactedBy

Who applied redaction or locked content.

reviewedAt/reviewedBy

Who reviewed the evidence packet.

approvedAt/approvedBy

Who made the final approved state.

exportedAt/exportedBy

Who exported and why.

deletedAt/deletedBy

Who requested deletion under retention rules.

restoredAt/restoredBy

Who restored evidence after incident approval.

lastDecisionAt/lastDecisionBy

Latest human decision marker.

makerCheckerRef

Future maker-checker chain reference.

retentionReviewAt

Date evidence should be reviewed for deletion or continued hold.

auditTrailRef

Future immutable audit reference, not the audit rows themselves.

Decision states

Review outcomes the backend must understand later

draft_review

Evidence is only a draft candidate.

needs_redaction

Evidence cannot be shared until sensitive portions are masked.

restricted_hold

Evidence is locked to security/founder review.

approved_internal

Evidence can be used internally for QA or developer correction.

approved_demo_safe

Evidence is safe to show in demo or founder walkthrough.

rejected

Evidence is invalid, unsafe, duplicate, or not useful.

deleted_pending_retention

Deletion requested but retention/audit rules still apply.

restored_after_incident

Evidence restored with incident approval and audit trail.

Redaction markers

How sensitive proof is marked

none

No sensitive area found after review.

crop

Crop unrelated browser/device/customer area.

blur

Blur visible private or operational details.

mask_text

Mask token-like, ID-like, phone, CNIC, or account text.

remove_metadata

Strip EXIF/device/browser metadata before storage.

replace_reference

Store a safe reference instead of the original sensitive object.

hard_block

Block forbidden evidence from being uploaded or retained.

Contract relations

How evidence truth connects

Phase 174 evidence candidate

Evidence metadata record

Candidate proof is normalized into a scoped record with role, route, proof type, and privacy class.

Evidence permission gate

Action permission map

Allowed actions stay aligned with 8 Phase 175 permission actions.

Evidence metadata record

Storage reference

Metadata points to future storage reference; storage object is never embedded into the record.

Storage reference

Review decision

Reviewer can decide internal/demo-safe status only after privacy and redaction checks.

Review decision

Audit trail

Every decision, export, deletion, and restoration must become audit evidence later.

Validation rules

Rules before any storage exists

Evidence record must include source phase, source route, role scope, proof type, storage lane, privacy class, and status.

Restricted or forbidden privacy classes must include a sensitivity reason and cannot be demo-safe by default.

Forbidden evidence must not receive a storage reference; it must move to hard_block or incident handling.

Storage references must never contain provider secrets, public URLs, signed URLs, customer private data, or raw file content.

Approval, export, deletion, and restoration must require maker-checker references once backend exists.

Redacted evidence must keep original and redacted references separate under security policy.

Customer-scoped evidence must never reveal other customer, supplier, rider, ledger, payment, or internal cost data.

The contract can be reviewed now, but database tables, migrations, upload APIs, workers, and buckets remain blocked.

Hard rules

Contract design is not backend storage

Phase 176 is a data contract design gate only.

Do not create migrations, database tables, storage buckets, upload endpoints, download endpoints, signed URL endpoints, queues, workers, or files in this phase.

Do not copy screenshots, CNIC, wallet PIN, bank details, provider secrets, customer private data, or production credentials into the codebase.

Do not treat JSON preview as a live API response or database schema.

Next gate should design evidence storage provider boundaries before any real storage implementation.

Contract packet

JSON preview

{
  "contractId": "evidence_data_contract_design_176",
  "phase": "Phase 176",
  "route": "/business-pro/evidence-data-contract-design",
  "sourceGate": "evidence_storage_permission_design_gate_175",
  "evidenceDesk": "role_qa_evidence_capture_desk_174",
  "sourceDeskCode": "FAEDA-ROLE-QA-EVIDENCE-CAPTURE-001",
  "designOnly": true,
  "createsDatabase": false,
  "createsStorage": false,
  "createsUploadApi": false,
  "createsDownloadApi": false,
  "metadataFields": [
    "evidenceId",
    "sourcePhase",
    "sourceGateCode",
    "sourceRoute",
    "roleScope",
    "subjectType",
    "subjectIdRef",
    "title",
    "summary",
    "proofType",
    "storageLane",
    "privacyClass",
    "sensitivityReason",
    "captureMode",
    "captureTimestamp",
    "createdByRef",
    "status",
    "tags"
  ],
  "storageReferenceFields": [
    "storageProviderKey",
    "bucketOrContainerRef",
    "objectKeyRef",
    "redactedObjectKeyRef",
    "checksumSha256",
    "mimeType",
    "byteSize",
    "dimensions",
    "signedViewPolicyRef"
  ],
  "auditFieldCount": 12,
  "decisionStates": [
    "draft_review",
    "needs_redaction",
    "restricted_hold",
    "approved_internal",
    "approved_demo_safe",
    "rejected",
    "deleted_pending_retention",
    "restored_after_incident"
  ],
  "redactionMarkers": [
    "none",
    "crop",
    "blur",
    "mask_text",
    "remove_metadata",
    "replace_reference",
    "hard_block"
  ],
  "candidateCount": 21,
  "nextAllowedGate": "phase_177_evidence_storage_provider_boundary_design"
}

Next build gate

Phase 177 is evidence storage provider boundary design

After the data contract is clear, the next safe move is deciding provider boundaries, encryption, signed-view policy, and retention controls without storing files.

Open provider boundary