feat(server): Phase 1-2: add runtime control version history

[lan17]

Summary

This is Phase 1 of the control lifecycle work. It takes control_versions from migration-only/backfill state into active runtime use by recording new version rows on control mutations and exposing version history through read APIs.

This PR is stacked on top of #172.
Please review it against feature/control-phase-0, not against main.

Design doc and implementation plan: https://gist.github.com/lan17/6a08282243576f096626bb10996c024b

What changed

The server now records a version row whenever a control is created, updated, patched, or soft-deleted. Those writes happen in the same transaction as the control mutation, so the live control row and its latest audit snapshot stay in sync.

To keep that logic in one place, this PR introduces a ControlService that owns active-control lookup, version creation, and version-history reads. The control endpoints now use that service instead of each path reaching into the database on its own, and the agent/policy association endpoints use the same service for active-control existence checks.

This PR also adds two version history endpoints:

• GET /api/v1/controls/{control_id}/versions
• GET /api/v1/controls/{control_id}/versions/{version_num}

Those endpoints follow the repo's cursor-pagination conventions. The list endpoint returns summaries only, while the detail endpoint returns the full stored snapshot for audit and diffing.

The shared API models, Python SDK wrapper, and generated TypeScript SDK were updated to match the new endpoints and response shapes.

Review follow-up

A review-loop pass found a concurrency hole in version number allocation and one misleading error mapping on PATCH /controls/{id}. This branch now serializes version creation with a row-level control lock and only reports CONTROL_NAME_CONFLICT for actual control-name uniqueness failures.

Why this shape

Phase 0 created the schema and backfilled history, but runtime writes still were not participating in version tracking. That left control_versions useful for migration cleanup, but not yet trustworthy as the live audit trail.

This PR closes that gap before the later store/clone work. It also establishes ControlService as the boundary for control persistence concerns, which keeps the next phase from duplicating versioning and lookup logic again.

Reviewer notes

The important areas to look at are:

• version-row creation on all control mutation paths
• ControlService transaction behavior, row locking, and snapshot shape
• version history endpoint pagination and deleted-control behavior
• the shared-model / SDK surface added for version-history reads

Validation

• make check
• make openapi-spec-check
• make sdk-ts-generate
• make sdk-ts-overlay-test
• make sdk-ts-name-check
• targeted server slice for control/version endpoints
• targeted Python SDK controls wrapper slice

[codecov]

Codecov Report

❌ Patch coverage is 98.86040% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	96.87%	2 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	99.14%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

Summary

This is Phase 1 of the control lifecycle work. It takes control_versions from migration-only/backfill state into active runtime use by recording new version rows on control mutations and exposing version history through read APIs.

This PR is stacked on top of #172.
Please review it against feature/control-phase-0, not against main.

Design doc and implementation plan: https://gist.github.com/lan17/6a08282243576f096626bb10996c024b

What changed

The server now records a version row whenever a control is created, updated, patched, or soft-deleted. Those writes happen in the same transaction as the control mutation, so the live control row and its latest audit snapshot stay in sync.

To keep that logic in one place, this PR introduces a ControlService that owns active-control lookup, version creation, and version-history reads. The control endpoints now use that service instead of each path reaching into the database on its own, and the agent/policy association endpoints use the same service for active-control existence checks.

This PR also adds two version history endpoints:

• GET /api/v1/controls/{control_id}/versions
• GET /api/v1/controls/{control_id}/versions/{version_num}

Those endpoints follow the repo's cursor-pagination conventions. The list endpoint returns summaries only, while the detail endpoint returns the full stored snapshot for audit and diffing.

The shared API models, Python SDK wrapper, and generated TypeScript SDK were updated to match the new endpoints and response shapes.

Review follow-up

A review-loop pass found a concurrency hole in version number allocation and one misleading error mapping on PATCH /controls/{id}. This branch now serializes version creation with a row-level control lock and only reports CONTROL_NAME_CONFLICT for actual control-name uniqueness failures.

Why this shape

Phase 0 created the schema and backfilled history, but runtime writes still were not participating in version tracking. That left control_versions useful for migration cleanup, but not yet trustworthy as the live audit trail.

This PR closes that gap before the later store/clone work. It also establishes ControlService as the boundary for control persistence concerns, which keeps the next phase from duplicating versioning and lookup logic again.

Reviewer notes

The important areas to look at are:

• version-row creation on all control mutation paths
• ControlService transaction behavior, row locking, and snapshot shape
• version history endpoint pagination and deleted-control behavior
• the shared-model / SDK surface added for version-history reads

Validation

• make check
• make openapi-spec-check
• make sdk-ts-generate
• make sdk-ts-overlay-test
• make sdk-ts-name-check
• targeted server slice for control/version endpoints
• targeted Python SDK controls wrapper slice

[codecov]

Codecov Report

❌ Patch coverage is 98.86040% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	96.87%	2 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	99.14%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

Summary

This is Phase 1 of the control lifecycle work. It takes control_versions from migration-only/backfill state into active runtime use by recording new version rows on control mutations and exposing version history through read APIs.

This PR is stacked on top of #172.
Please review it against feature/control-phase-0, not against main.

Design doc and implementation plan: https://gist.github.com/lan17/6a08282243576f096626bb10996c024b

What changed

The server now records a version row whenever a control is created, updated, patched, or soft-deleted. Those writes happen in the same transaction as the control mutation, so the live control row and its latest audit snapshot stay in sync.

To keep that logic in one place, this PR introduces a ControlService that owns active-control lookup, version creation, and version-history reads. The control endpoints now use that service instead of each path reaching into the database on its own, and the agent/policy association endpoints use the same service for active-control existence checks.

This PR also adds two version history endpoints:

• GET /api/v1/controls/{control_id}/versions
• GET /api/v1/controls/{control_id}/versions/{version_num}

Those endpoints follow the repo's cursor-pagination conventions. The list endpoint returns summaries only, while the detail endpoint returns the full stored snapshot for audit and diffing.

The shared API models, Python SDK wrapper, and generated TypeScript SDK were updated to match the new endpoints and response shapes.

Review follow-up

A review-loop pass found a concurrency hole in version number allocation and one misleading error mapping on PATCH /controls/{id}. This branch now serializes version creation with a row-level control lock and only reports CONTROL_NAME_CONFLICT for actual control-name uniqueness failures.

Why this shape

Phase 0 created the schema and backfilled history, but runtime writes still were not participating in version tracking. That left control_versions useful for migration cleanup, but not yet trustworthy as the live audit trail.

This PR closes that gap before the later store/clone work. It also establishes ControlService as the boundary for control persistence concerns, which keeps the next phase from duplicating versioning and lookup logic again.

Reviewer notes

The important areas to look at are:

• version-row creation on all control mutation paths
• ControlService transaction behavior, row locking, and snapshot shape
• version history endpoint pagination and deleted-control behavior
• the shared-model / SDK surface added for version-history reads

Validation

• make check
• make openapi-spec-check
• make sdk-ts-generate
• make sdk-ts-overlay-test
• make sdk-ts-name-check
• targeted server slice for control/version endpoints
• targeted Python SDK controls wrapper slice

[codecov]

Codecov Report

❌ Patch coverage is 98.86040% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	96.87%	2 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	99.14%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

Summary

This is Phase 1 of the control lifecycle work. It takes control_versions from migration-only/backfill state into active runtime use by recording new version rows on control mutations and exposing version history through read APIs.

This PR is stacked on top of #172.
Please review it against feature/control-phase-0, not against main.

Design doc and implementation plan: https://gist.github.com/lan17/6a08282243576f096626bb10996c024b

What changed

The server now records a version row whenever a control is created, updated, patched, or soft-deleted. Those writes happen in the same transaction as the control mutation, so the live control row and its latest audit snapshot stay in sync.

To keep that logic in one place, this PR introduces a ControlService that owns active-control lookup, version creation, and version-history reads. The control endpoints now use that service instead of each path reaching into the database on its own, and the agent/policy association endpoints use the same service for active-control existence checks.

This PR also adds two version history endpoints:

• GET /api/v1/controls/{control_id}/versions
• GET /api/v1/controls/{control_id}/versions/{version_num}

Those endpoints follow the repo's cursor-pagination conventions. The list endpoint returns summaries only, while the detail endpoint returns the full stored snapshot for audit and diffing.

The shared API models, Python SDK wrapper, and generated TypeScript SDK were updated to match the new endpoints and response shapes.

Review follow-up

A review-loop pass found a concurrency hole in version number allocation and one misleading error mapping on PATCH /controls/{id}. This branch now serializes version creation with a row-level control lock and only reports CONTROL_NAME_CONFLICT for actual control-name uniqueness failures.

Why this shape

Phase 0 created the schema and backfilled history, but runtime writes still were not participating in version tracking. That left control_versions useful for migration cleanup, but not yet trustworthy as the live audit trail.

This PR closes that gap before the later store/clone work. It also establishes ControlService as the boundary for control persistence concerns, which keeps the next phase from duplicating versioning and lookup logic again.

Reviewer notes

The important areas to look at are:

• version-row creation on all control mutation paths
• ControlService transaction behavior, row locking, and snapshot shape
• version history endpoint pagination and deleted-control behavior
• the shared-model / SDK surface added for version-history reads

Validation

• make check
• make openapi-spec-check
• make sdk-ts-generate
• make sdk-ts-overlay-test
• make sdk-ts-name-check
• targeted server slice for control/version endpoints
• targeted Python SDK controls wrapper slice

[codecov]

Codecov Report

❌ Patch coverage is 98.86040% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	96.87%	2 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	99.14%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

Summary

This is Phase 1 of the control lifecycle work. It takes control_versions from migration-only/backfill state into active runtime use by recording new version rows on control mutations and exposing version history through read APIs.

This PR is stacked on top of #172.
Please review it against feature/control-phase-0, not against main.

Design doc and implementation plan: https://gist.github.com/lan17/6a08282243576f096626bb10996c024b

What changed

The server now records a version row whenever a control is created, updated, patched, or soft-deleted. Those writes happen in the same transaction as the control mutation, so the live control row and its latest audit snapshot stay in sync.

To keep that logic in one place, this PR introduces a ControlService that owns active-control lookup, version creation, and version-history reads. The control endpoints now use that service instead of each path reaching into the database on its own, and the agent/policy association endpoints use the same service for active-control existence checks.

This PR also adds two version history endpoints:

• GET /api/v1/controls/{control_id}/versions
• GET /api/v1/controls/{control_id}/versions/{version_num}

Those endpoints follow the repo's cursor-pagination conventions. The list endpoint returns summaries only, while the detail endpoint returns the full stored snapshot for audit and diffing.

The shared API models, Python SDK wrapper, and generated TypeScript SDK were updated to match the new endpoints and response shapes.

Review follow-up

A review-loop pass found a concurrency hole in version number allocation and one misleading error mapping on PATCH /controls/{id}. This branch now serializes version creation with a row-level control lock and only reports CONTROL_NAME_CONFLICT for actual control-name uniqueness failures.

Why this shape

Phase 0 created the schema and backfilled history, but runtime writes still were not participating in version tracking. That left control_versions useful for migration cleanup, but not yet trustworthy as the live audit trail.

This PR closes that gap before the later store/clone work. It also establishes ControlService as the boundary for control persistence concerns, which keeps the next phase from duplicating versioning and lookup logic again.

Reviewer notes

The important areas to look at are:

• version-row creation on all control mutation paths
• ControlService transaction behavior, row locking, and snapshot shape
• version history endpoint pagination and deleted-control behavior
• the shared-model / SDK surface added for version-history reads

Validation

• make check
• make openapi-spec-check
• make sdk-ts-generate
• make sdk-ts-overlay-test
• make sdk-ts-name-check
• targeted server slice for control/version endpoints
• targeted Python SDK controls wrapper slice

[codecov]

Codecov Report

❌ Patch coverage is 98.86040% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	96.87%	2 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	99.14%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

Summary

This is Phase 1 of the control lifecycle work. It takes control_versions from migration-only/backfill state into active runtime use by recording new version rows on control mutations and exposing version history through read APIs.

This PR is stacked on top of #172.
Please review it against feature/control-phase-0, not against main.

Design doc and implementation plan: https://gist.github.com/lan17/6a08282243576f096626bb10996c024b

What changed

The server now records a version row whenever a control is created, updated, patched, or soft-deleted. Those writes happen in the same transaction as the control mutation, so the live control row and its latest audit snapshot stay in sync.

To keep that logic in one place, this PR introduces a ControlService that owns active-control lookup, version creation, and version-history reads. The control endpoints now use that service instead of each path reaching into the database on its own, and the agent/policy association endpoints use the same service for active-control existence checks.

This PR also adds two version history endpoints:

• GET /api/v1/controls/{control_id}/versions
• GET /api/v1/controls/{control_id}/versions/{version_num}

Those endpoints follow the repo's cursor-pagination conventions. The list endpoint returns summaries only, while the detail endpoint returns the full stored snapshot for audit and diffing.

The shared API models, Python SDK wrapper, and generated TypeScript SDK were updated to match the new endpoints and response shapes.

Review follow-up

A review-loop pass found a concurrency hole in version number allocation and one misleading error mapping on PATCH /controls/{id}. This branch now serializes version creation with a row-level control lock and only reports CONTROL_NAME_CONFLICT for actual control-name uniqueness failures.

Why this shape

Phase 0 created the schema and backfilled history, but runtime writes still were not participating in version tracking. That left control_versions useful for migration cleanup, but not yet trustworthy as the live audit trail.

This PR closes that gap before the later store/clone work. It also establishes ControlService as the boundary for control persistence concerns, which keeps the next phase from duplicating versioning and lookup logic again.

Reviewer notes

The important areas to look at are:

• version-row creation on all control mutation paths
• ControlService transaction behavior, row locking, and snapshot shape
• version history endpoint pagination and deleted-control behavior
• the shared-model / SDK surface added for version-history reads

Validation

• make check
• make openapi-spec-check
• make sdk-ts-generate
• make sdk-ts-overlay-test
• make sdk-ts-name-check
• targeted server slice for control/version endpoints
• targeted Python SDK controls wrapper slice

[codecov]

Codecov Report

❌ Patch coverage is 98.86040% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	96.87%	2 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	99.14%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

Summary

This is Phase 1 of the control lifecycle work. It takes control_versions from migration-only/backfill state into active runtime use by recording new version rows on control mutations and exposing version history through read APIs.

This PR is stacked on top of #172.
Please review it against feature/control-phase-0, not against main.

Design doc and implementation plan: https://gist.github.com/lan17/6a08282243576f096626bb10996c024b

What changed

The server now records a version row whenever a control is created, updated, patched, or soft-deleted. Those writes happen in the same transaction as the control mutation, so the live control row and its latest audit snapshot stay in sync.

To keep that logic in one place, this PR introduces a ControlService that owns active-control lookup, version creation, and version-history reads. The control endpoints now use that service instead of each path reaching into the database on its own, and the agent/policy association endpoints use the same service for active-control existence checks.

This PR also adds two version history endpoints:

• GET /api/v1/controls/{control_id}/versions
• GET /api/v1/controls/{control_id}/versions/{version_num}

Those endpoints follow the repo's cursor-pagination conventions. The list endpoint returns summaries only, while the detail endpoint returns the full stored snapshot for audit and diffing.

The shared API models, Python SDK wrapper, and generated TypeScript SDK were updated to match the new endpoints and response shapes.

Review follow-up

A review-loop pass found a concurrency hole in version number allocation and one misleading error mapping on PATCH /controls/{id}. This branch now serializes version creation with a row-level control lock and only reports CONTROL_NAME_CONFLICT for actual control-name uniqueness failures.

Why this shape

Phase 0 created the schema and backfilled history, but runtime writes still were not participating in version tracking. That left control_versions useful for migration cleanup, but not yet trustworthy as the live audit trail.

This PR closes that gap before the later store/clone work. It also establishes ControlService as the boundary for control persistence concerns, which keeps the next phase from duplicating versioning and lookup logic again.

Reviewer notes

The important areas to look at are:

• version-row creation on all control mutation paths
• ControlService transaction behavior, row locking, and snapshot shape
• version history endpoint pagination and deleted-control behavior
• the shared-model / SDK surface added for version-history reads

Validation

• make check
• make openapi-spec-check
• make sdk-ts-generate
• make sdk-ts-overlay-test
• make sdk-ts-name-check
• targeted server slice for control/version endpoints
• targeted Python SDK controls wrapper slice

[codecov]

Codecov Report

❌ Patch coverage is 98.86040% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	96.87%	2 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	99.14%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

Summary

This is Phase 1 of the control lifecycle work. It takes control_versions from migration-only/backfill state into active runtime use by recording new version rows on control mutations and exposing version history through read APIs.

This PR is stacked on top of #172.
Please review it against feature/control-phase-0, not against main.

Design doc and implementation plan: https://gist.github.com/lan17/6a08282243576f096626bb10996c024b

What changed

The server now records a version row whenever a control is created, updated, patched, or soft-deleted. Those writes happen in the same transaction as the control mutation, so the live control row and its latest audit snapshot stay in sync.

To keep that logic in one place, this PR introduces a ControlService that owns active-control lookup, version creation, and version-history reads. The control endpoints now use that service instead of each path reaching into the database on its own, and the agent/policy association endpoints use the same service for active-control existence checks.

This PR also adds two version history endpoints:

• GET /api/v1/controls/{control_id}/versions
• GET /api/v1/controls/{control_id}/versions/{version_num}

Those endpoints follow the repo's cursor-pagination conventions. The list endpoint returns summaries only, while the detail endpoint returns the full stored snapshot for audit and diffing.

The shared API models, Python SDK wrapper, and generated TypeScript SDK were updated to match the new endpoints and response shapes.

Review follow-up

A review-loop pass found a concurrency hole in version number allocation and one misleading error mapping on PATCH /controls/{id}. This branch now serializes version creation with a row-level control lock and only reports CONTROL_NAME_CONFLICT for actual control-name uniqueness failures.

Why this shape

Phase 0 created the schema and backfilled history, but runtime writes still were not participating in version tracking. That left control_versions useful for migration cleanup, but not yet trustworthy as the live audit trail.

This PR closes that gap before the later store/clone work. It also establishes ControlService as the boundary for control persistence concerns, which keeps the next phase from duplicating versioning and lookup logic again.

Reviewer notes

The important areas to look at are:

• version-row creation on all control mutation paths
• ControlService transaction behavior, row locking, and snapshot shape
• version history endpoint pagination and deleted-control behavior
• the shared-model / SDK surface added for version-history reads

Validation

• make check
• make openapi-spec-check
• make sdk-ts-generate
• make sdk-ts-overlay-test
• make sdk-ts-name-check
• targeted server slice for control/version endpoints
• targeted Python SDK controls wrapper slice

[codecov]

Codecov Report

❌ Patch coverage is 98.86040% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	96.87%	2 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	99.14%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!