Initial commit: Add project files

contracts/README.md

@@ -0,0 +1,9 @@
+# Versioned contracts
+
+This directory is the machine-readable contract surface for policy, event and outcome-metric definitions.
+
+- `policies/sell-policy-contract.v1.json`: approved research-candidate implementation values; SHA-256 `a269a0331b83c0f6ec108e7587de1d20c798036ff8d0c03d726cd854e73d8480`.
+- `events/signal-decision-created.v2.schema.json`: immutable outbox payload contract.
+- `metrics/outcome-metrics.v1.json`: proposed metric definitions; Quant/Risk approval is still required.
+
+The C# constants are intentionally checked against the policy JSON by `scripts/validate_v123.py`. A changed value without a Model Change record, Golden vectors and OOS impact evidence blocks G2.

contracts/data/pit-envelope.v1.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PIT Execution Envelope",
+  "contractVersion": "1.0",
+  "required": [
+    "asOf",
+    "publishedAtCutoff",
+    "datasetId",
+    "modelVersion",
+    "configVersion",
+    "codeSha",
+    "contractVersion",
+    "contentHash",
+    "correlationId"
+  ],
+  "rules": [
+    "server-resolved-context",
+    "no-client-evidence-trust",
+    "append-only-evidence",
+    "tradable-session-cutoff"
+  ]
+}

contracts/data/projection-contract.v1.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Projection Contract",
+  "contractVersion": "1.0",
+  "required": [
+    "projectionName",
+    "projectionVersion",
+    "sourceWatermark",
+    "builtAt",
+    "staleAfter",
+    "rebuildPolicy",
+    "owner"
+  ],
+  "states": [
+    "CURRENT",
+    "STALE",
+    "REBUILDING",
+    "FAILED",
+    "QUARANTINED"
+  ]
+}

contracts/events/signal-decision-created.v2.schema.json

@@ -0,0 +1,69 @@
+{
+  "$id": "https://kartsell.local/contracts/events/signal-decision-created.v2.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "action": {
+      "enum": [
+        "Hold",
+        "PartialSell",
+        "FullSell"
+      ]
+    },
+    "createdAt": {
+      "format": "date-time",
+      "type": "string"
+    },
+    "datasetId": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "decisionContractVersion": {
+      "const": "sell-decision.v2"
+    },
+    "decisionId": {
+      "format": "uuid",
+      "type": "string"
+    },
+    "evidenceId": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "policyId": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "policyTraceSchemaVersion": {
+      "const": 2
+    },
+    "positionLotId": {
+      "format": "uuid",
+      "type": "string"
+    },
+    "sellRatioOfLot": {
+      "maximum": 1,
+      "minimum": 0,
+      "type": "number"
+    },
+    "targetSecurityPortfolioWeightAfter": {
+      "maximum": 1,
+      "minimum": 0,
+      "type": "number"
+    }
+  },
+  "required": [
+    "decisionId",
+    "positionLotId",
+    "policyId",
+    "action",
+    "sellRatioOfLot",
+    "targetSecurityPortfolioWeightAfter",
+    "evidenceId",
+    "datasetId",
+    "decisionContractVersion",
+    "policyTraceSchemaVersion",
+    "createdAt"
+  ],
+  "title": "SignalDecisionCreated v2",
+  "type": "object"
+}

contracts/metrics/outcome-metrics.v1.json

@@ -0,0 +1,35 @@
+{
+  "metrics": [
+    {
+      "aggregation": "quantity weighted",
+      "definitionVersion": "1.0.0",
+      "denominator": "eligible sold quantity with complete PIT total-return outcome",
+      "metricId": "FALSE_EXIT_63D",
+      "notes": "Not directly comparable to annual 2% target until annualization and cohort rules are approved",
+      "numerator": "sold quantity whose benchmark-adjusted total return from decision price to window end is positive beyond approved materiality threshold",
+      "population": "non-hard sell decisions",
+      "windowTradingSessions": 63
+    },
+    {
+      "aggregation": "watch count",
+      "definitionVersion": "1.0.0",
+      "denominator": "eligible watches with complete observations",
+      "metricId": "REENTRY_CAPTURE_126D",
+      "minimumTarget": 0.65,
+      "numerator": "eligible watches that create an approved stage before expiry",
+      "population": "reentry-eligible sell decisions",
+      "windowTradingSessions": 126
+    },
+    {
+      "aggregation": "count",
+      "definitionVersion": "1.0.0",
+      "denominator": "not applicable",
+      "maximumTarget": 0,
+      "metricId": "DUPLICATE_STAGE_COUNT",
+      "numerator": "duplicate execution attempts accepted",
+      "population": "all reentry stages"
+    }
+  ],
+  "registryVersion": "outcome-metrics.v1",
+  "status": "PROPOSED_REQUIRES_QUANT_RISK_APPROVAL"
+}

contracts/metrics/outcome-metrics.v2.json

@@ -0,0 +1,56 @@
+{
+  "contractVersion": "outcome-metrics.v2",
+  "status": "PROPOSED",
+  "commonRules": {
+    "pointInTime": true,
+    "revisionAware": true,
+    "costs": ["fee", "tax", "fx", "slippage"],
+    "windowsTradingDays": [1, 5, 20, 63, 126, 252],
+    "attribution": ["recommendation", "publication", "clientDecision", "execution"]
+  },
+  "metrics": [
+    {
+      "metricCode": "OPERATIONAL_INTEGRITY_ERRORS",
+      "numerator": "count of duplicate, lookahead, unauthorized publication, unreconciled critical breaks and immutable-evidence violations",
+      "denominator": "one evaluation run",
+      "aggregation": "sum",
+      "threshold": "0"
+    },
+    {
+      "metricCode": "FALSE_EXIT_ANNUAL_RATE",
+      "numerator": "eligible non-impairment exits followed by approved adverse-regret condition within the versioned evaluation window",
+      "denominator": "all eligible non-impairment exits in the same cohort",
+      "aggregation": "annualized cohort ratio",
+      "threshold": "<=0.02",
+      "decisionRequired": "The exact adverse-regret price and benchmark definition must be approved before production use."
+    },
+    {
+      "metricCode": "REENTRY_CAPTURE_RATE",
+      "numerator": "eligible exits whose versioned reentry contract produced a valid stage-ready observation within 126 trading days",
+      "denominator": "all eligible non-impairment exits with complete data",
+      "aggregation": "cohort ratio",
+      "threshold": ">=0.65"
+    },
+    {
+      "metricCode": "NET_EXPECTED_UTILITY",
+      "numerator": "realized or calibrated expected benefit after risk, fee, tax, FX, slippage and reentry option loss",
+      "denominator": "one evaluated decision or cohort",
+      "aggregation": "mean with confidence interval",
+      "threshold": ">0 and lower confidence bound >0 for opportunity replacement"
+    },
+    {
+      "metricCode": "PBO",
+      "numerator": "CSCV combinations where in-sample winner underperforms out of sample",
+      "denominator": "all approved CSCV combinations",
+      "aggregation": "probability",
+      "threshold": "<=0.20"
+    },
+    {
+      "metricCode": "DSR",
+      "numerator": "deflated performance statistic adjusted for multiple testing and non-normality",
+      "denominator": "approved experiment registry",
+      "aggregation": "probability/confidence",
+      "threshold": ">=0.95"
+    }
+  ]
+}

contracts/model-governance/evaluation-promotion.v2.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Model Evaluation and Promotion Contract v2",
+  "contractVersion": "2.0",
+  "promotionMode": "HUMAN_CHANGE_APPROVAL_ONLY",
+  "automaticActivation": false,
+  "automaticOrder": false,
+  "requiredEvidence": [
+    "252-trading-session-shadow",
+    "multiple-regimes",
+    "calibration",
+    "sell-reentry-attribution",
+    "PBO",
+    "DSR",
+    "double-cost-positive",
+    "independent-validation",
+    "rollback-evidence",
+    "operations-integrity"
+  ]
+}

contracts/model-governance/evidence-classification.v1.json

@@ -0,0 +1,18 @@
+{
+  "contractVersion": "1.0.0",
+  "classes": [
+    {"code":"SOURCE","description":"Original source, license, schema or policy evidence"},
+    {"code":"RUNTIME","description":"Build, test, migration, performance or operational evidence"},
+    {"code":"RESEARCH","description":"Frozen backtest, OOS, calibration, PBO/DSR or model-comparison evidence"},
+    {"code":"RELEASE","description":"Approved release bundle with required runtime and governance artifacts"},
+    {"code":"AUDIT","description":"Immutable decision, review, correction and chain-of-custody evidence"}
+  ],
+  "statusTransitions": {
+    "IMPLEMENTATION_TEMPLATE": ["STATIC_VALIDATED"],
+    "STATIC_VALIDATED": ["BUILD_VALIDATED"],
+    "BUILD_VALIDATED": ["DB_REHEARSED"],
+    "DB_REHEARSED": ["SHADOW_READY"],
+    "SHADOW_READY": ["PILOT_REVIEW_REQUIRED"]
+  },
+  "forbiddenShortcut": "No state may be inferred from file presence or document version number."
+}

contracts/model-governance/promotion-gate.v1.json

@@ -0,0 +1,32 @@
+{
+  "contractVersion": "promotion-gate.v1",
+  "status": "PROPOSED",
+  "boundary": "EVIDENCE_ONLY_NO_AUTO_PROMOTION",
+  "thresholds": {
+    "minimumShadowTradingDays": 252,
+    "preferredShadowTradingDays": 504,
+    "minimumDistinctRegimes": 2,
+    "maximumFalseExitAnnualRate": 0.02,
+    "minimumReentryCaptureRate": 0.65,
+    "maximumPbo": 0.20,
+    "minimumDsr": 0.95,
+    "positiveNetExpectedUtility": true,
+    "positiveUnderDoubleCost": true,
+    "operationalIntegrityErrors": 0,
+    "calibrationStable": true
+  },
+  "mandatoryApprovals": [
+    "IndependentValidation",
+    "Risk",
+    "InvestmentCommittee",
+    "Compliance",
+    "Security",
+    "Operations"
+  ],
+  "forbiddenActions": [
+    "automatic model activation",
+    "automatic threshold change",
+    "automatic order submission",
+    "KIS submission"
+  ]
+}

contracts/policies/sell-policy-contract.v1.json

@@ -0,0 +1,83 @@
+{
+  "changeControl": "MODEL_CHANGE_AND_GOLDEN_OOS_REQUIRED",
+  "contractVersion": "sell-policy.v1",
+  "decisionContractVersion": "sell-decision.v2",
+  "policies": [
+    {
+      "condition": "approved hard impairment",
+      "documentedRange": [
+        0.8,
+        1.0
+      ],
+      "mayCrossStrategicCore": true,
+      "policyId": "ALG-SELL-001",
+      "priority": 1000,
+      "reentryEligible": false,
+      "requestedSellRatioOfLot": 1.0,
+      "terminal": true
+    },
+    {
+      "condition": "capital floor breached",
+      "decisionRequired": "Whether portfolio survival bypasses same-direction cooldown",
+      "mayCrossStrategicCore": true,
+      "policyId": "ALG-SELL-PORT-001",
+      "priority": 900,
+      "ratioSource": "server PIT risk context",
+      "reentryEligible": true,
+      "terminal": true
+    },
+    {
+      "condition": {
+        "gapBelowFloorAtrGte": 1.5
+      },
+      "documentedRange": [
+        0.3,
+        0.5
+      ],
+      "mayCrossStrategicCore": false,
+      "policyId": "ALG-SELL-002",
+      "priority": 800,
+      "reentryEligible": true,
+      "requestedSellRatioOfLot": 0.4,
+      "terminal": false
+    },
+    {
+      "condition": {
+        "consecutiveCloseBreachesGte": 2
+      },
+      "documentedRange": [
+        0.15,
+        0.25
+      ],
+      "mayCrossStrategicCore": false,
+      "policyId": "ALG-SELL-003",
+      "priority": 700,
+      "reentryEligible": true,
+      "requestedSellRatioOfLot": 0.2,
+      "terminal": false
+    },
+    {
+      "condition": "approved concentration/liquidity excess ratio > 0",
+      "mayCrossStrategicCore": false,
+      "policyId": "ALG-SELL-004",
+      "priority": 600,
+      "ratioSource": "server PIT portfolio risk context",
+      "reentryEligible": true,
+      "terminal": false
+    },
+    {
+      "condition": "opportunity edge lower bound > 0 and requested ratio > 0",
+      "mayCrossStrategicCore": false,
+      "policyId": "ALG-SELL-005",
+      "priority": 500,
+      "reentryEligible": true,
+      "requestedRange": [
+        0.1,
+        0.25
+      ],
+      "terminal": false
+    }
+  ],
+  "policyTraceSchemaVersion": 2,
+  "status": "RESEARCH_CANDIDATE_NOT_PRODUCTION"
+}

contracts/schedules/execution-assurance.v1.json

@@ -0,0 +1,27 @@
+{
+  "contractVersion": "1.0.0",
+  "boundary": "EVIDENCE_ONLY_NO_AUTO_MODEL_OR_ORDER_MUTATION",
+  "dispatcher": {
+    "enabledByDefault": false,
+    "defaultCronUtc": "*/15 * * * *",
+    "leaseMinutes": 14,
+    "batchLimit": 50,
+    "requiresCapability": "ShadowEvaluation"
+  },
+  "operations": [
+    {"code":"J25","name":"SourceContractDriftCheck","cadence":"DAILY","mode":"EVALUATION_ONLY","queue":"q-evaluation","enabledByDefault":false},
+    {"code":"J26","name":"MarketCalendarCompletenessCheck","cadence":"DAILY","mode":"EVALUATION_ONLY","queue":"q-market-data","enabledByDefault":false},
+    {"code":"J27","name":"EvidenceChainAudit","cadence":"DAILY","mode":"EVALUATION_ONLY","queue":"q-control","enabledByDefault":false},
+    {"code":"J28","name":"ProjectionFreshnessCheck","cadence":"DAILY","mode":"EVALUATION_ONLY","queue":"q-evaluation","enabledByDefault":false},
+    {"code":"J29","name":"CapacitySlaTrend","cadence":"WEEKLY","mode":"EVALUATION_ONLY","queue":"q-control","enabledByDefault":false},
+    {"code":"J30","name":"ReleaseEvidenceAssemble","cadence":"EVENT_DRIVEN","mode":"PROPOSAL_ONLY","queue":"q-control","enabledByDefault":false}
+  ],
+  "forbiddenEffects": [
+    "MODEL_VERSION_ACTIVATION",
+    "MODEL_CONFIGURATION_MUTATION",
+    "CODE_MERGE",
+    "CLIENT_PUBLICATION",
+    "BROKER_ORDER_SUBMISSION",
+    "KIS_SUBMISSION"
+  ]
+}

contracts/schedules/execution-ledger.v1.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Scheduled Execution Ledger",
+  "contractVersion": "1.0",
+  "required": [
+    "operationCode",
+    "scopeKey",
+    "scheduledFor",
+    "dispatchRevision",
+    "leaseToken",
+    "idempotencyKey",
+    "versionSet",
+    "state",
+    "reasonCode",
+    "heartbeatAt"
+  ],
+  "states": [
+    "REQUESTED",
+    "LEASED",
+    "RUNNING",
+    "SUCCEEDED",
+    "BUSINESS_HOLD",
+    "FAILED",
+    "QUARANTINED",
+    "ABANDONED"
+  ],
+  "rules": [
+    "fencing-token-required",
+    "scheduled-for-anchor",
+    "no-blind-retry",
+    "terminal-state-immutable",
+    "manual-model-activation-only"
+  ]
+}

contracts/schedules/model-operations.v1.json

@@ -0,0 +1,28 @@
+{
+  "contractVersion": "model-operations.v1",
+  "status": "IMPLEMENTATION_TEMPLATE",
+  "algorithmStatus": "RESEARCH_CANDIDATE_NOT_PRODUCTION",
+  "dispatcher": {
+    "jobId": "model-operations-dispatcher-v1",
+    "cadence": "EVERY_15_MINUTES",
+    "queue": "q-control",
+    "leaseMinutes": 14,
+    "batchLimit": 50
+  },
+  "automationBoundary": {
+    "allowed": ["EVALUATION_ONLY", "PROPOSAL_ONLY", "DRILL_ONLY"],
+    "forbidden": ["AUTO_PROMOTE", "AUTO_ROLLBACK", "AUTO_PARAMETER_CHANGE", "AUTO_ORDER", "KIS_SUBMISSION"]
+  },
+  "operations": [
+    {"operationCode":"J10","name":"OutcomeEvaluationRun","cadence":"DAILY","queue":"q-evaluation","mode":"EVALUATION_ONLY","gate":"G3"},
+    {"operationCode":"J11","name":"DailyScorecardBuild","cadence":"DAILY","queue":"q-evaluation","mode":"EVALUATION_ONLY","gate":"G3"},
+    {"operationCode":"J17","name":"DriftDetectionRun","cadence":"DAILY","queue":"q-evaluation","mode":"EVALUATION_ONLY","gate":"G4"},
+    {"operationCode":"J18","name":"ChampionChallengerEvaluation","cadence":"WEEKLY","queue":"q-evaluation","mode":"EVALUATION_ONLY","gate":"G4"},
+    {"operationCode":"J19","name":"FrozenOosBacktest","cadence":"MONTHLY","queue":"q-research","mode":"EVALUATION_ONLY","gate":"G4"},
+    {"operationCode":"J20","name":"RobustnessPboDsrRun","cadence":"QUARTERLY","queue":"q-research","mode":"EVALUATION_ONLY","gate":"G4"},
+    {"operationCode":"J21","name":"ModelImprovementProposalBuild","cadence":"MONTHLY","queue":"q-research","mode":"PROPOSAL_ONLY","gate":"G4"},
+    {"operationCode":"J22","name":"PromotionEvidenceReviewBuild","cadence":"MONTHLY","queue":"q-control","mode":"PROPOSAL_ONLY","gate":"G4"},
+    {"operationCode":"J23","name":"ModelRollbackDrill","cadence":"QUARTERLY","queue":"q-control","mode":"DRILL_ONLY","gate":"G5"},
+    {"operationCode":"J24","name":"DataRevisionRevalidation","cadence":"WEEKLY","queue":"q-backfill","mode":"EVALUATION_ONLY","gate":"G3"}
+  ]
+}

contracts/schedules/model-operations.v2.json

@@ -0,0 +1,116 @@
+{
+  "contractVersion": "model-operations.v2",
+  "status": "IMPLEMENTATION_TEMPLATE",
+  "algorithmStatus": "RESEARCH_CANDIDATE_NOT_PRODUCTION",
+  "dispatcher": {
+    "jobId": "model-operations-dispatcher-v1",
+    "cadence": "EVERY_15_MINUTES",
+    "queue": "q-control",
+    "leaseMinutes": 14,
+    "batchLimit": 50,
+    "enabledByDefault": false
+  },
+  "automationBoundary": {
+    "allowed": [
+      "EVALUATION_ONLY",
+      "PROPOSAL_ONLY",
+      "DRILL_ONLY"
+    ],
+    "forbidden": [
+      "AUTO_PROMOTE",
+      "AUTO_ROLLBACK",
+      "AUTO_PARAMETER_CHANGE",
+      "AUTO_ORDER",
+      "KIS_SUBMISSION",
+      "CLIENT_PUBLICATION"
+    ]
+  },
+  "evaluationClock": {
+    "predictionFreeze": "before approved market cutoff",
+    "labelMaturity": "trading-session windows 1/5/20/63/126/252",
+    "revisionPolicy": "new revision; never overwrite prior evidence"
+  },
+  "operations": [
+    {
+      "operationCode": "J31",
+      "name": "PredictionFreezeRun",
+      "cadence": "DAILY",
+      "queue": "q-evaluation",
+      "mode": "EVALUATION_ONLY",
+      "gate": "G3",
+      "enabledByDefault": false
+    },
+    {
+      "operationCode": "J32",
+      "name": "OutcomeMaturitySweep",
+      "cadence": "DAILY",
+      "queue": "q-evaluation",
+      "mode": "EVALUATION_ONLY",
+      "gate": "G3",
+      "enabledByDefault": false
+    },
+    {
+      "operationCode": "J33",
+      "name": "SellReentryAttributionReview",
+      "cadence": "WEEKLY",
+      "queue": "q-evaluation",
+      "mode": "EVALUATION_ONLY",
+      "gate": "G4",
+      "enabledByDefault": false
+    },
+    {
+      "operationCode": "J34",
+      "name": "CalibrationRegimeReview",
+      "cadence": "WEEKLY",
+      "queue": "q-evaluation",
+      "mode": "EVALUATION_ONLY",
+      "gate": "G4",
+      "enabledByDefault": false
+    },
+    {
+      "operationCode": "J35",
+      "name": "ImprovementHypothesisBuild",
+      "cadence": "MONTHLY",
+      "queue": "q-research",
+      "mode": "PROPOSAL_ONLY",
+      "gate": "G4",
+      "enabledByDefault": false
+    },
+    {
+      "operationCode": "J36",
+      "name": "ChallengerExperimentPlan",
+      "cadence": "MONTHLY",
+      "queue": "q-research",
+      "mode": "PROPOSAL_ONLY",
+      "gate": "G4",
+      "enabledByDefault": false
+    },
+    {
+      "operationCode": "J37",
+      "name": "IndependentValidationPack",
+      "cadence": "QUARTERLY",
+      "queue": "q-control",
+      "mode": "PROPOSAL_ONLY",
+      "gate": "G4",
+      "enabledByDefault": false
+    },
+    {
+      "operationCode": "J38",
+      "name": "ModelPolicyDebtReview",
+      "cadence": "MONTHLY",
+      "queue": "q-control",
+      "mode": "PROPOSAL_ONLY",
+      "gate": "G5",
+      "enabledByDefault": false
+    },
+    {
+      "operationCode": "J39",
+      "name": "FeedbackCycleIntegrityAudit",
+      "cadence": "DAILY",
+      "queue": "q-control",
+      "mode": "EVALUATION_ONLY",
+      "gate": "G4",
+      "enabledByDefault": false
+    }
+  ]
+}

contracts/schedules/model-operations.v3.json

@@ -0,0 +1,20 @@
+{
+  "contractVersion": "model-operations.v3",
+  "status": "IMPLEMENTATION_TEMPLATE",
+  "algorithmStatus": "RESEARCH_CANDIDATE_NOT_PRODUCTION",
+  "dispatcher": {"jobId":"model-operations-dispatcher-v1","cadence":"EVERY_15_MINUTES","queue":"q-control","leaseMinutes":14,"batchLimit":50,"enabledByDefault":false},
+  "scheduleSemantics": {
+    "anchor":"next due time advances from scheduledFor, not worker dispatch time",
+    "timezone":"IANA/approved calendar mapping; UTC storage",
+    "catchUpPolicies":["LATEST_ONLY","SKIP_MISSED","ALL_WITH_LIMIT"],
+    "businessHold":"no blind retry; reason, owner, holdUntil and evidence required",
+    "idempotency":"operation:scope:scheduleVersion:scheduledForUtc"
+  },
+  "executionStates":["REQUESTED","RUNNING","SUCCEEDED","BUSINESS_HOLD","FAILED","QUARANTINED"],
+  "evaluationWindows":[1,5,20,63,126,252],
+  "automationBoundary": {
+    "allowed":["EVALUATION_ONLY","PROPOSAL_ONLY","DRILL_ONLY"],
+    "forbidden":["AUTO_PROMOTE","AUTO_ROLLBACK","AUTO_PARAMETER_CHANGE","AUTO_ORDER","KIS_SUBMISSION","CLIENT_PUBLICATION"]
+  },
+  "newOperation": {"operationCode":"J40","name":"EvaluationWindowIntegrityAudit","enabledByDefault":false,"mode":"EVALUATION_ONLY","gate":"G4"}
+}

contracts/ui/crud-page.v1.json

@@ -0,0 +1,9 @@
+{
+  "contractVersion": "crud-page.v1",
+  "stateOwners": {"server":"TanStack Query","form":"vee-validate + Zod","url":"vue-router","sessionAndUiPreference":"Pinia"},
+  "requiredRequestHeaders": ["Idempotency-Key for commands", "If-Match for updates where concurrency applies", "X-Correlation-Id"],
+  "requiredResponseMetadata": ["asOf", "projectionVersion", "stale", "watermark where applicable"],
+  "listQuery": ["page", "pageSize", "search", "sort[]", "filter[]"],
+  "failureStates": ["LOADING","EMPTY","WARN","ERROR","UNAUTHORIZED","FORBIDDEN","PARTIAL","DIRTY","CONFLICT","EXPIRED","READONLY","PROCESSING"],
+  "forbidden": ["server data duplicated in Pinia", "vendor grid state stored in domain feature", "silent overwrite after 409/412", "delete without reason and audit"]
+}

contracts/ui/crud-resource.v2.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "K-ArtSell CRUD Resource Contract v2",
+  "contractVersion": "2.0",
+  "required": [
+    "resourceId",
+    "querySchemaVersion",
+    "responseSchemaVersion",
+    "permissionPolicy",
+    "concurrencyMode",
+    "idempotencyMode",
+    "sensitiveFields"
+  ],
+  "properties": {
+    "concurrencyMode": {
+      "enum": [
+        "NONE",
+        "ETAG_IF_MATCH"
+      ]
+    },
+    "idempotencyMode": {
+      "enum": [
+        "NONE",
+        "IDEMPOTENCY_KEY"
+      ]
+    },
+    "queryOwnership": {
+      "const": "VUE_ROUTER"
+    },
+    "serverStateOwnership": {
+      "const": "TANSTACK_QUERY"
+    },
+    "formOwnership": {
+      "const": "VEE_VALIDATE_ZOD"
+    }
+  }
+}

contracts/ui/layout-regions.v1.json

@@ -0,0 +1,5 @@
+{
+  "contractVersion":"layout-regions.v1",
+  "regions":["Header","Summary","Filter","Main","SidePanel","ActionBar","AuditHelp"],
+  "rules":["one h1 per page","actions remain visible without covering content","evidence context is visible","responsive order follows task order","operation screens expose run status and watermark"]
+}

contracts/ui/screen-types.v2.json

@@ -0,0 +1,22 @@
+{
+  "contractVersion": "2.0",
+  "templates": [
+    { "id": "T01", "component": "SearchListCrudPage", "purpose": "search/list CRUD" },
+    { "id": "T02", "component": "DetailReadPage", "purpose": "read-only detail with evidence" },
+    { "id": "T03", "component": "EditFormPage", "purpose": "create/update form" },
+    { "id": "T04", "component": "MasterDetailCrudPage", "purpose": "master-detail CRUD" },
+    { "id": "T05", "component": "ApprovalWorkbenchPage", "purpose": "maker-checker review" },
+    { "id": "T06", "component": "StepWizardPage", "purpose": "multi-step workflow" },
+    { "id": "T07", "component": "ScorecardDashboardPage", "purpose": "dashboard and scorecard" },
+    { "id": "T08", "component": "BatchOperationsPageV2", "purpose": "batch and data operations" },
+    { "id": "T09", "component": "ReconciliationExceptionPage", "purpose": "reconciliation and correction" },
+    { "id": "T10", "component": "VersionGovernancePage", "purpose": "version comparison and governance" }
+  ],
+  "mandatoryCrossCutting": [
+    "loading/empty/warn/error/unauthorized/partial states",
+    "as-of and version evidence",
+    "permission boundary",
+    "correlation and audit link",
+    "responsive and keyboard operation"
+  ]
+}

contracts/ui/ui-adapter.v2.json

@@ -0,0 +1,16 @@
+{
+  "contractVersion": "2.0",
+  "requiredCapabilities": [
+    "button", "text-field", "text-area", "select", "checkbox",
+    "date-field", "number-field", "dialog", "status-tag", "data-grid"
+  ],
+  "providers": [
+    { "id": "primevue-aggrid", "productionEligible": true, "selection": "VITE_UI_ADAPTER=primevue" },
+    { "id": "native-accessible", "productionEligible": false, "selection": "VITE_UI_ADAPTER=native" }
+  ],
+  "featureImportRule": "Feature code imports only from @/shared/ui/components, @/shared/ui/layouts or @/shared/ui/screen-types.",
+  "replacementGate": [
+    "adapter contract tests", "accessibility keyboard tests", "visual regression",
+    "screen-state matrix", "large-list performance", "security review"
+  ]
+}

contracts/ui/ui-adapter.v3.json

@@ -0,0 +1,12 @@
+{
+  "contractVersion": "3.0",
+  "status": "CURRENT",
+  "principle": "Feature code depends on normalized K-ArtSell contracts, never vendor props or events.",
+  "requiredCapabilities": ["button","text-field","text-area","select","multi-select","checkbox","date-field","number-field","dialog","status-tag","inline-message","paginator","tabs","data-grid"],
+  "providers": [
+    {"id":"primevue-aggrid","productionEligible":true,"boundary":"frontend/src/shared/ui/adapter/primevue"},
+    {"id":"native-accessible","productionEligible":false,"purpose":"reference and contract conformance"}
+  ],
+  "forbidden": ["vendor import outside provider", "pass-through of unreviewed vendor props", "vendor-specific state in feature store", "silent fallback when capability is missing"],
+  "acceptance": ["contract conformance", "keyboard and label tests", "T01-T10 state matrix", "server paging and sorting contract", "visual regression", "accessibility review"]
+}

contracts/ui/ui-adapter.v4.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "K-ArtSell UI Adapter Contract v4",
+  "contractVersion": "4.0",
+  "status": "IMPLEMENTATION_TEMPLATE",
+  "requiredCapabilities": [
+    "button",
+    "text-field",
+    "text-area",
+    "select",
+    "multi-select",
+    "checkbox",
+    "date-field",
+    "number-field",
+    "dialog",
+    "status-tag",
+    "inline-message",
+    "paginator",
+    "tabs",
+    "data-grid"
+  ],
+  "requiredEvidence": [
+    "contract-conformance",
+    "keyboard-focus",
+    "accessible-name",
+    "t01-t10-state-regression",
+    "provider-switch-smoke",
+    "visual-regression",
+    "performance-budget",
+    "rollback-rehearsal"
+  ],
+  "rules": {
+    "featureVendorImports": 0,
+    "unknownCapability": "FAIL_FAST",
+    "unsupportedContract": "FAIL_FAST",
+    "providerSelection": "STARTUP_ONLY",
+    "mutableGlobalProviderSwitch": false,
+    "normalizedSemantics": [
+      "disabled",
+      "invalid",
+      "busy",
+      "aria-describedby",
+      "stable-events"
+    ]
+  }
+}