Skip to content

docs: fix schema link and expand storage/ledger reference#16

Merged
Gsbreddy merged 1 commit into
mainfrom
cursor/documentation-automation-system-34fc
May 2, 2026
Merged

docs: fix schema link and expand storage/ledger reference#16
Gsbreddy merged 1 commit into
mainfrom
cursor/documentation-automation-system-34fc

Conversation

@cursor
Copy link
Copy Markdown

@cursor cursor Bot commented May 2, 2026

Docs added/updated

docs/release-artifact.md

  • Fixed broken JSON Schema link: schemas/v1/release_artifact.schema.jsonschemas/v1/release.schema.json (the file that actually exists in the repo; caught by comparing the doc link against ls schemas/v1/).

docs/operations-and-policy.md

  • SQLite table list corrected: Added the missing pricing_import_audit table (7 tables, not 5/6).
  • Storage connection settings: Documents the four SQLite pragmas (WAL, IMMEDIATE, busy_timeout=5000, foreign_keys=ON) and why BEGIN IMMEDIATE is used for promotion and pricing-import transactions.
  • Idempotent run event ingestion: Explains the per-row insert loop, run_id PRIMARY KEY deduplication, safe re-ingest semantics, and what the return value represents.
  • Schema migration table: Documents versions 1–3 (initial schema, run_events index, audit_seq column/backfill) and guidance for future migrations.
  • Rollup semantics section: Covers how runs, cost_per_run_usd, latency_ms_avg, and error_rate are computed; clarifies run_start vs run_end event counting; explains latency_ms_avg = None (not zero) and the policy skip; documents the delta_cost_per_run_pct and delta_latency_ms_avg None guards.
  • Active policy upsert behavior: Documents the INSERT … ON CONFLICT DO UPDATE single-row semantics and get_active_policy tie-breaking by updated_at.

Which codepaths these cover

Doc change Source file
Schema link fix schemas/v1/release.schema.json
Storage pragmas / transactions src/flightdeck/storage.py (_configure_connection, transaction)
Idempotent ingest src/flightdeck/storage.py (insert_run_events)
Schema migration table src/flightdeck/storage.py (migrate, LATEST_SCHEMA_MIGRATION_VERSION)
Rollup semantics src/flightdeck/ledger.py (compute_rollup, diff_releases, DiffResult)
Active policy upsert src/flightdeck/storage.py (set_active_policy, get_active_policy)

Key knowledge gaps addressed

  1. Broken link — the release artifact JSON Schema link pointed to a non-existent file name.
  2. Missing tablepricing_import_audit was documented in the release-artifact doc but absent from the storage schema table in operations-and-policy.
  3. Transaction modelBEGIN IMMEDIATE and WAL pragmas were undocumented; relevant to anyone debugging SQLITE_BUSY errors or concurrent access.
  4. Idempotent ingest — the safe re-ingest guarantee was only visible in source code; operators need to know re-running runs ingest is harmless.
  5. Rollup event counting — whether run_start events are counted was not documented; latency/delta None vs 0 distinction was missing.
  6. Active policy ambiguity — behavior when multiple policy_id values exist was undocumented.
Open in Web View Automation 

- Fix broken JSON Schema link in release-artifact.md:
  release_artifact.schema.json -> release.schema.json (actual file name)

- Add pricing_import_audit to the SQLite table list in
  operations-and-policy.md (7 tables, not 5)

- Document Storage connection settings (WAL, IMMEDIATE transactions,
  busy_timeout, foreign_keys pragma)

- Document idempotent run event ingestion: run_id PRIMARY KEY
  deduplication, per-row insert loop, safe re-ingestion semantics

- Document schema migration versions 1-3 with change summary and
  guidance for adding future migrations

- Add Rollup semantics section: how runs/cost/latency/error_rate are
  computed, run_start vs run_end event counting, latency_ms_avg=None
  meaning, delta_cost_per_run_pct and delta_latency_ms_avg None guards

- Document active_policy single-row upsert behavior and
  get_active_policy tie-breaking on updated_at

Co-authored-by: Gottam Sai Bharath <Gsbreddy@users.noreply.github.com>
@Gsbreddy Gsbreddy marked this pull request as ready for review May 2, 2026 11:00
@Gsbreddy Gsbreddy merged commit 2bc535b into main May 2, 2026
2 checks passed
@Gsbreddy Gsbreddy deleted the cursor/documentation-automation-system-34fc branch May 2, 2026 11:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants