Squashed '.stage-pilot/' content from commit 2c0510c

git-subtree-dir: .stage-pilot git-subtree-split: 2c0510c68add43c50adcdedb30c174e68e730395
2026-06-03 08:56:02 +00:00
commit 9339d3d503
100 changed files with 8843 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Sample Host Project Interface Contract
+
+- Baseline Mode: declared
+- Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
+- Status: confirmed
+- Owner: Platform Team
+- Last Updated (KST): 2026-04-30 16:30
+- Source Discovery / Batch: bootstrap-baseline
+- Primary Runtime: api-service
+
+## Project Summary
+- Python-based API service for curated market data analysis.
+
+## Primary Domain
+- financial analytics
+
+## Purpose
+- This document captures the initial interface contract baseline after StagePilot bootstrap.
+- It provides a shared reference for future REQ, design, implementation, and verification work.
+
+## Scope
+- Covers the planned API and job interfaces exposed by the sample host project.
+- Does not duplicate detailed acceptance criteria or generated OpenAPI/schema artifacts.
+
+## Interface Summary
+
+- HTTP market data API :: serve curated market data and derived analytics to clients
+- Refresh job command :: update stored market data snapshots from upstream sources
+
+## Interface: `HTTP market data API`
+
+- Type: http-api
+- Consumers / Producers: internal dashboards and downstream service clients
+- Purpose: serve curated market data and derived analytics to clients
+- Stability: experimental
+
+### Inputs
+
+- `GET /markets/{symbol}` :: request the current curated snapshot for a symbol
+- `GET /analytics/{symbol}` :: request derived analytics for a symbol
+
+### Outputs
+
+- JSON market snapshot payload :: current normalized market data for the requested symbol
+- JSON analytics payload :: derived analytics and summary metrics for the requested symbol
+
+### Error Contract
+
+- `404 not_found` :: symbol is not available in the curated dataset
+- `503 upstream_unavailable` :: refreshed data is temporarily unavailable
+
+### Compatibility Rules
+
+- response payload changes should remain backward compatible within the same API version
+
+## Interface: `Refresh job command`
+
+- Type: cli
+- Consumers / Producers: operators and scheduled automation
+- Purpose: update stored market data snapshots from upstream sources
+- Stability: internal
+
+### Inputs
+
+- `python -m src.jobs.refresh_market_data` :: trigger a refresh of curated market data snapshots
+
+### Outputs
+
+- refreshed local snapshot artifacts :: normalized data persisted for later API reads
+
+### Error Contract
+
+- non-zero exit code :: refresh failed and data should be treated as stale
+
+### Compatibility Rules
+
+- command arguments and exit-code semantics should remain stable for automation callers
+
+## Shared Constraints
+
+- all interfaces assume symbol identifiers are validated before persistence or response rendering
+- refresh failures must not silently overwrite previously known-good snapshots
+
+## Current Gaps / Planned Changes
+
+- authentication and authorization rules are not defined yet
+- API versioning strategy is still undecided
+
+## Update Triggers
+
+- Update this document when an externally visible API, event, CLI, or file contract changes.
+- Update this document when a batch changes compatibility, validation, or error behavior.
+- Update this document when a new external consumer or producer is introduced.
+
+## Change Log
+
+- 2026-04-30: bootstrap-baseline created the initial interface contract baseline from declared project inputs.