Operations

AlphaPreview ContractVerification Required

Concordia validation runbooks.

Concordia validation runbooks for Cache, Gateway, Storage, Time Series, active compatibility, protocol fixtures, validation scripts, and evidence handoff boundaries.

Current availability

Private Beta. Public beta is scheduled for December 7, 2026.

Runbook Snapshot

Runbooks: 8
First checks: 10
Triage entries: 23
Review state: Pending

Runbook Summary

Concordia validation runbook coverage
Runbook	Primary command or route	Proves	Does not prove	Evidence
Cache local validation	./Support/Validate-Local.sh and Cache quickstart commands	Local Cache health, local bearer-token admission, put/get/count, placement, and restart load.	Production identity, shared storage, distributed routing, replication, availability, support, performance, scale, or GA.	CONC-EVID-002 through 008
Time Series local validation	./Support/Validate-TSDB-Local.sh	Local health, protected sample append, recent query, newest-first order, and retention limit.	Durable TSDB storage, projection freshness, cross-node replication, production auth, or abuse/rate-limit enforcement.	CONC-EVID-009, CONC-EVID-011
Gateway alpha validation	./Support/Validate-Gateway-Diagnostics-Smoke.sh and ./Support/Validate-Gateway-Alpha-Route-Smoke.sh	Readiness blockers, fixture-backed placement, local auth, idempotency, and diagnostic accept.	Quorum commit, visible reads, TCP owner forwarding, external metadata watches, restart recovery, or cross-node routing.	CONC-EVID-010, CONC-EVID-011
Storage startup validation	./Support/Validate-Storage-Product-Startup.sh	Dry-run, require-ready, fail-closed blockers, and loopback boundary modes.	General Storage serving, broad write-frame handling, repair execution, shared storage, or customer data durability.	CONC-EVID-011, CONC-EVID-012
Active compatibility validation	./Support/Validate-SingleNode.sh	Active service HTTP/TCP compatibility on node 1 and active frame handling.	Product-binary parity, persistent state, multi-node availability, production auth, or future protocol frame support.	CONC-EVID-011, CONC-EVID-012
Protocol fixture validation	./Support/Validate-Replica-Append-Protocol-Fixtures.sh and focused C# binary utility tests	Active fixture bytes and reserved replica append fixture compatibility.	Runtime support for future frame IDs, listener coverage for every allocated ID, or customer-facing protocol availability.	CONC-EVID-011, CONC-EVID-012
Alpha evidence helpers	./Support/Validate-Alpha-Gates.sh and ./Support/Generate-Alpha-Evidence-Packet.sh	Runnable local gate summary and review packet scaffolding.	Full local implementation validation, planned gate completion, alpha release readiness, packaging, deploy, or rollback.	Alpha validation matrix
Documentation claim validation	./Support/Validate-Documentation-Claims.sh and docs repo claim lint	Claim-sensitive wording has nearby limits or evidence.	Product SME acceptance, legal approval, security approval, or runtime behavior not already in sources.	DOCS-041, DOCS-042

Local Setup

Run validation commands from the Service.Concordia repository root and use loopback ports plus disposable local paths only.

cd /path/to/Service.Concordia
cargo --version
dotnet --version
curl --version

First Checks

Full local validation

Validation

./Support/Validate-Local.sh

Expected signal

Formatting, compile, Rust tests, docs claim checks, TSDB local checks, C# utility tests, and Cache smoke pass.

Capture: Command, exit code, Service.Concordia commit SHA, override ports, and failing subsection when nonzero.

Runnable alpha gate summary

Validation

./Support/Validate-Alpha-Gates.sh

Expected signal

Executable local alpha evidence reports pass or names blocked gates.

Capture: Gate IDs, command output, unresolved risk, owner, and sign-off state.

Cache focused tests

Validation

cargo test --manifest-path Cargo.toml -p concordia-cache -p concordia-cache-bin

Expected signal

Cache crate and binary tests pass.

Capture: Test command, test count, and any auth, TTL, placement, or persistence failure text.

TSDB focused validation

Validation

./Support/Validate-TSDB-Local.sh

Expected signal

TSDB model, binary routes, CLI tests, docs claim scan, and local-only evidence checks pass.

Capture: Test command, local-only limit lines, retention setting, and failing filter if any.

Gateway diagnostics smoke

Validation

./Support/Validate-Gateway-Diagnostics-Smoke.sh

Expected signal

Default Gateway diagnostics report disabled write behavior and readiness blockers.

Capture: Bind address, health response, placement response, blocker list, and disabled-write response.

Gateway alpha smoke

Validation

./Support/Validate-Gateway-Alpha-Route-Smoke.sh

Expected signal

Alpha-ready Gateway reports no blockers and one protected write returns diagnostic accepted output.

Capture: Fixture path, bind address, auth/idempotency checks, status, record hash shape, and diagnostic flags.

Storage startup validation

Validation

./Support/Validate-Storage-Product-Startup.sh

Expected signal

Dry-run, require-ready, listener-bind, process-frame rejection, and owner-write boundary tests pass.

Capture: Startup report, blockers, socket and mutation booleans, loopback bind overrides, and failed focused test.

Active single-node harness

Validation

./Support/Validate-SingleNode.sh

Expected signal

Node 1 starts, /status responds, and C# endpoint tests pass.

Capture: HTTP base URL, TCP host/port, test count, route or frame failure, and active node log tail.

Protocol fixture check

Validation

dotnet test AutomatedTests/Stornamics.Service.Concordia.AutomatedTests.sln --filter FullyQualifiedName~AutomatedTests.UnitTests.MessageUtilityTests

Expected signal

C# binary utility tests pass.

Capture: Test count, fixture name, decoded values, and parser error if any.

Docs claim check

Validation

./Support/Validate-Documentation-Claims.sh README.md docs/LOCAL_RUNBOOK.md docs/planning/ALPHA_VALIDATION_MATRIX.md

Expected signal

Claim-sensitive wording has evidence or limiting context.

Capture: File, line, claim term, nearby limit text, and owner for any waiver.

Cache Validation Triage

Concordia Cache validation triage
Symptom	Likely cause	First check	Remediation
Cache smoke cannot bind	The selected loopback port is already in use or not loopback.	Check CONCORDIA_CACHE_SMOKE_BIND_ADDR and service logs.	Choose another loopback override and rerun the script.
Protected route stays rejected	Bearer token is missing or not local-cache-token.	Capture request headers and missing_authorization body.	Set the local token for protected routes; do not infer production identity behavior.
Stale write is accepted	The newer version write did not run first or the key differs.	Compare key, crdt_version, and response outcome.	Re-run the documented version sequence against a clean local service.
Restart reload fails	The process restarted with a different persistence path or file.	Compare --persistence-path values before and after.	Restart with the same tutorial-scoped file before cleanup.
Placement implies routing	routing_enabled:false was misread as a routing proof.	Inspect placement response fields.	Record placement as local diagnostics only; keep owner forwarding and cross-node routing blocked.

Time Series Validation Triage

Concordia Time Series validation triage
Symptom	Likely cause	First check	Remediation
TSDB protected route rejects	Bearer token is missing or not local-tsdb-token.	Capture status and response body.	Retry with the local token and keep the result scoped to local admission.
Recent query returns no series	Tenant, dataset, series name, or tags do not match appended sample.	Compare the append payload and query body.	Reuse the exact identity fields from the tutorial or focused script.
Retention evidence drifts	--retention-max-records or sample count differs.	Capture health and retained record count.	Rerun with the intended retention value and record newest-first timestamps.
Docs imply durable TSDB	Limit wording is missing near durability or replication terms.	Run Validate-Documentation-Claims.sh on TSDB docs.	Add local-memory-only wording before asking docs QA to approve the claim.

Gateway Validation Triage

Concordia Gateway validation triage
Symptom	Likely cause	First check	Remediation
Gateway health stays blocked	One alpha-ready flag or fixture input is missing.	Capture alpha_write_blockers and startup args.	Restart with explicit write mode, in-process owner transport, metadata fixture, retry budget, and quota.
Placement metadata is unavailable	Fixture path is wrong or metadata fallback failed closed.	Check fixture path, metadata version, and fallback decision.	Run from the Service.Concordia root and use fixtures/metadata/placement-alpha-v2.txt.
Write returns missing idempotency	Idempotency-Key header is omitted.	Compare headers and request body.	Send the header and keep it equal to the optional body idempotency key.
Disabled write response appears	The service is still running in default write-disabled mode.	Check health for writes_enabled:false.	Stop the disabled-mode process and restart with the alpha-ready command.
Accepted output is overclaimed	Diagnostic flags were omitted from evidence or summary wording.	Check committed:false, visible:false, and diagnostic_only:true.	Keep the evidence label diagnostic; do not claim quorum, visible reads, or cross-node routing.

Storage Validation Triage

Concordia Storage validation triage
Symptom	Likely cause	First check	Remediation
Dry-run reports blocked	Replica transport or replica targets are disabled by default.	Capture status=blocked and blocker list.	Treat default blocked output as expected fail-closed evidence.
Require-ready exits nonzero	Required startup evidence is missing.	Capture stdout and stderr.	Add the explicit in-process transport and replica target settings only for the reviewed local check.
Listener boundary fails	Bind address is occupied or not loopback.	Check the requested bind address.	Use an unused loopback override and rerun the specific boundary command.
Process-frame boundary mutates	Boundary output no longer reports no mutation or no committed claim.	Inspect mutates_storage and committed_visibility_claim.	Preserve output and route to Storage owner review before retrying.
Owner-write boundary overclaims	Local owner acknowledgement is treated as quorum or visible behavior.	Check follower-frame and committed labels.	Keep owner-write evidence local and uncommitted until quorum evidence is separately accepted.

Active Compatibility And Protocol Triage

Concordia active compatibility and protocol triage
Symptom	Likely cause	First check	Remediation
Active harness refuses start	Another service is already responding at http://localhost:9001.	Check the preflight response and active node log.	Stop the unrelated local process or rerun later; do not test against an unknown service.
Endpoint tests fail to restore	NuGet source or network access is unavailable.	Capture restore warnings and package source.	Rerun when package sources are reachable or use restored packages with the documented skip flag.
TCP frame test fails	Active binary frame bytes, parser, or port routing drifted.	Capture the failing C# endpoint test and TCP settings.	Preserve frame evidence and route to active service and protocol owners.
Future frame treated as live	Registry allocation was confused with runtime listener support.	Check the protocol registry row and compatibility page.	Keep future frame IDs labeled future until parser, serializer, route, listener, and evidence land.

Evidence Handoff

Command Identity

Capture script name, command line, working directory, commit SHA, branch, host OS, timestamp, and any port overrides.

Runtime Output

Keep health JSON, readiness blockers, status codes, reason codes, retention counts, and diagnostic flags; redact tokens, keys, values, tenants, and datasets.

Boundary Flags

Record socket, mutation, write-frame, follower-frame, committed, visible, and diagnostic booleans before rerunning a Storage or Gateway check.

Evidence

DOCS-053 evidence map
Runbook area	Evidence	Status
Cache local validation	DOCS-025, CONC-EVID-002 through CONC-EVID-008	pending
TSDB and Gateway validation	DOCS-026, CONC-EVID-009, CONC-EVID-010	pending
Runtime and compatibility map	DOCS-035, DOCS-041, CONC-EVID-011, CONC-EVID-012	pending
Limits and review boundaries	DOCS-042, CONC-EVID-013	pending
Validation runbook artifact	DOCS-053 and /products/concordia/operations/validation-runbooks/	pending

Internal review records track this Concordia validation runbook page and its evidence handoff requirements.

Validation Limits

No Production Readiness Claim

Passing these checks does not approve production identity, shared storage, distributed routing, support posture, release readiness, or GA wording.

Gateway Accepted Is Diagnostic

Accepted Gateway alpha output stays diagnostic when it reports committed:false, visible:false, and diagnostic_only:true.

Storage Flags Are Evidence Modes

Storage startup and local-alpha flags are narrow validation surfaces, not general serving behavior.

Safe Next Steps

Available: DOCS-035
Read runtime reference
Use command, route, auth, response, error, maturity, and evidence details before changing a validation step.
Available: DOCS-041
Map runtime boundaries
Check whether a result is supported, partial, unsupported, preview, future, or verification-required.
Available: DOCS-042
Read known limits
Keep local bearer tokens, Gateway diagnostics, Storage flags, protocol frames, and Edge Workflows in their current boundary.
Available
Review Concordia evidence
Use CONC evidence records before strengthening validation, support, security, routing, Storage, protocol, or readiness wording.