From 74ebee36a832198428547442fa897f270decf8ab Mon Sep 17 00:00:00 2001 From: wutongyuonce <147830929+wutongyuonce@users.noreply.github.com> Date: Sun, 27 Sep 2026 20:12:46 +0800 Subject: [PATCH 1/8] feat(server): add protocol discovery identity --- .../remote-access-implementation.md | 33 +++++ .../remote-access-implementation.md | 31 +++++ .../powercontext/src/operations.generated.ts | 1 + .../powercontext/src/operations.generated.ts | 1 + .../powercontext/src/operations.generated.ts | 1 + openapi/powercontext.yaml | 90 ++++++++++++- src/powercontext/client/client.py | 7 + src/powercontext/http/__init__.py | 6 + src/powercontext/http/_generated/models.py | 36 ++++++ .../http/_generated/operations.py | 27 +++- src/powercontext/http/_generated/schema.py | 120 +++++++++++++++++- src/powercontext/server/app.py | 11 ++ src/powercontext/server/cli.py | 27 ++++ src/powercontext/server/factory.py | 6 + src/powercontext/server/identity.py | 114 +++++++++++++++++ src/powercontext/server/info.py | 57 +++++++++ tests/test_api_contract.py | 53 ++++++++ tests/test_cli.py | 21 +++ tests/test_client.py | 32 +++++ tests/test_server.py | 56 ++++++++ tests/test_server_identity.py | 77 +++++++++++ 21 files changed, 804 insertions(+), 3 deletions(-) create mode 100644 src/powercontext/server/identity.py create mode 100644 src/powercontext/server/info.py create mode 100644 tests/test_server_identity.py diff --git a/docs/en/development/remote-access-implementation.md b/docs/en/development/remote-access-implementation.md index 387ed1e0e9..e7c1cd3235 100644 --- a/docs/en/development/remote-access-implementation.md +++ b/docs/en/development/remote-access-implementation.md @@ -87,6 +87,7 @@ The source contract is `openapi/powercontext.yaml`. Generated Pydantic models an | Area | Operations | | --- | --- | | Health | liveness and readiness | +| Server discovery | stable deployment identity and protocol contracts | | Capabilities | source types, Artifact families, extraction, search modes | | Sources | capture durable content evidence | | Memory | flush pending Sources, remember explicit entries, search | @@ -100,6 +101,36 @@ Server errors use the OpenAPI error schema and include a Server-owned `X-PowerCo derived from the inbound request span. Validation errors, revision conflicts, missing entries, unavailable inference, and internal failures map to stable HTTP status codes. +### Server identity and compatibility discovery + +`GET /v1/server-info` is protected by `server.observe` and returns the stable deployment `server_id`, installed package +version, API contract version, response schema version, and initial feature contracts. It deliberately does not report +health, enabled runtime capabilities, limits, inventory, secrets, filesystem paths, or the authenticated principal. +Use the dedicated health, capabilities, statistics, and access endpoints for those concerns. + +All discovery versions use `major` and `minor` integers. A major increment may remove or incompatibly change the +governed contract; a minor increment is backward compatible. The response `schema_version` governs its fields and +semantics, while `api_contract_version` is the major/minor projection of the OpenAPI `info.version`. Each feature +contract version applies only to its listed OpenAPI operation IDs: adding an operation or compatible semantics increments +minor; removing, renaming, or incompatibly changing a listed operation increments major. Compatible clients must ignore +unknown optional fields introduced by a schema minor version. + +The Server stores one identity singleton in the configured primary relational database. Startup creates it atomically or +loads the existing value, so restarts, package upgrades, backup restore, and replicas sharing that database retain the +same ID. If identity schema initialization or loading fails, Server startup fails before readiness instead of publishing a +temporary identity. An in-memory SQLite deployment receives a new ID with each process because it has no durable store. + +Treat a restored backup as the same deployment and keep its ID. When a backup is used to create an independent clone, +stop every Server process using the clone database and rotate only the clone: + +```bash +uv run powercontext server identity-reset --env-file /path/to/clone.env --maintenance-confirmed +``` + +The command refuses in-memory databases and requires the explicit maintenance confirmation. It cannot detect active +replicas, so stopping them is an operator precondition. Logical application-data imports do not copy the identity unless +the `pc_server_identity` table itself is included. + ## Python Client Install the Client role for the SDK: @@ -117,6 +148,7 @@ from powercontext.client import PowerContextClient async def search() -> None: async with PowerContextClient("http://127.0.0.1:8000") as client: + server_info = await client.get_server_info() capabilities = await client.get_capabilities() result = await client.search_memory( SearchMemoryRequest( @@ -126,6 +158,7 @@ async def search() -> None: mode="auto", ) ) + print(server_info.model_dump()) print(capabilities.model_dump()) print(result.model_dump()) ``` diff --git a/docs/zh/development/remote-access-implementation.md b/docs/zh/development/remote-access-implementation.md index e20cadd82b..3651792398 100644 --- a/docs/zh/development/remote-access-implementation.md +++ b/docs/zh/development/remote-access-implementation.md @@ -83,6 +83,7 @@ inference 配置见[配置 Pydantic AI 推理](pydantic-ai-inference.md)。 | 领域 | Operation | | --- | --- | | Health | liveness 和 readiness | +| Server discovery | 稳定 deployment identity 和协议契约 | | Capabilities | source type、Artifact family、extraction、search mode | | Sources | capture 持久化 content evidence | | Memory | flush 待处理 Source、remember 显式 entry、search | @@ -96,6 +97,34 @@ Server error 使用 OpenAPI error schema，并在 response header 中包含由 i Server-owned `X-PowerContext-Request-ID`。validation error、revision conflict、entry 不存在、inference unavailable 和内部 failure 会映射为稳定的 HTTP status code。 +### Server identity 与兼容性发现 + +`GET /v1/server-info` 受 `server.observe` 保护，返回稳定的 deployment `server_id`、已安装 package version、API +contract version、response schema version 和首批 feature contract。它刻意不返回 health、已启用 runtime +capability、limit、inventory、secret、文件系统 path 或已认证 principal；这些信息分别由 health、capabilities、 +statistics 和 access endpoint 负责。 + +所有 discovery version 都使用 `major` 和 `minor` 整数。major 增加表示受管契约可能被移除或发生不兼容变化；minor +增加只允许向后兼容的扩展。response 的 `schema_version` 管理字段与语义，`api_contract_version` 是 OpenAPI +`info.version` 的 major/minor 投影。每个 feature contract version 只约束它列出的 OpenAPI operation ID：增加 +operation 或兼容语义时增加 minor，移除、重命名或不兼容地改变已列 operation 时增加 major。兼容 client 必须忽略 +schema minor version 新增的未知可选字段。 + +Server 在配置的主关系数据库中保存一条 identity singleton。启动时会原子创建或读取它，因此进程重启、package +升级、备份恢复以及共享同一数据库的 replica 都保持相同 ID。identity schema 初始化或读取失败时，Server 会在 +进入 readiness 之前直接启动失败，而不会发布临时 identity。内存 SQLite 没有持久存储，所以每个新进程都会获得 +新的 ID。 + +把备份恢复为原 deployment 时应保留原 ID。若用备份创建独立 clone，请停止所有使用 clone 数据库的 Server +进程，然后只在 clone 上轮换： + +```bash +uv run powercontext server identity-reset --env-file /path/to/clone.env --maintenance-confirmed +``` + +该命令拒绝内存数据库，并要求显式 maintenance confirmation。它无法检测仍在运行的 replica，因此停服是 operator +前置条件。逻辑 application-data import 不会复制 identity，除非显式包含 `pc_server_identity` 表。 + ## Python Client 安装 Client role 以使用 SDK： @@ -113,6 +142,7 @@ from powercontext.client import PowerContextClient async def search() -> None: async with PowerContextClient("http://127.0.0.1:8000") as client: + server_info = await client.get_server_info() capabilities = await client.get_capabilities() result = await client.search_memory( SearchMemoryRequest( @@ -122,6 +152,7 @@ async def search() -> None: mode="auto", ) ) + print(server_info.model_dump()) print(capabilities.model_dump()) print(result.model_dump()) ``` diff --git a/integrations/dsh/plugins/powercontext/src/operations.generated.ts b/integrations/dsh/plugins/powercontext/src/operations.generated.ts index 32e2223d57..9b59ece9cb 100644 --- a/integrations/dsh/plugins/powercontext/src/operations.generated.ts +++ b/integrations/dsh/plugins/powercontext/src/operations.generated.ts @@ -23,6 +23,7 @@ export const OPERATIONS = { flush_profile: { method: 'POST', path: '/v1/profile/flush', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_liveness: { method: 'GET', path: '/health/live', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_readiness: { method: 'GET', path: '/health/ready', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, + get_server_info: { method: 'GET', path: '/v1/server-info', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, list_scopes: { method: 'GET', path: '/v1/scopes', location: "query", scopeMode: 'none', pathParameters: [], queryParams: ['query','query_field','parent_scope_id','external_reference_kind','binding_integration','binding_kind','limit','cursor'], headerParams: [], successStatuses: [200], emptyStatuses: [] }, create_scope: { method: 'POST', path: '/v1/scopes', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [201], emptyStatuses: [] }, diff --git a/integrations/opencode/plugins/powercontext/src/operations.generated.ts b/integrations/opencode/plugins/powercontext/src/operations.generated.ts index 32e2223d57..9b59ece9cb 100644 --- a/integrations/opencode/plugins/powercontext/src/operations.generated.ts +++ b/integrations/opencode/plugins/powercontext/src/operations.generated.ts @@ -23,6 +23,7 @@ export const OPERATIONS = { flush_profile: { method: 'POST', path: '/v1/profile/flush', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_liveness: { method: 'GET', path: '/health/live', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_readiness: { method: 'GET', path: '/health/ready', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, + get_server_info: { method: 'GET', path: '/v1/server-info', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, list_scopes: { method: 'GET', path: '/v1/scopes', location: "query", scopeMode: 'none', pathParameters: [], queryParams: ['query','query_field','parent_scope_id','external_reference_kind','binding_integration','binding_kind','limit','cursor'], headerParams: [], successStatuses: [200], emptyStatuses: [] }, create_scope: { method: 'POST', path: '/v1/scopes', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [201], emptyStatuses: [] }, diff --git a/integrations/pi/plugins/powercontext/src/operations.generated.ts b/integrations/pi/plugins/powercontext/src/operations.generated.ts index 32e2223d57..9b59ece9cb 100644 --- a/integrations/pi/plugins/powercontext/src/operations.generated.ts +++ b/integrations/pi/plugins/powercontext/src/operations.generated.ts @@ -23,6 +23,7 @@ export const OPERATIONS = { flush_profile: { method: 'POST', path: '/v1/profile/flush', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_liveness: { method: 'GET', path: '/health/live', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_readiness: { method: 'GET', path: '/health/ready', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, + get_server_info: { method: 'GET', path: '/v1/server-info', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, get_capabilities: { method: 'GET', path: '/v1/capabilities', location: null, scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [200], emptyStatuses: [] }, list_scopes: { method: 'GET', path: '/v1/scopes', location: "query", scopeMode: 'none', pathParameters: [], queryParams: ['query','query_field','parent_scope_id','external_reference_kind','binding_integration','binding_kind','limit','cursor'], headerParams: [], successStatuses: [200], emptyStatuses: [] }, create_scope: { method: 'POST', path: '/v1/scopes', location: "body", scopeMode: 'none', pathParameters: [], queryParams: [], headerParams: [], successStatuses: [201], emptyStatuses: [] }, diff --git a/openapi/powercontext.yaml b/openapi/powercontext.yaml index 1461bf30ef..5f2d0474f9 100644 --- a/openapi/powercontext.yaml +++ b/openapi/powercontext.yaml @@ -16,7 +16,7 @@ openapi: 3.0.3 info: title: PowerContext API description: Remote PowerContext transport. Runtime behavior is reported by /v1/capabilities. - version: 1.1.0 + version: 1.2.0 security: - BearerAuth: [] - {} @@ -242,6 +242,31 @@ paths: application/json: schema: $ref: "#/components/schemas/ReadinessResponse" + /v1/server-info: + get: + tags: [server] + summary: Get stable Server deployment identity and protocol contracts + description: >- + Returns deployment identity and compatibility metadata only. Runtime availability, enabled behavior, + limits and inventory remain owned by health, capabilities and statistics endpoints. + operationId: get_server_info + x-powercontext-access: {action: server.observe, resource: {type: server}} + responses: + "200": + description: Stable deployment identity and protocol compatibility metadata. + headers: + X-PowerContext-Request-ID: + $ref: "#/components/headers/RequestId" + content: + application/json: + schema: + $ref: "#/components/schemas/ServerInfo" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "503": + $ref: "#/components/responses/Unavailable" /v1/capabilities: get: tags: [capabilities] @@ -4450,6 +4475,69 @@ components: schema: $ref: "#/components/schemas/ErrorResponse" schemas: + ContractVersion: + type: object + description: >- + A major/minor compatibility version. A major increment may remove or incompatibly change the governed + contract. A minor increment only adds backward-compatible behavior or fields. + required: [major, minor] + properties: + major: + type: integer + minimum: 1 + minor: + type: integer + minimum: 0 + FeatureContract: + type: object + description: >- + Compatibility version for exactly the listed OpenAPI operation IDs. Adding operations or compatible + semantics increments minor; removing, renaming or incompatibly changing a listed operation increments major. + required: [version, operations] + properties: + version: + $ref: "#/components/schemas/ContractVersion" + operations: + type: array + minItems: 1 + uniqueItems: true + items: + type: string + ServerInfo: + type: object + description: >- + Stable deployment identity and protocol compatibility metadata. Compatible clients must ignore unknown + optional fields added by a future schema minor version. This contract intentionally excludes runtime + capabilities, health, limits, inventory and authorization-principal identity. + required: + [schema_version, product, server_id, package_version, api_contract_version, feature_contracts] + properties: + schema_version: + allOf: + - $ref: "#/components/schemas/ContractVersion" + description: Compatibility version for this response shape and field semantics. + product: + type: string + enum: [powercontext] + server_id: + type: string + minLength: 1 + maxLength: 128 + description: >- + Opaque identity of the durable Server deployment. It is unrelated to Access deployment_id and remains + stable across restarts, upgrades, backup restore and replicas sharing the same primary database. + package_version: + type: string + minLength: 1 + api_contract_version: + allOf: + - $ref: "#/components/schemas/ContractVersion" + description: Major/minor projection of the OpenAPI info.version served by this package. + feature_contracts: + type: object + description: Stable feature groups keyed by contract name. + additionalProperties: + $ref: "#/components/schemas/FeatureContract" CreateSubjectSourceRequest: type: "object" additionalProperties: false diff --git a/src/powercontext/client/client.py b/src/powercontext/client/client.py index f450861bc2..04c1c58e5b 100644 --- a/src/powercontext/client/client.py +++ b/src/powercontext/client/client.py @@ -177,6 +177,7 @@ SearchMemoryResponse, SearchTopicMemoryRequest, SearchTopicMemoryResponse, + ServerInfo, SetDefaultScopeRequest, SetScopeBindingRequest, SkillArtifact, @@ -246,6 +247,7 @@ GET_PROMPT_CONFIGURATION, GET_READINESS, GET_SCOPE, + GET_SERVER_INFO, GET_SKILL, GET_SKILL_PACKAGE_MANIFEST, GET_SOURCE, @@ -387,6 +389,11 @@ async def get_capabilities(self) -> Capabilities: return await self._request(GET_CAPABILITIES) + async def get_server_info(self) -> ServerInfo: + """Read stable deployment identity and protocol compatibility metadata.""" + + return await self._request(GET_SERVER_INFO) + async def list_scopes( self, query: str | None = None, diff --git a/src/powercontext/http/__init__.py b/src/powercontext/http/__init__.py index 1a41691998..c9bf6d9c7f 100644 --- a/src/powercontext/http/__init__.py +++ b/src/powercontext/http/__init__.py @@ -96,6 +96,7 @@ ContextAssemblySection, ContextReference, ContinueHandoffRequest, + ContractVersion, CreateAccessBindingRequest, CreateArtifactRequest, CreateDreamRunRequest, @@ -149,6 +150,7 @@ FailureSignature, FailureVerification, FamilyCount, + FeatureContract, FinalizeHandoffRequest, FlushMemoryRequest, FlushMemoryResponse, @@ -349,6 +351,7 @@ SearchTopicMemoryRequest, SearchTopicMemoryResponse, ServerAccessResource, + ServerInfo, SetDefaultScopeRequest, SetScopeBindingRequest, SkillArtifact, @@ -490,6 +493,7 @@ "ContextAssemblySection", "ContextReference", "ContinueHandoffRequest", + "ContractVersion", "CreateAccessBindingRequest", "CreateArtifactRequest", "CreateDreamRunRequest", @@ -543,6 +547,7 @@ "FailureSignature", "FailureVerification", "FamilyCount", + "FeatureContract", "FinalizeHandoffRequest", "FlushMemoryRequest", "FlushMemoryResponse", @@ -743,6 +748,7 @@ "SearchTopicMemoryRequest", "SearchTopicMemoryResponse", "ServerAccessResource", + "ServerInfo", "SetDefaultScopeRequest", "SetScopeBindingRequest", "SkillArtifact", diff --git a/src/powercontext/http/_generated/models.py b/src/powercontext/http/_generated/models.py index 5ac8ed0246..db47de80a2 100644 --- a/src/powercontext/http/_generated/models.py +++ b/src/powercontext/http/_generated/models.py @@ -21,6 +21,42 @@ ) +class ContractVersion(BaseModel): + major: Annotated[StrictInt, Field(ge=1)] + minor: Annotated[StrictInt, Field(ge=0)] + + +class FeatureContract(BaseModel): + version: ContractVersion + operations: Annotated[list[StrictStr], Field(min_length=1)] + + +class Product(StrEnum): + POWERCONTEXT = "powercontext" + + +class ServerInfo(BaseModel): + schema_version: Annotated[ + ContractVersion, Field(description="Compatibility version for this response shape and field semantics.") + ] + product: Product + server_id: Annotated[ + StrictStr, + Field( + description="Opaque identity of the durable Server deployment. It is unrelated to Access deployment_id and remains stable across restarts, upgrades, backup restore and replicas sharing the same primary database.", + max_length=128, + min_length=1, + ), + ] + package_version: Annotated[StrictStr, Field(min_length=1)] + api_contract_version: Annotated[ + ContractVersion, Field(description="Major/minor projection of the OpenAPI info.version served by this package.") + ] + feature_contracts: Annotated[ + dict[str, FeatureContract], Field(description="Stable feature groups keyed by contract name.") + ] + + class SubjectType(StrEnum): USER = "user" diff --git a/src/powercontext/http/_generated/operations.py b/src/powercontext/http/_generated/operations.py index 221caae794..aac94afdea 100644 --- a/src/powercontext/http/_generated/operations.py +++ b/src/powercontext/http/_generated/operations.py @@ -156,6 +156,7 @@ SearchMemoryResponse, SearchTopicMemoryRequest, SearchTopicMemoryResponse, + ServerInfo, SetDefaultScopeRequest, SetScopeBindingRequest, SkillArtifact, @@ -177,7 +178,7 @@ OPENAPI_VERSION = "3.0.3" API_TITLE = "PowerContext API" API_DESCRIPTION = "Remote PowerContext transport. Runtime behavior is reported by /v1/capabilities." -API_VERSION = "1.1.0" +API_VERSION = "1.2.0" RequestT = TypeVar("RequestT") ResponseT = TypeVar("ResponseT") @@ -368,6 +369,30 @@ class AccessRequirement(BaseModel): access=None, ) +GET_SERVER_INFO = Operation[None, ServerInfo]( + method="GET", + path="/v1/server-info", + operation_id="get_server_info", + request_type=None, + request_location=None, + path_parameters=(), + response_type=ServerInfo, + success_status=200, + summary="Get stable Server deployment identity and protocol contracts", + tags=("server",), + scope_mode="none", + responses={ + 200: { + "description": "Stable deployment identity and protocol compatibility metadata.", + "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, + }, + 401: {"$ref": "#/components/responses/Unauthorized"}, + 403: {"$ref": "#/components/responses/Forbidden"}, + 503: {"$ref": "#/components/responses/Unavailable"}, + }, + access=AccessRequirement(action="server.observe", resource="server", scope_id_field=None, resolver="static"), +) + GET_CAPABILITIES = Operation[None, Capabilities]( method="GET", path="/v1/capabilities", diff --git a/src/powercontext/http/_generated/schema.py b/src/powercontext/http/_generated/schema.py index 599f756efa..6b7cc1ef16 100644 --- a/src/powercontext/http/_generated/schema.py +++ b/src/powercontext/http/_generated/schema.py @@ -7,7 +7,7 @@ "info": { "title": "PowerContext API", "description": "Remote PowerContext transport. Runtime behavior is reported by /v1/capabilities.", - "version": "1.1.0", + "version": "1.2.0", }, "paths": { "/v1/scopes/{scope_id}/subject-sources": { @@ -191,6 +191,29 @@ "security": [], } }, + "/v1/server-info": { + "get": { + "tags": ["server"], + "summary": "Get stable Server deployment identity and protocol contracts", + "description": "Returns deployment identity and " + "compatibility metadata only. Runtime " + "availability, enabled behavior, limits and " + "inventory remain owned by health, " + "capabilities and statistics endpoints.", + "operationId": "get_server_info", + "responses": { + "200": { + "description": "Stable deployment identity and protocol compatibility metadata.", + "headers": {"X-PowerContext-Request-ID": {"$ref": "#/components/headers/RequestId"}}, + "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ServerInfo"}}}, + }, + "401": {"$ref": "#/components/responses/Unauthorized"}, + "403": {"$ref": "#/components/responses/Forbidden"}, + "503": {"$ref": "#/components/responses/Unavailable"}, + }, + "x-powercontext-access": {"action": "server.observe", "resource": {"type": "server"}}, + } + }, "/v1/capabilities": { "get": { "tags": ["capabilities"], @@ -4532,6 +4555,101 @@ }, "components": { "schemas": { + "ContractVersion": { + "properties": { + "major": {"type": "integer", "minimum": 1.0}, + "minor": {"type": "integer", "minimum": 0.0}, + }, + "type": "object", + "required": ["major", "minor"], + "description": "A major/minor compatibility " + "version. A major increment may " + "remove or incompatibly change the " + "governed contract. A minor " + "increment only adds " + "backward-compatible behavior or " + "fields.", + }, + "FeatureContract": { + "properties": { + "version": {"$ref": "#/components/schemas/ContractVersion"}, + "operations": {"items": {"type": "string"}, "type": "array", "minItems": 1, "uniqueItems": True}, + }, + "type": "object", + "required": ["version", "operations"], + "description": "Compatibility version for exactly " + "the listed OpenAPI operation IDs. " + "Adding operations or compatible " + "semantics increments minor; " + "removing, renaming or incompatibly " + "changing a listed operation " + "increments major.", + }, + "ServerInfo": { + "properties": { + "schema_version": { + "allOf": [{"$ref": "#/components/schemas/ContractVersion"}], + "description": "Compatibility version for this response shape and field semantics.", + }, + "product": {"type": "string", "enum": ["powercontext"]}, + "server_id": { + "type": "string", + "maxLength": 128, + "minLength": 1, + "description": "Opaque " + "identity " + "of the " + "durable " + "Server " + "deployment. " + "It is " + "unrelated " + "to Access " + "deployment_id " + "and " + "remains " + "stable " + "across " + "restarts, " + "upgrades, " + "backup " + "restore " + "and " + "replicas " + "sharing " + "the same " + "primary " + "database.", + }, + "package_version": {"type": "string", "minLength": 1}, + "api_contract_version": { + "allOf": [{"$ref": "#/components/schemas/ContractVersion"}], + "description": "Major/minor projection of the OpenAPI info.version served by this package.", + }, + "feature_contracts": { + "additionalProperties": {"$ref": "#/components/schemas/FeatureContract"}, + "type": "object", + "description": "Stable feature groups keyed by contract name.", + }, + }, + "type": "object", + "required": [ + "schema_version", + "product", + "server_id", + "package_version", + "api_contract_version", + "feature_contracts", + ], + "description": "Stable deployment identity and protocol " + "compatibility metadata. Compatible " + "clients must ignore unknown optional " + "fields added by a future schema minor " + "version. This contract intentionally " + "excludes runtime capabilities, health, " + "limits, inventory and " + "authorization-principal identity.", + }, "CreateSubjectSourceRequest": { "properties": { "subject_key": {"type": "string", "maxLength": 256, "minLength": 1, "pattern": ".*\\S.*"}, diff --git a/src/powercontext/server/app.py b/src/powercontext/server/app.py index c8cfa7ddfd..7ff95dde5c 100644 --- a/src/powercontext/server/app.py +++ b/src/powercontext/server/app.py @@ -539,6 +539,7 @@ SearchTopicMemoryRequest, SearchTopicMemoryResponse, ServerAccessResource, + ServerInfo, SetDefaultScopeRequest, SetScopeBindingRequest, SkillArtifact, @@ -683,6 +684,7 @@ GET_PROMPT_CONFIGURATION, GET_READINESS, GET_SCOPE, + GET_SERVER_INFO, GET_SKILL, GET_SKILL_PACKAGE_MANIFEST, GET_SOURCE, @@ -1293,6 +1295,7 @@ def create_app( search_modes=[], context_versions=[], ) + app.state.server_info = None @app.middleware("http") async def attach_request_id(request: Request, call_next: RequestResponseEndpoint) -> Response: @@ -1358,6 +1361,7 @@ async def unexpected_error(request: Request, error: Exception) -> JSONResponse: _add_route(app, LIST_DREAM_RUNS, list_dream_runs) _add_route(app, GET_LIVENESS, get_liveness) _add_route(app, GET_READINESS, get_readiness) + _add_route(app, GET_SERVER_INFO, get_server_info) _add_route(app, GET_CAPABILITIES, get_capabilities) _add_route(app, LIST_SCOPES, list_scopes) _add_route(app, CREATE_SCOPE, create_scope) @@ -1555,6 +1559,13 @@ async def get_capabilities(request: Request) -> Capabilities: return request.app.state.capabilities +async def get_server_info(request: Request) -> ServerInfo: + info: ServerInfo | None = request.app.state.server_info + if info is None: + raise _RuntimeNotReadyError + return info + + async def get_access_principal(request: Request) -> AccessMeResponse: access = _require_access_control(request) provider = access.provider_capabilities diff --git a/src/powercontext/server/cli.py b/src/powercontext/server/cli.py index 36a850cf36..14c5cd2261 100644 --- a/src/powercontext/server/cli.py +++ b/src/powercontext/server/cli.py @@ -46,6 +46,7 @@ server_settings_context, ) from powercontext.server.factory import create_server_app +from powercontext.server.identity import open_server_identity_repository from powercontext.server.logging import configure_server_logging from powercontext.server.processing_security import build_worker_security from powercontext.server.settings import ( @@ -161,6 +162,32 @@ async def _processing_maintenance( return verification.ready +@app.command("identity-reset") +def identity_reset( + env_file: Annotated[Path | None, typer.Option(help="Load deployment settings from this environment file.")] = None, + maintenance_confirmed: Annotated[ + bool, + typer.Option(help="Confirm every Server process using the primary database is stopped."), + ] = False, +) -> None: + """Rotate the durable Server identity after cloning a stopped deployment.""" + + if not maintenance_confirmed: + raise typer.BadParameter( # noqa: TRY003 + "identity reset requires --maintenance-confirmed after stopping every Server process" + ) + with server_settings_context(env_file=env_file) as settings: + if isinstance(settings.database, SQLiteConfig) and settings.database.is_in_memory: + raise typer.BadParameter("identity reset requires a persistent database") # noqa: TRY003 + server_id = asyncio.run(_reset_server_identity(settings)) + typer.echo(server_id) + + +async def _reset_server_identity(settings: ServerSettings) -> str: + async with open_server_identity_repository(settings.database) as repository: + return await repository.rotate() + + @app.command() def run( host: Annotated[str | None, typer.Option(help="Address to bind.")] = None, diff --git a/src/powercontext/server/factory.py b/src/powercontext/server/factory.py index 189a9cf155..1335b28b2c 100644 --- a/src/powercontext/server/factory.py +++ b/src/powercontext/server/factory.py @@ -75,6 +75,8 @@ from powercontext.server.cursor_secret import resolve_cursor_secret from powercontext.server.dashboard import mount_dashboard from powercontext.server.dream_access import DreamAccess +from powercontext.server.identity import open_server_identity_repository +from powercontext.server.info import server_info from powercontext.server.mcp import mount_mcp from powercontext.server.metrics import CONTENT_TYPE_LATEST, HttpMetricsMiddleware, ServerMetrics from powercontext.server.middleware import AuthenticationMiddleware @@ -176,6 +178,8 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: ) cursor_secret = resolve_cursor_secret(config.database, configured_cursor_secret) async with AsyncExitStack() as resources: + async with open_server_identity_repository(config.database) as identity_repository: + server_id = await identity_repository.load_or_create() active_access_control = configured_access_control if active_access_control is None and resolved.access.mode == "enforced": active_access_control = await resources.enter_async_context( @@ -255,6 +259,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: app.state.access_control = active_access_control app.state.authentication_provider = configured_authentication app.state.capabilities = await _server_capabilities(runtime) + app.state.server_info = server_info(server_id) await readiness_probe() try: yield @@ -264,6 +269,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: app.state.application = None app.state.access_control = configured_access_control app.state.authentication_provider = configured_authentication + app.state.server_info = None app.state.capabilities = Capabilities( source_types=[], artifact_families=[], diff --git a/src/powercontext/server/identity.py b/src/powercontext/server/identity.py new file mode 100644 index 0000000000..a8921318b6 --- /dev/null +++ b/src/powercontext/server/identity.py @@ -0,0 +1,114 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Durable identity for one configured Server deployment.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator, Callable +from contextlib import asynccontextmanager +from uuid import uuid4 + +from sqlalchemy import CheckConstraint, Column, Integer, MetaData, String, Table, insert, select, update +from sqlalchemy.exc import IntegrityError + +from powercontext.builtin.persistence.database import AsyncDatabase +from powercontext.builtin.persistence.oceanbase import OceanBaseConfig, OceanBaseProfile +from powercontext.builtin.persistence.seekdb import SeekDBConfig, SeekDBProfile +from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile +from powercontext.builtin.runtime.config import DatabaseConfig + +_IDENTITY_METADATA = MetaData() +_SINGLETON_KEY = 1 + +SERVER_IDENTITY_TABLE = Table( + "pc_server_identity", + _IDENTITY_METADATA, + Column("singleton_key", Integer, primary_key=True), + Column("server_id", String(36), nullable=False, unique=True), + CheckConstraint("singleton_key = 1", name="ck_pc_server_identity_singleton"), +) + + +class ServerIdentityRepository: + """Own the singleton deployment identity in the primary relational backend.""" + + def __init__(self, database: AsyncDatabase, *, id_factory: Callable[[], str] | None = None) -> None: + self._database = database + self._id_factory = (lambda: str(uuid4())) if id_factory is None else id_factory + + async def load_or_create(self) -> str: + """Return the durable identity, creating it once across concurrent replicas.""" + + server_id = await self._load() + if server_id is not None: + return server_id + + candidate = self._id_factory() + try: + async with self._database.transaction() as connection: + await connection.execute( + insert(SERVER_IDENTITY_TABLE).values(singleton_key=_SINGLETON_KEY, server_id=candidate) + ) + except IntegrityError: + # A concurrent initializer may have committed the singleton first. + server_id = await self._load() + if server_id is None: + raise + return server_id + return candidate + + async def rotate(self) -> str: + """Replace the identity during an operator-confirmed offline clone procedure.""" + + candidate = self._id_factory() + async with self._database.transaction() as connection: + result = await connection.execute( + update(SERVER_IDENTITY_TABLE) + .where(SERVER_IDENTITY_TABLE.c.singleton_key == _SINGLETON_KEY) + .values(server_id=candidate) + ) + if result.rowcount == 0: + await connection.execute( + insert(SERVER_IDENTITY_TABLE).values(singleton_key=_SINGLETON_KEY, server_id=candidate) + ) + return candidate + + async def _load(self) -> str | None: + async with self._database.transaction() as connection: + result = await connection.execute( + select(SERVER_IDENTITY_TABLE.c.server_id).where(SERVER_IDENTITY_TABLE.c.singleton_key == _SINGLETON_KEY) + ) + value = result.scalar_one_or_none() + return None if value is None else str(value) + + +@asynccontextmanager +async def open_server_identity_repository(config: DatabaseConfig) -> AsyncIterator[ServerIdentityRepository]: + """Open the configured primary database with only the Server identity schema.""" + + tables = (SERVER_IDENTITY_TABLE,) + if isinstance(config, SQLiteConfig): + opened = SQLiteProfile.open(config, tables=tables) + elif isinstance(config, OceanBaseConfig): + opened = OceanBaseProfile.open(config, tables=tables) + elif isinstance(config, SeekDBConfig): + opened = SeekDBProfile.open(config, tables=tables) + else: + raise TypeError(f"unsupported Server identity database: {type(config).__name__}") # noqa: TRY003 + async with opened as profile: + yield ServerIdentityRepository(profile.database) + + +__all__ = ("SERVER_IDENTITY_TABLE", "ServerIdentityRepository", "open_server_identity_repository") diff --git a/src/powercontext/server/info.py b/src/powercontext/server/info.py new file mode 100644 index 0000000000..c8c5f83dd2 --- /dev/null +++ b/src/powercontext/server/info.py @@ -0,0 +1,57 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Authoritative static discovery contract for the PowerContext Server.""" + +from __future__ import annotations + +from importlib.metadata import version + +from packaging.version import Version + +from powercontext.http import ServerInfo +from powercontext.http._generated.operations import API_VERSION + +_SCHEMA_VERSION = {"major": 1, "minor": 0} +_FEATURE_CONTRACTS = { + "access.principal": { + "version": {"major": 1, "minor": 0}, + "operations": ["get_access_principal"], + }, + "scope.selection": { + "version": {"major": 1, "minor": 0}, + "operations": ["list_scopes", "get_scope", "get_default_scope"], + }, + "memory.explicit": { + "version": {"major": 1, "minor": 0}, + "operations": ["remember_memory", "search_memory", "get_memory_entry"], + }, +} + + +def server_info(server_id: str) -> ServerInfo: + """Build discovery metadata from the generated API contract and installed package.""" + + api_version = Version(API_VERSION) + return ServerInfo.model_validate({ + "schema_version": _SCHEMA_VERSION, + "product": "powercontext", + "server_id": server_id, + "package_version": version("powercontext"), + "api_contract_version": {"major": api_version.major, "minor": api_version.minor}, + "feature_contracts": _FEATURE_CONTRACTS, + }) + + +__all__ = ("server_info",) diff --git a/tests/test_api_contract.py b/tests/test_api_contract.py index 872ad33b47..32f4b80c0a 100644 --- a/tests/test_api_contract.py +++ b/tests/test_api_contract.py @@ -152,6 +152,7 @@ ) from powercontext.server.app import create_app from powercontext.server.factory import create_server_app +from powercontext.server.info import server_info from powercontext.server.settings import HandoffReportConfig, ServerSettings @@ -180,6 +181,58 @@ def test_contract_uses_the_namespaced_request_id_header() -> None: assert "X-Request-ID" not in contract +def test_server_info_contract_is_observable_and_forward_compatible() -> None: + contract = yaml.safe_load(CONTRACT_PATH.read_text()) + + assert contract["info"]["version"] == "1.2.0" + operation = contract["paths"]["/v1/server-info"]["get"] + assert operation["operationId"] == "get_server_info" + assert operation["x-powercontext-access"] == { + "action": "server.observe", + "resource": {"type": "server"}, + } + schema = contract["components"]["schemas"]["ServerInfo"] + assert schema["required"] == [ + "schema_version", + "product", + "server_id", + "package_version", + "api_contract_version", + "feature_contracts", + ] + assert "additionalProperties" not in schema + + parsed = http_models.ServerInfo.model_validate({ + "schema_version": {"major": 1, "minor": 0}, + "product": "powercontext", + "server_id": "server-a", + "package_version": "1.2.3", + "api_contract_version": {"major": 1, "minor": 2}, + "feature_contracts": { + "memory.explicit": { + "version": {"major": 1, "minor": 0}, + "operations": ["remember_memory"], + } + }, + "future_optional_field": {"added_in_schema_minor": 1}, + }) + assert parsed.server_id == "server-a" + + +def test_server_info_feature_contracts_name_existing_openapi_operations() -> None: + contract = yaml.safe_load(CONTRACT_PATH.read_text()) + operation_ids = { + operation["operationId"] for path_item in contract["paths"].values() for operation in path_item.values() + } + advertised = { + operation_id + for feature in server_info("server-a").feature_contracts.values() + for operation_id in feature.operations + } + + assert advertised <= operation_ids + + def test_contract_declares_server_and_remote_target_bearer_boundaries() -> None: contract = yaml.safe_load(CONTRACT_PATH.read_text()) diff --git a/tests/test_cli.py b/tests/test_cli.py index dc0ec5e7bf..069549ded3 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -629,6 +629,27 @@ def test_cli_exposes_installed_role_commands() -> None: assert "client" not in result.output +def test_server_identity_reset_requires_offline_confirmation_and_rotates(tmp_path) -> None: + environment = tmp_path / "server.env" + environment.write_text(f"POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:///{tmp_path / 'runtime.db'}\n") + cli = create_cli([server_app]) + + refused = CliRunner().invoke(cli, ["server", "identity-reset", "--env-file", str(environment)]) + first = CliRunner().invoke( + cli, + ["server", "identity-reset", "--env-file", str(environment), "--maintenance-confirmed"], + ) + second = CliRunner().invoke( + cli, + ["server", "identity-reset", "--env-file", str(environment), "--maintenance-confirmed"], + ) + + assert refused.exit_code == 2 + assert "requires --maintenance-confirmed" in refused.output + assert first.exit_code == second.exit_code == 0 + assert first.output.strip() != second.output.strip() + + def test_service_command_provider_requires_the_complete_server_role() -> None: script = """ import builtins diff --git a/tests/test_client.py b/tests/test_client.py index 09df64fa0c..d4fce54f3c 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -63,6 +63,38 @@ ) +def test_client_reads_server_info_and_ignores_future_optional_fields() -> None: + async def scenario() -> None: + def respond(request: httpx.Request) -> httpx.Response: + assert request.url.path == "/v1/server-info" + return httpx.Response( + 200, + json={ + "schema_version": {"major": 1, "minor": 0}, + "product": "powercontext", + "server_id": "server-a", + "package_version": "1.2.3", + "api_contract_version": {"major": 1, "minor": 2}, + "feature_contracts": { + "access.principal": { + "version": {"major": 1, "minor": 0}, + "operations": ["get_access_principal"], + } + }, + "future_optional_field": True, + }, + request=request, + ) + + async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as http_client: + info = await PowerContextClient("https://memory.example", http_client=http_client).get_server_info() + + assert info.server_id == "server-a" + assert info.api_contract_version.minor == 2 + + asyncio.run(scenario()) + + def test_prepare_client_preserves_omitted_and_explicit_assembly() -> None: async def scenario() -> None: bodies = [] diff --git a/tests/test_server.py b/tests/test_server.py index a17cc5e1a6..6007f6ec3d 100644 --- a/tests/test_server.py +++ b/tests/test_server.py @@ -17,6 +17,7 @@ import os import re import shlex +from contextlib import asynccontextmanager from datetime import datetime, timedelta from pathlib import Path from types import SimpleNamespace @@ -274,6 +275,57 @@ def test_server_reuses_file_backed_cursor_secret_across_restarts(tmp_path, monke assert len(second_page.json()["items"]) == 1 +def test_server_info_uses_one_durable_identity_across_restarts(tmp_path) -> None: + settings = ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}"), + auth=BearerAuthConfig(enabled=False), + mcp=McpConfig(enabled=False), + ) + + with TestClient(create_server_app(settings=settings)) as client: + first = client.get("/v1/server-info") + with TestClient(create_server_app(settings=settings)) as client: + second = client.get("/v1/server-info") + + assert first.status_code == second.status_code == 200 + assert first.json() == second.json() + assert first.json()["schema_version"] == {"major": 1, "minor": 0} + assert first.json()["api_contract_version"] == {"major": 1, "minor": 2} + assert first.json()["feature_contracts"] == { + "access.principal": { + "version": {"major": 1, "minor": 0}, + "operations": ["get_access_principal"], + }, + "scope.selection": { + "version": {"major": 1, "minor": 0}, + "operations": ["list_scopes", "get_scope", "get_default_scope"], + }, + "memory.explicit": { + "version": {"major": 1, "minor": 0}, + "operations": ["remember_memory", "search_memory", "get_memory_entry"], + }, + } + + +def test_server_startup_fails_when_identity_initialization_fails(tmp_path, monkeypatch) -> None: + @asynccontextmanager + async def unavailable_identity(_config): + raise OSError("identity backend unavailable") # noqa: TRY003 + yield + + monkeypatch.setattr("powercontext.server.factory.open_server_identity_repository", unavailable_identity) + app = create_server_app( + settings=ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}"), + auth=BearerAuthConfig(enabled=False), + mcp=McpConfig(enabled=False), + ) + ) + + with pytest.raises(OSError, match="identity backend unavailable"), TestClient(app): + pass + + def test_server_settings_use_configured_workspace_for_default_skill_targets(tmp_path, monkeypatch) -> None: monkeypatch.setenv("POWERCONTEXT_SERVER_WORKSPACE", str(tmp_path)) monkeypatch.delenv("POWERCONTEXT_SERVER_EXTERNAL_SKILLS", raising=False) @@ -582,6 +634,8 @@ def test_server_factory_optionally_requires_bearer_authentication() -> None: missing = client.get("/v1/capabilities") invalid = client.get("/v1/capabilities", headers={"Authorization": "Bearer wrong"}) accepted = client.get("/v1/capabilities", headers={"Authorization": "Bearer server-secret"}) + protected_server_info = client.get("/v1/server-info") + accepted_server_info = client.get("/v1/server-info", headers={"Authorization": "Bearer server-secret"}) protected_metrics = client.get("/metrics") accepted_metrics = client.get("/metrics", headers={"Authorization": "Bearer server-secret"}) liveness = client.get("/health/live") @@ -599,6 +653,8 @@ def test_server_factory_optionally_requires_bearer_authentication() -> None: } assert invalid.status_code == 401 assert accepted.status_code == 200 + assert protected_server_info.status_code == 401 + assert accepted_server_info.status_code == 200 assert protected_metrics.status_code == 401 assert accepted_metrics.status_code == 200 assert liveness.status_code == 200 diff --git a/tests/test_server_identity.py b/tests/test_server_identity.py new file mode 100644 index 0000000000..115ba4688d --- /dev/null +++ b/tests/test_server_identity.py @@ -0,0 +1,77 @@ +# Copyright (c) 2026 OceanBase. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +import asyncio +import shutil + +from powercontext.builtin.persistence.sqlite import SQLiteConfig +from powercontext.server.identity import open_server_identity_repository + + +def test_server_identity_survives_reopen_restore_and_explicit_clone_rotation(tmp_path) -> None: + async def scenario() -> None: + primary_path = tmp_path / "primary.db" + restored_path = tmp_path / "restored.db" + primary = SQLiteConfig(url=f"sqlite+aiosqlite:///{primary_path}") + + async with open_server_identity_repository(primary) as repository: + original = await repository.load_or_create() + assert await repository.load_or_create() == original + + shutil.copy2(primary_path, restored_path) + restored = SQLiteConfig(url=f"sqlite+aiosqlite:///{restored_path}") + async with open_server_identity_repository(restored) as repository: + assert await repository.load_or_create() == original + rotated = await repository.rotate() + assert rotated != original + assert await repository.load_or_create() == rotated + + async with open_server_identity_repository(primary) as repository: + assert await repository.load_or_create() == original + + asyncio.run(scenario()) + + +def test_concurrent_server_initializers_converge_on_one_identity(tmp_path) -> None: + async def scenario() -> None: + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'deployment.db'}") + async with ( + open_server_identity_repository(config) as first, + open_server_identity_repository(config) as second, + ): + first_identity, second_identity = await asyncio.gather( + first.load_or_create(), + second.load_or_create(), + ) + + assert first_identity == second_identity + + asyncio.run(scenario()) + + +def test_in_memory_server_identity_is_stable_only_for_one_open_repository() -> None: + async def scenario() -> None: + config = SQLiteConfig() + async with open_server_identity_repository(config) as repository: + first = await repository.load_or_create() + assert await repository.load_or_create() == first + + async with open_server_identity_repository(config) as repository: + second = await repository.load_or_create() + + assert second != first + + asyncio.run(scenario()) From 8d2e8ef7df347f3902ebac851eaee95530ab0ad7 Mon Sep 17 00:00:00 2001 From: wutongyuonce <147830929+wutongyuonce@users.noreply.github.com> Date: Sun, 27 Sep 2026 20:16:15 +0800 Subject: [PATCH 2/8] chore(dsh): refresh generated bundle --- integrations/dsh/plugins/powercontext/lib/index.js | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/integrations/dsh/plugins/powercontext/lib/index.js b/integrations/dsh/plugins/powercontext/lib/index.js index 468c62ac8f..0799af6d9d 100644 --- a/integrations/dsh/plugins/powercontext/lib/index.js +++ b/integrations/dsh/plugins/powercontext/lib/index.js @@ -222,6 +222,17 @@ const OPERATIONS$1 = { successStatuses: [200], emptyStatuses: [] }, + get_server_info: { + method: "GET", + path: "/v1/server-info", + location: null, + scopeMode: "none", + pathParameters: [], + queryParams: [], + headerParams: [], + successStatuses: [200], + emptyStatuses: [] + }, get_capabilities: { method: "GET", path: "/v1/capabilities", From c0c735efee792ceabeca4da0ce70437e5abc6ad0 Mon Sep 17 00:00:00 2001 From: wutongyuonce <147830929+wutongyuonce@users.noreply.github.com> Date: Sun, 27 Sep 2026 20:20:11 +0800 Subject: [PATCH 3/8] fix(server): disable identity key autoincrement --- src/powercontext/server/identity.py | 2 +- tests/test_server_identity.py | 12 +++++++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/src/powercontext/server/identity.py b/src/powercontext/server/identity.py index a8921318b6..96fbd0087c 100644 --- a/src/powercontext/server/identity.py +++ b/src/powercontext/server/identity.py @@ -35,7 +35,7 @@ SERVER_IDENTITY_TABLE = Table( "pc_server_identity", _IDENTITY_METADATA, - Column("singleton_key", Integer, primary_key=True), + Column("singleton_key", Integer, primary_key=True, autoincrement=False), Column("server_id", String(36), nullable=False, unique=True), CheckConstraint("singleton_key = 1", name="ck_pc_server_identity_singleton"), ) diff --git a/tests/test_server_identity.py b/tests/test_server_identity.py index 115ba4688d..c4f12ccb65 100644 --- a/tests/test_server_identity.py +++ b/tests/test_server_identity.py @@ -17,8 +17,18 @@ import asyncio import shutil +from sqlalchemy.dialects import mysql +from sqlalchemy.schema import CreateTable + from powercontext.builtin.persistence.sqlite import SQLiteConfig -from powercontext.server.identity import open_server_identity_repository +from powercontext.server.identity import SERVER_IDENTITY_TABLE, open_server_identity_repository + + +def test_server_identity_singleton_key_is_not_auto_incremented_by_mysql_profiles() -> None: + ddl = str(CreateTable(SERVER_IDENTITY_TABLE).compile(dialect=mysql.dialect())) + + assert "AUTO_INCREMENT" not in ddl + assert "CHECK (singleton_key = 1)" in ddl def test_server_identity_survives_reopen_restore_and_explicit_clone_rotation(tmp_path) -> None: From 0384c93ba2a1469ecf9e4eb2514626e5b31912b0 Mon Sep 17 00:00:00 2001 From: wutongyuonce <147830929+wutongyuonce@users.noreply.github.com> Date: Sun, 27 Sep 2026 20:28:24 +0800 Subject: [PATCH 4/8] test(server): assert reset leaves storage untouched --- tests/test_cli.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/tests/test_cli.py b/tests/test_cli.py index 069549ded3..8b75738f5d 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -630,11 +630,15 @@ def test_cli_exposes_installed_role_commands() -> None: def test_server_identity_reset_requires_offline_confirmation_and_rotates(tmp_path) -> None: + database = tmp_path / "runtime.db" environment = tmp_path / "server.env" - environment.write_text(f"POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:///{tmp_path / 'runtime.db'}\n") + environment.write_text(f"POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:///{database}\n") cli = create_cli([server_app]) refused = CliRunner().invoke(cli, ["server", "identity-reset", "--env-file", str(environment)]) + assert refused.exit_code == 2 + assert not database.exists() + first = CliRunner().invoke( cli, ["server", "identity-reset", "--env-file", str(environment), "--maintenance-confirmed"], @@ -644,8 +648,6 @@ def test_server_identity_reset_requires_offline_confirmation_and_rotates(tmp_pat ["server", "identity-reset", "--env-file", str(environment), "--maintenance-confirmed"], ) - assert refused.exit_code == 2 - assert "requires --maintenance-confirmed" in refused.output assert first.exit_code == second.exit_code == 0 assert first.output.strip() != second.output.strip() From 154f6a57835eb4aa14504b99841b929382f1314e Mon Sep 17 00:00:00 2001 From: wutongyuonce <147830929+wutongyuonce@users.noreply.github.com> Date: Sun, 27 Sep 2026 21:45:01 +0800 Subject: [PATCH 5/8] fix(server): harden identity initialization --- .../development/remote-access-implementation.md | 10 ++++++---- .../development/remote-access-implementation.md | 8 ++++---- .../builtin/persistence/sqlite/profile.py | 8 ++++++-- src/powercontext/server/identity.py | 5 ++++- .../builtin/persistence/test_sqlite_profile.py | 16 ++++++++++++++++ tests/test_cli.py | 15 +++++++++++++++ tests/test_server_identity.py | 17 +++++++---------- 7 files changed, 58 insertions(+), 21 deletions(-) diff --git a/docs/en/development/remote-access-implementation.md b/docs/en/development/remote-access-implementation.md index e7c1cd3235..a06cb1a0c7 100644 --- a/docs/en/development/remote-access-implementation.md +++ b/docs/en/development/remote-access-implementation.md @@ -115,10 +115,12 @@ contract version applies only to its listed OpenAPI operation IDs: adding an ope minor; removing, renaming, or incompatibly changing a listed operation increments major. Compatible clients must ignore unknown optional fields introduced by a schema minor version. -The Server stores one identity singleton in the configured primary relational database. Startup creates it atomically or -loads the existing value, so restarts, package upgrades, backup restore, and replicas sharing that database retain the -same ID. If identity schema initialization or loading fails, Server startup fails before readiness instead of publishing a -temporary identity. An in-memory SQLite deployment receives a new ID with each process because it has no durable store. +The Server stores one identity singleton in the configured primary relational database. Startup creates the identity +table idempotently, then atomically creates or loads the singleton, so concurrent initializers converge on one ID and +restarts, package upgrades, backup restore, and replicas sharing that database retain it. If identity schema +initialization or loading fails, Server startup fails before readiness instead of publishing a temporary identity. An +in-memory SQLite deployment, including SQLite URI memory mode, receives a new ID with each database lifetime because it +has no durable store. Treat a restored backup as the same deployment and keep its ID. When a backup is used to create an independent clone, stop every Server process using the clone database and rotate only the clone: diff --git a/docs/zh/development/remote-access-implementation.md b/docs/zh/development/remote-access-implementation.md index 3651792398..68f882626a 100644 --- a/docs/zh/development/remote-access-implementation.md +++ b/docs/zh/development/remote-access-implementation.md @@ -110,10 +110,10 @@ statistics 和 access endpoint 负责。 operation 或兼容语义时增加 minor，移除、重命名或不兼容地改变已列 operation 时增加 major。兼容 client 必须忽略 schema minor version 新增的未知可选字段。 -Server 在配置的主关系数据库中保存一条 identity singleton。启动时会原子创建或读取它，因此进程重启、package -升级、备份恢复以及共享同一数据库的 replica 都保持相同 ID。identity schema 初始化或读取失败时，Server 会在 -进入 readiness 之前直接启动失败，而不会发布临时 identity。内存 SQLite 没有持久存储，所以每个新进程都会获得 -新的 ID。 +Server 在配置的主关系数据库中保存一条 identity singleton。启动时先幂等创建 identity table，再原子创建或读取 +singleton，因此并发 initializer 会收敛到同一 ID，进程重启、package 升级、备份恢复以及共享同一数据库的 replica +也会保持该 ID。identity schema 初始化或读取失败时，Server 会在进入 readiness 之前直接启动失败，而不会发布 +临时 identity。内存 SQLite（包括 SQLite URI memory mode）没有持久存储，所以每个数据库生命周期都会获得新 ID。 把备份恢复为原 deployment 时应保留原 ID。若用备份创建独立 clone，请停止所有使用 clone 数据库的 Server 进程，然后只在 clone 上轮换： diff --git a/src/powercontext/builtin/persistence/sqlite/profile.py b/src/powercontext/builtin/persistence/sqlite/profile.py index d2a22aa32e..eb59d4bdd3 100644 --- a/src/powercontext/builtin/persistence/sqlite/profile.py +++ b/src/powercontext/builtin/persistence/sqlite/profile.py @@ -105,8 +105,12 @@ async def open( def _is_memory_url(value: str) -> bool: - database = make_url(value).database - return database in {None, "", ":memory:"} + url = make_url(value) + database = url.database + if database in {None, "", ":memory:"}: + return True + uri = str(url.query.get("uri", "")).casefold() == "true" + return uri and (database == "file::memory:" or str(url.query.get("mode", "")).casefold() == "memory") def _create_database_directory(value: str) -> None: diff --git a/src/powercontext/server/identity.py b/src/powercontext/server/identity.py index 96fbd0087c..600650532a 100644 --- a/src/powercontext/server/identity.py +++ b/src/powercontext/server/identity.py @@ -22,6 +22,7 @@ from sqlalchemy import CheckConstraint, Column, Integer, MetaData, String, Table, insert, select, update from sqlalchemy.exc import IntegrityError +from sqlalchemy.schema import CreateTable from powercontext.builtin.persistence.database import AsyncDatabase from powercontext.builtin.persistence.oceanbase import OceanBaseConfig, OceanBaseProfile @@ -98,7 +99,7 @@ async def _load(self) -> str | None: async def open_server_identity_repository(config: DatabaseConfig) -> AsyncIterator[ServerIdentityRepository]: """Open the configured primary database with only the Server identity schema.""" - tables = (SERVER_IDENTITY_TABLE,) + tables: tuple[Table, ...] = () if isinstance(config, SQLiteConfig): opened = SQLiteProfile.open(config, tables=tables) elif isinstance(config, OceanBaseConfig): @@ -108,6 +109,8 @@ async def open_server_identity_repository(config: DatabaseConfig) -> AsyncIterat else: raise TypeError(f"unsupported Server identity database: {type(config).__name__}") # noqa: TRY003 async with opened as profile: + async with profile.database.transaction() as connection: + await connection.execute(CreateTable(SERVER_IDENTITY_TABLE, if_not_exists=True)) yield ServerIdentityRepository(profile.database) diff --git a/tests/builtin/persistence/test_sqlite_profile.py b/tests/builtin/persistence/test_sqlite_profile.py index ec52477672..8c4d60bde2 100644 --- a/tests/builtin/persistence/test_sqlite_profile.py +++ b/tests/builtin/persistence/test_sqlite_profile.py @@ -34,6 +34,22 @@ def test_sqlite_config_requires_the_async_dialect() -> None: SQLiteConfig(url="sqlite:///:memory:") +@pytest.mark.parametrize( + "url", + [ + "sqlite+aiosqlite:///:memory:", + "sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=true", + "sqlite+aiosqlite:///file::memory:?cache=shared&uri=true", + ], +) +def test_sqlite_config_recognizes_memory_urls(url: str) -> None: + assert SQLiteConfig(url=url).is_in_memory + + +def test_sqlite_config_does_not_treat_uri_like_filename_as_memory_without_uri_mode() -> None: + assert not SQLiteConfig(url="sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared").is_in_memory + + def test_sqlite_profile_creates_a_missing_database_directory(tmp_path) -> None: async def scenario() -> None: database = tmp_path / "nested" / "powercontext.db" diff --git a/tests/test_cli.py b/tests/test_cli.py index 8b75738f5d..af6a44636b 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -652,6 +652,21 @@ def test_server_identity_reset_requires_offline_confirmation_and_rotates(tmp_pat assert first.output.strip() != second.output.strip() +def test_server_identity_reset_rejects_sqlite_memory_uri(tmp_path) -> None: + environment = tmp_path / "server.env" + environment.write_text( + "POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=true\n" + ) + + result = CliRunner().invoke( + create_cli([server_app]), + ["server", "identity-reset", "--env-file", str(environment), "--maintenance-confirmed"], + ) + + assert result.exit_code == 2 + assert "identity reset requires a persistent database" in result.output + + def test_service_command_provider_requires_the_complete_server_role() -> None: script = """ import builtins diff --git a/tests/test_server_identity.py b/tests/test_server_identity.py index c4f12ccb65..297e62ba39 100644 --- a/tests/test_server_identity.py +++ b/tests/test_server_identity.py @@ -58,16 +58,13 @@ async def scenario() -> None: def test_concurrent_server_initializers_converge_on_one_identity(tmp_path) -> None: async def scenario() -> None: config = SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'deployment.db'}") - async with ( - open_server_identity_repository(config) as first, - open_server_identity_repository(config) as second, - ): - first_identity, second_identity = await asyncio.gather( - first.load_or_create(), - second.load_or_create(), - ) - - assert first_identity == second_identity + + async def initialize() -> str: + async with open_server_identity_repository(config) as repository: + return await repository.load_or_create() + + identities = await asyncio.gather(*(initialize() for _ in range(8))) + assert len(set(identities)) == 1 asyncio.run(scenario()) From 1f58fe2630a36a462e9f524e63c9c612d0483992 Mon Sep 17 00:00:00 2001 From: wutongyuonce <147830929+wutongyuonce@users.noreply.github.com> Date: Mon, 28 Sep 2026 17:48:46 +0800 Subject: [PATCH 6/8] fix(server): align discovery with runtime and OpenAPI --- .../remote-access-implementation.md | 10 ++- .../remote-access-implementation.md | 8 +- openapi/powercontext.yaml | 11 +++ scripts/generate_api.py | 44 +++++++++++ .../builtin/runtime/application.py | 12 +++ .../builtin/runtime/composition.py | 1 + .../http/_generated/operations.py | 11 +++ src/powercontext/http/_generated/schema.py | 12 +++ src/powercontext/server/factory.py | 7 +- src/powercontext/server/identity.py | 12 ++- src/powercontext/server/info.py | 20 +---- tests/test_api_contract.py | 25 ++++--- tests/test_api_generation.py | 75 +++++++++++++++++++ tests/test_server.py | 34 +++++++-- 14 files changed, 241 insertions(+), 41 deletions(-) diff --git a/docs/en/development/remote-access-implementation.md b/docs/en/development/remote-access-implementation.md index a06cb1a0c7..b3772ad20d 100644 --- a/docs/en/development/remote-access-implementation.md +++ b/docs/en/development/remote-access-implementation.md @@ -115,12 +115,18 @@ contract version applies only to its listed OpenAPI operation IDs: adding an ope minor; removing, renaming, or incompatibly changing a listed operation increments major. Compatible clients must ignore unknown optional fields introduced by a schema minor version. -The Server stores one identity singleton in the configured primary relational database. Startup creates the identity +OpenAPI's root `x-powercontext-feature-contracts` declares the explicit feature versions. Each governed operation lists +its membership in the same extension; `make api-generate` produces the discovery metadata from those declarations. +Generation rejects invalid versions, unknown or duplicate memberships, and features without operations. Version bumps +remain an explicit contract edit, not an automatic consequence of changing membership. + +The Server stores one identity singleton using the Runtime-owned primary relational database. Startup creates the identity table idempotently, then atomically creates or loads the singleton, so concurrent initializers converge on one ID and restarts, package upgrades, backup restore, and replicas sharing that database retain it. If identity schema initialization or loading fails, Server startup fails before readiness instead of publishing a temporary identity. An in-memory SQLite deployment, including SQLite URI memory mode, receives a new ID with each database lifetime because it -has no durable store. +has no durable store. Applications using the same shared-memory SQLite database share both data and identity while any +Runtime connection keeps that database alive; after the last connection closes, reopening creates new data and identity. Treat a restored backup as the same deployment and keep its ID. When a backup is used to create an independent clone, stop every Server process using the clone database and rotate only the clone: diff --git a/docs/zh/development/remote-access-implementation.md b/docs/zh/development/remote-access-implementation.md index 68f882626a..b624144204 100644 --- a/docs/zh/development/remote-access-implementation.md +++ b/docs/zh/development/remote-access-implementation.md @@ -110,10 +110,16 @@ statistics 和 access endpoint 负责。 operation 或兼容语义时增加 minor，移除、重命名或不兼容地改变已列 operation 时增加 major。兼容 client 必须忽略 schema minor version 新增的未知可选字段。 -Server 在配置的主关系数据库中保存一条 identity singleton。启动时先幂等创建 identity table，再原子创建或读取 +OpenAPI 根级 `x-powercontext-feature-contracts` 显式声明 feature version，各受管 operation 使用同名扩展声明归属。 +`make api-generate` 从这些声明生成 discovery metadata，并拒绝非法版本、未知或重复归属及没有 operation 的 feature。 +版本号仍须显式修改，不会因归属变化而自动增加。 + +Server 使用 Runtime 持有的主关系数据库保存一条 identity singleton。启动时先幂等创建 identity table，再原子创建或读取 singleton，因此并发 initializer 会收敛到同一 ID，进程重启、package 升级、备份恢复以及共享同一数据库的 replica 也会保持该 ID。identity schema 初始化或读取失败时，Server 会在进入 readiness 之前直接启动失败，而不会发布 临时 identity。内存 SQLite（包括 SQLite URI memory mode）没有持久存储，所以每个数据库生命周期都会获得新 ID。 +使用同一共享内存 SQLite 数据库的 application 会共享数据和 identity；只要仍有 Runtime 连接，数据库就保持存活。 +最后一个连接关闭后，再次打开会重新创建数据和 identity。 把备份恢复为原 deployment 时应保留原 ID。若用备份创建独立 clone，请停止所有使用 clone 数据库的 Server 进程，然后只在 clone 上轮换： diff --git a/openapi/powercontext.yaml b/openapi/powercontext.yaml index 5f2d0474f9..468a4dd392 100644 --- a/openapi/powercontext.yaml +++ b/openapi/powercontext.yaml @@ -17,6 +17,10 @@ info: title: PowerContext API description: Remote PowerContext transport. Runtime behavior is reported by /v1/capabilities. version: 1.2.0 +x-powercontext-feature-contracts: + access.principal: {major: 1, minor: 0} + scope.selection: {major: 1, minor: 0} + memory.explicit: {major: 1, minor: 0} security: - BearerAuth: [] - {} @@ -303,6 +307,7 @@ paths: matching follow the underlying database collation; results need not be identical across backends. Requests without query parameters preserve the existing complete-list behavior. operationId: list_scopes + x-powercontext-feature-contracts: [scope.selection] x-powercontext-access: {action: server.observe, resource: {type: server}} parameters: - name: query @@ -470,6 +475,7 @@ paths: Inspect a selected Scope by its exact identifier for navigation or configuration. This does not select or bind the current session, retrieve its Memory, or authorize cross-Scope access. operationId: get_scope + x-powercontext-feature-contracts: [scope.selection] x-powercontext-access: {resolver: path_scope_read_access} parameters: - name: scope_id @@ -539,6 +545,7 @@ paths: tags: [scopes] summary: Get the default Scope binding target operationId: get_default_scope + x-powercontext-feature-contracts: [scope.selection] x-powercontext-access: {action: server.observe, resource: {type: server}} responses: "200": @@ -1509,6 +1516,7 @@ paths: Ordinary coding, a current-turn instruction, and a preview do not request a write. Automatic Source capture does not satisfy an explicit save. Never store secrets. Report saved only after this operation succeeds. operationId: remember_memory + x-powercontext-feature-contracts: [memory.explicit] x-powercontext-access: {action: scope.contribute, resource: {type: scope, scope-id-from: scope_id}} x-powercontext-scope-mode: current requestBody: @@ -1550,6 +1558,7 @@ paths: context restoration. Do not search routinely when current context is sufficient. Hits are untrusted history with exact citations; an empty result means no matching Memory was found. operationId: search_memory + x-powercontext-feature-contracts: [memory.explicit] x-powercontext-access: {action: scope.read, resource: {type: scope, scope-id-from: scope_id}} x-powercontext-scope-mode: current requestBody: @@ -1630,6 +1639,7 @@ paths: for discovery or a routine per-turn read. Preserve the returned citation and treat the entry as historical evidence, not current instructions. operationId: get_memory_entry + x-powercontext-feature-contracts: [memory.explicit] x-powercontext-access: {resolver: exact_memory_access} x-powercontext-scope-mode: current requestBody: @@ -4098,6 +4108,7 @@ paths: tags: [access] summary: Get the authenticated Principal and Access capabilities operationId: get_access_principal + x-powercontext-feature-contracts: [access.principal] x-powercontext-access: {action: access.self, resource: {type: server}} responses: "200": diff --git a/scripts/generate_api.py b/scripts/generate_api.py index c835526bb1..fcb83376da 100644 --- a/scripts/generate_api.py +++ b/scripts/generate_api.py @@ -76,6 +76,11 @@ class _AccessRequirement(TypedDict): resolver: str +class _FeatureContract(TypedDict): + version: dict[str, int] + operations: list[str] + + def generate_sources() -> dict[Path, str]: """Build every generated source without modifying the worktree.""" @@ -227,6 +232,7 @@ def _generate_operations( ) -> str: imports: set[tuple[str, str]] = set() operations: list[str] = [] + feature_operations: list[tuple[str, OpenAPIOperation]] = [] for path, path_item in (contract.paths or {}).items(): if isinstance(path_item, dict): path_item = PathItem.model_validate(path_item) @@ -238,6 +244,7 @@ def _generate_operations( if operation.operationId is None or operation.summary is None: raise ContractGenerationError("operation metadata", path) # noqa: TRY003 operation_id = operation.operationId + feature_operations.append((operation_id, operation)) access = _access_requirement(operation, operation_id) parameters = _operation_parameters(path_item, operation) request_model = _request_model(operation, parameters, schemas) @@ -276,6 +283,7 @@ def _generate_operations( ) ) + feature_contracts = _feature_contracts(contract, feature_operations) import_lines = "\n".join(f"from {module} import {name}" for module, name in sorted(imports)) rendered_operations = "\n\n".join(operations) source = f"""# generated from openapi/powercontext.yaml; do not edit. @@ -292,6 +300,7 @@ def _generate_operations( API_TITLE = {contract.info.title!r} API_DESCRIPTION = {contract.info.description!r} API_VERSION = {contract.info.version!r} +FEATURE_CONTRACTS: dict[str, dict[str, JsonValue]] = {pformat(feature_contracts, sort_dicts=False)} RequestT = TypeVar("RequestT") ResponseT = TypeVar("ResponseT") @@ -331,6 +340,41 @@ class AccessRequirement(BaseModel): return f"{formatter.format_code(source).rstrip()}\n" +def _feature_contracts( + contract: OpenAPI, operations: list[tuple[str, OpenAPIOperation]] +) -> dict[str, _FeatureContract]: + """Validate and collect feature versions and membership from the wire contract.""" + + versions = (contract.model_extra or {}).get("x-powercontext-feature-contracts", {}) + if not isinstance(versions, dict): + raise ContractGenerationError("x-powercontext-feature-contracts", versions) + features: dict[str, _FeatureContract] = {} + for name, version in versions.items(): + if ( + not isinstance(name, str) + or not name.strip() + or not isinstance(version, dict) + or set(version) != {"major", "minor"} + or any(type(value) is not int or value < 0 for value in version.values()) + ): + raise ContractGenerationError("feature version", {name: version}) # noqa: TRY003 + features[name] = {"version": version, "operations": []} + for operation_id, operation in operations: + memberships = (operation.model_extra or {}).get("x-powercontext-feature-contracts", []) + if ( + not isinstance(memberships, list) + or any(not isinstance(name, str) or name not in features for name in memberships) + or len(memberships) != len(set(memberships)) + ): + raise ContractGenerationError(f"feature membership for {operation_id}", memberships) # noqa: TRY003 + for name in memberships: + features[name]["operations"].append(operation_id) + for name, feature in features.items(): + if not feature["operations"]: + raise ContractGenerationError("feature without operations", name) # noqa: TRY003 + return features + + def _generate_schema(contract: dict[str, JsonValue]) -> str: source = f"""# generated from openapi/powercontext.yaml; do not edit. diff --git a/src/powercontext/builtin/runtime/application.py b/src/powercontext/builtin/runtime/application.py index aa9c7d81fe..1da5906fdb 100644 --- a/src/powercontext/builtin/runtime/application.py +++ b/src/powercontext/builtin/runtime/application.py @@ -138,6 +138,7 @@ ArtifactGovernance, ArtifactLifecycleState, ) +from powercontext.builtin.persistence.database import AsyncDatabase from powercontext.builtin.persistence.skill_publications import SkillPublication from powercontext.builtin.publication import ArtifactPublicationApplication from powercontext.builtin.records import ( @@ -435,6 +436,7 @@ class _RuntimeStateError(RuntimeError): def __init__(self, code: str) -> None: messages = { "closed": "Built-in Runtime is closed", + "database": "Primary database is not configured", "empty-write": "explicit Memory write did not produce a Memory", "experience-incubation": "Experience incubation is not configured", "external-skill-registry": "External Skill Registry is not configured", @@ -2930,6 +2932,7 @@ def __init__( *, provider: PowerContextProvider[BuiltinSources, BuiltinArtifacts, BuiltinTriggers], capabilities: RuntimeCapabilities, + primary_database: AsyncDatabase | None = None, code_service: CodeService | None = None, source_window_limit: int = 100, context_assembly_max_entries: int = 8, @@ -2987,6 +2990,7 @@ def __init__( if scope_cache_size < 1: raise _RuntimeConfigurationError("scope_cache_size") self._provider = provider + self._primary_database = primary_database self._capabilities = capabilities self._review_service = review_service self.profiles = profiles @@ -3075,6 +3079,14 @@ def __init__( async def __aenter__(self) -> BuiltinRuntime: return self + @property + def primary_database(self) -> AsyncDatabase: + """Borrow the primary database while the composed Runtime remains open.""" + + if self._primary_database is None: + raise _RuntimeStateError("database") + return self._primary_database + async def __aexit__(self, exc_type: object, exc_value: object, traceback: object) -> None: await self.close() diff --git a/src/powercontext/builtin/runtime/composition.py b/src/powercontext/builtin/runtime/composition.py index a6a5fe2ce9..f8ef69eac5 100644 --- a/src/powercontext/builtin/runtime/composition.py +++ b/src/powercontext/builtin/runtime/composition.py @@ -469,6 +469,7 @@ async def run_profile(scope_id, high): BuiltinRuntime( code_service=await resources.enter_async_context(open_code_service(config.code, config.database)), provider=contexts, + primary_database=contexts.database, capabilities=RuntimeCapabilities( memory_extraction=contexts.memory_extraction, experience_generation=contexts.experience_generation, diff --git a/src/powercontext/http/_generated/operations.py b/src/powercontext/http/_generated/operations.py index aac94afdea..fc1b7dda5f 100644 --- a/src/powercontext/http/_generated/operations.py +++ b/src/powercontext/http/_generated/operations.py @@ -179,6 +179,17 @@ API_TITLE = "PowerContext API" API_DESCRIPTION = "Remote PowerContext transport. Runtime behavior is reported by /v1/capabilities." API_VERSION = "1.2.0" +FEATURE_CONTRACTS: dict[str, dict[str, JsonValue]] = { + "access.principal": {"version": {"major": 1, "minor": 0}, "operations": ["get_access_principal"]}, + "scope.selection": { + "version": {"major": 1, "minor": 0}, + "operations": ["list_scopes", "get_scope", "get_default_scope"], + }, + "memory.explicit": { + "version": {"major": 1, "minor": 0}, + "operations": ["remember_memory", "search_memory", "get_memory_entry"], + }, +} RequestT = TypeVar("RequestT") ResponseT = TypeVar("ResponseT") diff --git a/src/powercontext/http/_generated/schema.py b/src/powercontext/http/_generated/schema.py index 6b7cc1ef16..fcc008bb93 100644 --- a/src/powercontext/http/_generated/schema.py +++ b/src/powercontext/http/_generated/schema.py @@ -254,6 +254,7 @@ "query parameters preserve the existing " "complete-list behavior.", "operationId": "list_scopes", + "x-powercontext-feature-contracts": ["scope.selection"], "x-powercontext-access": {"action": "server.observe", "resource": {"type": "server"}}, "parameters": [ {"name": "query", "in": "query", "required": False, "schema": {"type": "string", "maxLength": 256}}, @@ -424,6 +425,7 @@ "its Memory, or authorize cross-Scope " "access.", "operationId": "get_scope", + "x-powercontext-feature-contracts": ["scope.selection"], "x-powercontext-access": {"resolver": "path_scope_read_access"}, "parameters": [ { @@ -490,6 +492,7 @@ "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/Unavailable"}, }, + "x-powercontext-feature-contracts": ["scope.selection"], "x-powercontext-access": {"action": "server.observe", "resource": {"type": "server"}}, }, "put": { @@ -1563,6 +1566,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-feature-contracts": ["memory.explicit"], "x-powercontext-access": { "action": "scope.contribute", "resource": {"type": "scope", "scope-id-from": "scope_id"}, @@ -1608,6 +1612,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-feature-contracts": ["memory.explicit"], "x-powercontext-access": { "action": "scope.read", "resource": {"type": "scope", "scope-id-from": "scope_id"}, @@ -1695,6 +1700,7 @@ "503": {"$ref": "#/components/responses/Unavailable"}, "500": {"$ref": "#/components/responses/InternalError"}, }, + "x-powercontext-feature-contracts": ["memory.explicit"], "x-powercontext-access": {"resolver": "exact_memory_access"}, "x-powercontext-scope-mode": "current", } @@ -4339,6 +4345,7 @@ "403": {"$ref": "#/components/responses/Forbidden"}, "503": {"$ref": "#/components/responses/Unavailable"}, }, + "x-powercontext-feature-contracts": ["access.principal"], "x-powercontext-access": {"action": "access.self", "resource": {"type": "server"}}, } }, @@ -10047,4 +10054,9 @@ }, }, "security": [{"BearerAuth": []}, {}], + "x-powercontext-feature-contracts": { + "access.principal": {"major": 1, "minor": 0}, + "scope.selection": {"major": 1, "minor": 0}, + "memory.explicit": {"major": 1, "minor": 0}, + }, } diff --git a/src/powercontext/server/factory.py b/src/powercontext/server/factory.py index 1335b28b2c..cda66a7aae 100644 --- a/src/powercontext/server/factory.py +++ b/src/powercontext/server/factory.py @@ -75,7 +75,7 @@ from powercontext.server.cursor_secret import resolve_cursor_secret from powercontext.server.dashboard import mount_dashboard from powercontext.server.dream_access import DreamAccess -from powercontext.server.identity import open_server_identity_repository +from powercontext.server.identity import ServerIdentityRepository from powercontext.server.info import server_info from powercontext.server.mcp import mount_mcp from powercontext.server.metrics import CONTENT_TYPE_LATEST, HttpMetricsMiddleware, ServerMetrics @@ -178,8 +178,6 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: ) cursor_secret = resolve_cursor_secret(config.database, configured_cursor_secret) async with AsyncExitStack() as resources: - async with open_server_identity_repository(config.database) as identity_repository: - server_id = await identity_repository.load_or_create() active_access_control = configured_access_control if active_access_control is None and resolved.access.mode == "enforced": active_access_control = await resources.enter_async_context( @@ -245,6 +243,9 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: ), ) ) + identity_repository = ServerIdentityRepository(runtime.primary_database) + await identity_repository.initialize() + server_id = await identity_repository.load_or_create() _bind_dream_access(dream_access, runtime) if active_access_control is not None: migrated, unresolved = await runtime._records().migrate_handoff_receipts( diff --git a/src/powercontext/server/identity.py b/src/powercontext/server/identity.py index 600650532a..886c93ebf0 100644 --- a/src/powercontext/server/identity.py +++ b/src/powercontext/server/identity.py @@ -49,6 +49,12 @@ def __init__(self, database: AsyncDatabase, *, id_factory: Callable[[], str] | N self._database = database self._id_factory = (lambda: str(uuid4())) if id_factory is None else id_factory + async def initialize(self) -> None: + """Create the identity schema safely across concurrent initializers.""" + + async with self._database.transaction() as connection: + await connection.execute(CreateTable(SERVER_IDENTITY_TABLE, if_not_exists=True)) + async def load_or_create(self) -> str: """Return the durable identity, creating it once across concurrent replicas.""" @@ -109,9 +115,9 @@ async def open_server_identity_repository(config: DatabaseConfig) -> AsyncIterat else: raise TypeError(f"unsupported Server identity database: {type(config).__name__}") # noqa: TRY003 async with opened as profile: - async with profile.database.transaction() as connection: - await connection.execute(CreateTable(SERVER_IDENTITY_TABLE, if_not_exists=True)) - yield ServerIdentityRepository(profile.database) + repository = ServerIdentityRepository(profile.database) + await repository.initialize() + yield repository __all__ = ("SERVER_IDENTITY_TABLE", "ServerIdentityRepository", "open_server_identity_repository") diff --git a/src/powercontext/server/info.py b/src/powercontext/server/info.py index c8c5f83dd2..fcb1ddcc07 100644 --- a/src/powercontext/server/info.py +++ b/src/powercontext/server/info.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Authoritative static discovery contract for the PowerContext Server.""" +"""Project the generated discovery contract for the PowerContext Server.""" from __future__ import annotations @@ -21,23 +21,9 @@ from packaging.version import Version from powercontext.http import ServerInfo -from powercontext.http._generated.operations import API_VERSION +from powercontext.http._generated.operations import API_VERSION, FEATURE_CONTRACTS _SCHEMA_VERSION = {"major": 1, "minor": 0} -_FEATURE_CONTRACTS = { - "access.principal": { - "version": {"major": 1, "minor": 0}, - "operations": ["get_access_principal"], - }, - "scope.selection": { - "version": {"major": 1, "minor": 0}, - "operations": ["list_scopes", "get_scope", "get_default_scope"], - }, - "memory.explicit": { - "version": {"major": 1, "minor": 0}, - "operations": ["remember_memory", "search_memory", "get_memory_entry"], - }, -} def server_info(server_id: str) -> ServerInfo: @@ -50,7 +36,7 @@ def server_info(server_id: str) -> ServerInfo: "server_id": server_id, "package_version": version("powercontext"), "api_contract_version": {"major": api_version.major, "minor": api_version.minor}, - "feature_contracts": _FEATURE_CONTRACTS, + "feature_contracts": FEATURE_CONTRACTS, }) diff --git a/tests/test_api_contract.py b/tests/test_api_contract.py index 32f4b80c0a..2110603b4a 100644 --- a/tests/test_api_contract.py +++ b/tests/test_api_contract.py @@ -219,18 +219,23 @@ def test_server_info_contract_is_observable_and_forward_compatible() -> None: assert parsed.server_id == "server-a" -def test_server_info_feature_contracts_name_existing_openapi_operations() -> None: +def test_server_info_feature_contracts_match_openapi_versions_and_membership() -> None: contract = yaml.safe_load(CONTRACT_PATH.read_text()) - operation_ids = { - operation["operationId"] for path_item in contract["paths"].values() for operation in path_item.values() - } - advertised = { - operation_id - for feature in server_info("server-a").feature_contracts.values() - for operation_id in feature.operations + expected = { + name: { + "version": version, + "operations": [ + operation["operationId"] + for path_item in contract["paths"].values() + for operation in path_item.values() + if name in operation.get("x-powercontext-feature-contracts", []) + ], + } + for name, version in contract["x-powercontext-feature-contracts"].items() } - - assert advertised <= operation_ids + assert { + name: feature.model_dump() for name, feature in server_info("server-a").feature_contracts.items() + } == expected def test_contract_declares_server_and_remote_target_bearer_boundaries() -> None: diff --git a/tests/test_api_generation.py b/tests/test_api_generation.py index ab16bb7e69..92f50510c7 100644 --- a/tests/test_api_generation.py +++ b/tests/test_api_generation.py @@ -14,9 +14,12 @@ from __future__ import annotations +import ast import importlib.util from pathlib import Path +import pytest + REPO_ROOT = Path(__file__).resolve().parents[1] @@ -68,3 +71,75 @@ def test_path_and_header_parameters_do_not_create_a_query_model_for_no_content_s assert "request_location=None" in source assert "response_type=None" in source assert "success_status=204" in source + + +@pytest.fixture +def feature_contract(): + return { + "openapi": "3.0.3", + "info": {"title": "Test API", "version": "1.0.0"}, + "x-powercontext-feature-contracts": { + "scope.selection": {"major": 1, "minor": 0}, + "memory.explicit": {"major": 1, "minor": 0}, + }, + "paths": { + path: { + "get": { + "summary": operation_id, + "operationId": operation_id, + "responses": {"204": {"description": "Done."}}, + "x-powercontext-feature-contracts": [feature], + } + } + for path, operation_id, feature in ( + ("/scopes", "list_scopes", "scope.selection"), + ("/memory", "search_memory", "memory.explicit"), + ) + }, + } + + +def test_generation_projects_explicit_feature_versions_and_operation_membership(feature_contract) -> None: + generator = _load_generator() + feature_contract["x-powercontext-feature-contracts"]["scope.selection"]["minor"] = 2 + feature_contract["paths"]["/memory"]["get"]["x-powercontext-feature-contracts"] = [ + "scope.selection", + "memory.explicit", + ] + source = generator._generate_operations(generator.OpenAPI.model_validate(feature_contract), {}) + assignment = next( + node + for node in ast.parse(source).body + if isinstance(node, ast.AnnAssign) + and isinstance(node.target, ast.Name) + and node.target.id == "FEATURE_CONTRACTS" + ) + assert assignment.value is not None + assert ast.literal_eval(assignment.value) == { + "scope.selection": {"version": {"major": 1, "minor": 2}, "operations": ["list_scopes", "search_memory"]}, + "memory.explicit": {"version": {"major": 1, "minor": 0}, "operations": ["search_memory"]}, + } + + +@pytest.mark.parametrize( + ("invalid", "value"), + [ + ("version", -1), + ("version", True), + ("membership", ["undefined.feature"]), + ("membership", "scope.selection"), + ("membership", ["scope.selection", "scope.selection"]), + ("unused", {"major": 1, "minor": 0}), + ], +) +def test_generation_rejects_invalid_feature_contract_declarations(feature_contract, invalid, value) -> None: + generator = _load_generator() + if invalid == "version": + feature_contract["x-powercontext-feature-contracts"]["scope.selection"]["minor"] = value + elif invalid == "membership": + feature_contract["paths"]["/scopes"]["get"]["x-powercontext-feature-contracts"] = value + else: + feature_contract["x-powercontext-feature-contracts"]["unused"] = value + + with pytest.raises(generator.ContractGenerationError, match="feature"): + generator._generate_operations(generator.OpenAPI.model_validate(feature_contract), {}) diff --git a/tests/test_server.py b/tests/test_server.py index 6007f6ec3d..2407e40595 100644 --- a/tests/test_server.py +++ b/tests/test_server.py @@ -17,7 +17,6 @@ import os import re import shlex -from contextlib import asynccontextmanager from datetime import datetime, timedelta from pathlib import Path from types import SimpleNamespace @@ -308,12 +307,10 @@ def test_server_info_uses_one_durable_identity_across_restarts(tmp_path) -> None def test_server_startup_fails_when_identity_initialization_fails(tmp_path, monkeypatch) -> None: - @asynccontextmanager - async def unavailable_identity(_config): + async def unavailable_identity(_repository): raise OSError("identity backend unavailable") # noqa: TRY003 - yield - monkeypatch.setattr("powercontext.server.factory.open_server_identity_repository", unavailable_identity) + monkeypatch.setattr("powercontext.server.identity.ServerIdentityRepository.initialize", unavailable_identity) app = create_server_app( settings=ServerSettings( database=SQLiteConfig(url=f"sqlite+aiosqlite:///{tmp_path / 'runtime.db'}"), @@ -326,6 +323,33 @@ async def unavailable_identity(_config): pass +def test_servers_sharing_memory_scopes_share_identity_for_the_database_lifetime(tmp_path) -> None: + settings = ServerSettings( + database=SQLiteConfig(url=f"sqlite+aiosqlite:///file:{tmp_path / 'shared'}?mode=memory&cache=shared&uri=true"), + auth=BearerAuthConfig(enabled=False), + mcp=McpConfig(enabled=False), + ) + + with TestClient(create_server_app(settings=settings)) as first: + original_id = first.get("/v1/server-info").json()["server_id"] + created = first.post( + "/v1/scopes", + json={"title": "Shared Scope", "summary": "Shared deployment data", "idempotency_key": "shared-scope"}, + ) + assert created.status_code == 201 + scope_id = created.json()["scope_id"] + with TestClient(create_server_app(settings=settings)) as second: + assert second.get(f"/v1/scopes/{scope_id}").json() == created.json() + assert second.get("/v1/server-info").json()["server_id"] == original_id + + assert first.get("/v1/server-info").json()["server_id"] == original_id + assert first.get(f"/v1/scopes/{scope_id}").status_code == 200 + + with TestClient(create_server_app(settings=settings)) as reopened: + assert reopened.get(f"/v1/scopes/{scope_id}").status_code == 404 + assert reopened.get("/v1/server-info").json()["server_id"] != original_id + + def test_server_settings_use_configured_workspace_for_default_skill_targets(tmp_path, monkeypatch) -> None: monkeypatch.setenv("POWERCONTEXT_SERVER_WORKSPACE", str(tmp_path)) monkeypatch.delenv("POWERCONTEXT_SERVER_EXTERNAL_SKILLS", raising=False) From d0872c4946d1103691eb93dfc121909361ed94e1 Mon Sep 17 00:00:00 2001 From: wutongyuonce <147830929+wutongyuonce@users.noreply.github.com> Date: Mon, 28 Sep 2026 21:18:10 +0800 Subject: [PATCH 7/8] fix(server): validate effective SQLite URIs and feature versions Classify memory storage using dialect connection arguments and decoded SQLite URIs so offline reset cannot claim a nonpersistent rotation. Reject feature major zero during generation, matching the discovery model. Extend existing regressions and document both validation boundaries. --- docs/en/development/remote-access-implementation.md | 11 +++++++---- docs/zh/development/remote-access-implementation.md | 6 ++++-- scripts/generate_api.py | 1 + .../builtin/persistence/sqlite/profile.py | 13 +++++++++---- tests/builtin/persistence/test_sqlite_profile.py | 9 +++++++-- tests/test_api_generation.py | 11 +++++++---- tests/test_cli.py | 13 +++++++++---- 7 files changed, 44 insertions(+), 20 deletions(-) diff --git a/docs/en/development/remote-access-implementation.md b/docs/en/development/remote-access-implementation.md index b3772ad20d..0e4c77e70c 100644 --- a/docs/en/development/remote-access-implementation.md +++ b/docs/en/development/remote-access-implementation.md @@ -108,8 +108,8 @@ version, API contract version, response schema version, and initial feature cont health, enabled runtime capabilities, limits, inventory, secrets, filesystem paths, or the authenticated principal. Use the dedicated health, capabilities, statistics, and access endpoints for those concerns. -All discovery versions use `major` and `minor` integers. A major increment may remove or incompatibly change the -governed contract; a minor increment is backward compatible. The response `schema_version` governs its fields and +All discovery versions use integers with `major >= 1` and `minor >= 0`. A major increment may remove or incompatibly +change the governed contract; a minor increment is backward compatible. The response `schema_version` governs its fields and semantics, while `api_contract_version` is the major/minor projection of the OpenAPI `info.version`. Each feature contract version applies only to its listed OpenAPI operation IDs: adding an operation or compatible semantics increments minor; removing, renaming, or incompatibly changing a listed operation increments major. Compatible clients must ignore @@ -117,8 +117,8 @@ unknown optional fields introduced by a schema minor version. OpenAPI's root `x-powercontext-feature-contracts` declares the explicit feature versions. Each governed operation lists its membership in the same extension; `make api-generate` produces the discovery metadata from those declarations. -Generation rejects invalid versions, unknown or duplicate memberships, and features without operations. Version bumps -remain an explicit contract edit, not an automatic consequence of changing membership. +Generation rejects invalid versions (including values outside these bounds), unknown or duplicate memberships, and +features without operations. Version bumps remain an explicit contract edit, not an automatic consequence of changing membership. The Server stores one identity singleton using the Runtime-owned primary relational database. Startup creates the identity table idempotently, then atomically creates or loads the singleton, so concurrent initializers converge on one ID and @@ -127,6 +127,9 @@ initialization or loading fails, Server startup fails before readiness instead o in-memory SQLite deployment, including SQLite URI memory mode, receives a new ID with each database lifetime because it has no durable store. Applications using the same shared-memory SQLite database share both data and identity while any Runtime connection keeps that database alive; after the last connection closes, reopening creates new data and identity. +Memory classification uses the dialect's effective connection arguments and the decoded SQLite URI, including supported +true spellings (`true`, `1`, `yes`, `on`) and percent-encoded `:memory:` paths. Pooling and offline maintenance guards +consume the same `SQLiteConfig.is_in_memory` classification. Treat a restored backup as the same deployment and keep its ID. When a backup is used to create an independent clone, stop every Server process using the clone database and rotate only the clone: diff --git a/docs/zh/development/remote-access-implementation.md b/docs/zh/development/remote-access-implementation.md index b624144204..cf0d62acdd 100644 --- a/docs/zh/development/remote-access-implementation.md +++ b/docs/zh/development/remote-access-implementation.md @@ -104,14 +104,14 @@ contract version、response schema version 和首批 feature contract。它刻 capability、limit、inventory、secret、文件系统 path 或已认证 principal；这些信息分别由 health、capabilities、 statistics 和 access endpoint 负责。 -所有 discovery version 都使用 `major` 和 `minor` 整数。major 增加表示受管契约可能被移除或发生不兼容变化；minor +所有 discovery version 都使用 `major >= 1` 和 `minor >= 0` 的整数。major 增加表示受管契约可能被移除或发生不兼容变化；minor 增加只允许向后兼容的扩展。response 的 `schema_version` 管理字段与语义，`api_contract_version` 是 OpenAPI `info.version` 的 major/minor 投影。每个 feature contract version 只约束它列出的 OpenAPI operation ID：增加 operation 或兼容语义时增加 minor，移除、重命名或不兼容地改变已列 operation 时增加 major。兼容 client 必须忽略 schema minor version 新增的未知可选字段。 OpenAPI 根级 `x-powercontext-feature-contracts` 显式声明 feature version，各受管 operation 使用同名扩展声明归属。 -`make api-generate` 从这些声明生成 discovery metadata，并拒绝非法版本、未知或重复归属及没有 operation 的 feature。 +`make api-generate` 从这些声明生成 discovery metadata，并拒绝超出上述范围的版本、未知或重复归属及没有 operation 的 feature。 版本号仍须显式修改，不会因归属变化而自动增加。 Server 使用 Runtime 持有的主关系数据库保存一条 identity singleton。启动时先幂等创建 identity table，再原子创建或读取 @@ -120,6 +120,8 @@ singleton，因此并发 initializer 会收敛到同一 ID，进程重启、pack 临时 identity。内存 SQLite（包括 SQLite URI memory mode）没有持久存储，所以每个数据库生命周期都会获得新 ID。 使用同一共享内存 SQLite 数据库的 application 会共享数据和 identity；只要仍有 Runtime 连接，数据库就保持存活。 最后一个连接关闭后，再次打开会重新创建数据和 identity。 +内存分类使用 dialect 的实际连接参数和解码后的 SQLite URI，包括支持的 true 拼写（`true`、`1`、`yes`、`on`）以及 +百分号编码的 `:memory:` path。连接池选择和离线维护检查统一使用 `SQLiteConfig.is_in_memory` 的分类结果。 把备份恢复为原 deployment 时应保留原 ID。若用备份创建独立 clone，请停止所有使用 clone 数据库的 Server 进程，然后只在 clone 上轮换： diff --git a/scripts/generate_api.py b/scripts/generate_api.py index fcb83376da..9764c6c460 100644 --- a/scripts/generate_api.py +++ b/scripts/generate_api.py @@ -356,6 +356,7 @@ def _feature_contracts( or not isinstance(version, dict) or set(version) != {"major", "minor"} or any(type(value) is not int or value < 0 for value in version.values()) + or version["major"] < 1 ): raise ContractGenerationError("feature version", {name: version}) # noqa: TRY003 features[name] = {"version": version, "operations": []} diff --git a/src/powercontext/builtin/persistence/sqlite/profile.py b/src/powercontext/builtin/persistence/sqlite/profile.py index eb59d4bdd3..c4790012a1 100644 --- a/src/powercontext/builtin/persistence/sqlite/profile.py +++ b/src/powercontext/builtin/persistence/sqlite/profile.py @@ -21,6 +21,7 @@ from contextlib import asynccontextmanager from pathlib import Path from typing import Literal +from urllib.parse import parse_qs, unquote, urlsplit from weakref import WeakKeyDictionary import sqlite_vec @@ -106,11 +107,15 @@ async def open( def _is_memory_url(value: str) -> bool: url = make_url(value) - database = url.database - if database in {None, "", ":memory:"}: + # Match the driver's effective URI flag and filename, including boolean aliases. + args, options = url.get_dialect()().create_connect_args(url) + filename = str(args[0]) + if filename == ":memory:": return True - uri = str(url.query.get("uri", "")).casefold() == "true" - return uri and (database == "file::memory:" or str(url.query.get("mode", "")).casefold() == "memory") + if not options.get("uri"): + return False + uri = urlsplit(filename) + return uri.scheme == "file" and (unquote(uri.path) == ":memory:" or parse_qs(uri.query).get("mode") == ["memory"]) def _create_database_directory(value: str) -> None: diff --git a/tests/builtin/persistence/test_sqlite_profile.py b/tests/builtin/persistence/test_sqlite_profile.py index 8c4d60bde2..0d75ed30e0 100644 --- a/tests/builtin/persistence/test_sqlite_profile.py +++ b/tests/builtin/persistence/test_sqlite_profile.py @@ -39,15 +39,20 @@ def test_sqlite_config_requires_the_async_dialect() -> None: [ "sqlite+aiosqlite:///:memory:", "sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=true", + "sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=1", + "sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=yes", + "sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=on", "sqlite+aiosqlite:///file::memory:?cache=shared&uri=true", + "sqlite+aiosqlite:///file:%3Amemory%3A?cache=shared&uri=true", ], ) def test_sqlite_config_recognizes_memory_urls(url: str) -> None: assert SQLiteConfig(url=url).is_in_memory -def test_sqlite_config_does_not_treat_uri_like_filename_as_memory_without_uri_mode() -> None: - assert not SQLiteConfig(url="sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared").is_in_memory +@pytest.mark.parametrize("uri", ["", "&uri=false", "&uri=0", "&uri=no", "&uri=off"]) +def test_sqlite_config_does_not_treat_uri_like_filename_as_memory_without_uri_mode(uri: str) -> None: + assert not SQLiteConfig(url=f"sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared{uri}").is_in_memory def test_sqlite_profile_creates_a_missing_database_directory(tmp_path) -> None: diff --git a/tests/test_api_generation.py b/tests/test_api_generation.py index 92f50510c7..461d0ae26a 100644 --- a/tests/test_api_generation.py +++ b/tests/test_api_generation.py @@ -124,8 +124,11 @@ def test_generation_projects_explicit_feature_versions_and_operation_membership( @pytest.mark.parametrize( ("invalid", "value"), [ - ("version", -1), - ("version", True), + ("major", 0), + ("major", -1), + ("major", True), + ("minor", -1), + ("minor", True), ("membership", ["undefined.feature"]), ("membership", "scope.selection"), ("membership", ["scope.selection", "scope.selection"]), @@ -134,8 +137,8 @@ def test_generation_projects_explicit_feature_versions_and_operation_membership( ) def test_generation_rejects_invalid_feature_contract_declarations(feature_contract, invalid, value) -> None: generator = _load_generator() - if invalid == "version": - feature_contract["x-powercontext-feature-contracts"]["scope.selection"]["minor"] = value + if invalid in {"major", "minor"}: + feature_contract["x-powercontext-feature-contracts"]["scope.selection"][invalid] = value elif invalid == "membership": feature_contract["paths"]["/scopes"]["get"]["x-powercontext-feature-contracts"] = value else: diff --git a/tests/test_cli.py b/tests/test_cli.py index af6a44636b..9999ea5350 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -652,11 +652,16 @@ def test_server_identity_reset_requires_offline_confirmation_and_rotates(tmp_pat assert first.output.strip() != second.output.strip() -def test_server_identity_reset_rejects_sqlite_memory_uri(tmp_path) -> None: +@pytest.mark.parametrize( + "url", + [ + "sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=1", + "sqlite+aiosqlite:///file:%3Amemory%3A?cache=shared&uri=true", + ], +) +def test_server_identity_reset_rejects_sqlite_memory_uri(tmp_path, url: str) -> None: environment = tmp_path / "server.env" - environment.write_text( - "POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=true\n" - ) + environment.write_text(f"POWERCONTEXT_SERVER_DATABASE_URL={url}\n") result = CliRunner().invoke( create_cli([server_app]), From 633823bfa625b17a22a42bce591d2c62748f262a Mon Sep 17 00:00:00 2001 From: wutongyuonce <147830929+wutongyuonce@users.noreply.github.com> Date: Sat, 10 Oct 2026 19:08:12 +0800 Subject: [PATCH 8/8] fix(server): honor native SQLite durability and recover identity locks Classify persistence from SQLite's own URI rules so offline reset cannot report an identity that disappears on reopen. Retry only busy and locked errors across the complete identity initialization, and keep that classification in the SQLite adapter. --- .../remote-access-implementation.md | 24 ++++-- .../remote-access-implementation.md | 15 +++- .../builtin/persistence/sqlite/__init__.py | 3 +- .../builtin/persistence/sqlite/profile.py | 50 ++++++++---- .../builtin/runtime/composition.py | 2 +- src/powercontext/server/cli.py | 4 +- src/powercontext/server/cursor_secret.py | 2 +- src/powercontext/server/identity.py | 41 ++++++++-- .../persistence/test_sqlite_profile.py | 48 +++++++++++- tests/test_api_contract.py | 16 ---- tests/test_cli.py | 18 ++++- tests/test_server.py | 14 ---- tests/test_server_identity.py | 77 ++++++++++++++++--- 13 files changed, 234 insertions(+), 80 deletions(-) diff --git a/docs/en/development/remote-access-implementation.md b/docs/en/development/remote-access-implementation.md index 48645f0aac..f0fe6c4b07 100644 --- a/docs/en/development/remote-access-implementation.md +++ b/docs/en/development/remote-access-implementation.md @@ -123,13 +123,23 @@ features without operations. Version bumps remain an explicit contract edit, not The Server stores one identity singleton using the Runtime-owned primary relational database. Startup creates the identity table idempotently, then atomically creates or loads the singleton, so concurrent initializers converge on one ID and restarts, package upgrades, backup restore, and replicas sharing that database retain it. If identity schema -initialization or loading fails, Server startup fails before readiness instead of publishing a temporary identity. An -in-memory SQLite deployment, including SQLite URI memory mode, receives a new ID with each database lifetime because it -has no durable store. Applications using the same shared-memory SQLite database share both data and identity while any +initialization or loading fails, Server startup fails before readiness instead of publishing a temporary identity. +The identity repository retries only SQLite busy/locked errors, replaying the complete schema or singleton operation +after rollback. It admits retries for up to five seconds with 50 ms waits; each SQL attempt also retains the driver's +configured busy timeout. Exhaustion and all other errors propagate; offline rotation is not retried. +An in-memory or temporary SQLite deployment receives a new ID with each database lifetime because it has no durable store. Applications using the same shared-memory SQLite database share both data and identity while any Runtime connection keeps that database alive; after the last connection closes, reopening creates new data and identity. -Memory classification uses the dialect's effective connection arguments and the decoded SQLite URI, including supported -true spellings (`true`, `1`, `yes`, `on`) and percent-encoded `:memory:` paths. Pooling and offline maintenance guards -consume the same `SQLiteConfig.is_in_memory` classification. +SQLite storage classification uses the dialect's effective connection arguments and the decoded SQLite URI, including +supported true spellings (`true`, `1`, `yes`, `on`), percent-encoded `:memory:` paths, and the built-in `vfs=memdb` +in-memory filesystem. Empty-path file URIs such as +`file:?uri=true` and `file:?cache=shared&uri=true` create connection-local temporary databases, not durable files. +Classification also honors SQLite's decoded NUL termination for filenames and query parameter names/values: +`file:%00tail?uri=true` is temporary, an encoded `:memory:` followed by `%00` remains memory storage, and +`mode=memory%2500tail` or `mode%2500tail=memory` in a SQLAlchemy URL still selects native memory mode. Only an exact lowercase `file:` prefix enables +SQLite URI interpretation; uppercase schemes, leading spaces, and literal filename controls are not normalized. +`SQLiteConfig.is_in_memory` distinguishes memory storage; `SQLiteConfig.is_persistent` excludes both memory and temporary +storage. Pooling keeps one connection for nonpersistent storage; offline maintenance, cursor-secret persistence, and +subprocess workers consume that same persistence classification. The unified migration implementation from [RFC #1771](../rfcs/1771-unified-database-migrations.md) currently covers only a registered four-table Artifact bundle. It does not manage `pc_server_identity`, gate ordinary Server @@ -150,7 +160,7 @@ stop every Server process using the clone database and rotate only the clone: uv run powercontext server identity-reset --env-file /path/to/clone.env --maintenance-confirmed ``` -The command refuses in-memory databases and requires the explicit maintenance confirmation. It cannot detect active +The command refuses in-memory and temporary databases and requires the explicit maintenance confirmation. It cannot detect active replicas, so stopping them is an operator precondition. Logical application-data imports do not copy the identity unless the `pc_server_identity` table itself is included. diff --git a/docs/zh/development/remote-access-implementation.md b/docs/zh/development/remote-access-implementation.md index 6bbb0d9f38..7c70469b80 100644 --- a/docs/zh/development/remote-access-implementation.md +++ b/docs/zh/development/remote-access-implementation.md @@ -117,11 +117,18 @@ OpenAPI 根级 `x-powercontext-feature-contracts` 显式声明 feature version Server 使用 Runtime 持有的主关系数据库保存一条 identity singleton。启动时先幂等创建 identity table，再原子创建或读取 singleton，因此并发 initializer 会收敛到同一 ID，进程重启、package 升级、备份恢复以及共享同一数据库的 replica 也会保持该 ID。identity schema 初始化或读取失败时，Server 会在进入 readiness 之前直接启动失败，而不会发布 -临时 identity。内存 SQLite（包括 SQLite URI memory mode）没有持久存储，所以每个数据库生命周期都会获得新 ID。 +临时 identity。identity repository 只重试 SQLite busy/locked 错误，在事务回滚后重新执行完整的 schema 或 singleton +操作。重试窗口为五秒，每次等待 50 ms；每条 SQL 仍使用 driver 配置的 busy timeout。窗口耗尽或其他错误会直接 +传播，离线轮换不重试。内存或临时 SQLite 没有持久存储，所以每个数据库生命周期都会获得新 ID。 使用同一共享内存 SQLite 数据库的 application 会共享数据和 identity；只要仍有 Runtime 连接，数据库就保持存活。 最后一个连接关闭后，再次打开会重新创建数据和 identity。 -内存分类使用 dialect 的实际连接参数和解码后的 SQLite URI，包括支持的 true 拼写（`true`、`1`、`yes`、`on`）以及 -百分号编码的 `:memory:` path。连接池选择和离线维护检查统一使用 `SQLiteConfig.is_in_memory` 的分类结果。 +SQLite 存储分类使用 dialect 的实际连接参数和解码后的 URI，包括支持的 true 拼写（`true`、`1`、`yes`、`on`）以及 +百分号编码的 `:memory:` path 以及内置的 `vfs=memdb` 内存文件系统。`file:?uri=true` 和 `file:?cache=shared&uri=true` 这类空路径 URI 创建的是连接独占的 +临时数据库，而非持久文件。分类也遵循 SQLite 在解码后的 NUL 处终止文件名和查询参数名/值的行为：`file:%00tail?uri=true` 属于临时存储， +编码后的 `:memory:` 即使后接 `%00` 也仍是内存存储，SQLAlchemy URL 中的 `mode=memory%2500tail` 或 +`mode%2500tail=memory` 也仍会选择原生 memory mode。只有精确的小写 `file:` 前缀才启用 SQLite URI 解释， +不会归一化大写 scheme、前导空格或文件名中的控制字符。`SQLiteConfig.is_in_memory` 区分内存存储；`SQLiteConfig.is_persistent` 同时排除内存与临时 +存储。非持久存储的连接池保留一个连接；离线维护、cursor secret 持久化及子进程 worker 统一使用该持久性分类。 [RFC #1771](../rfcs/1771-unified-database-migrations.md) 对应的统一迁移实现目前只覆盖已注册的四张 Artifact 表。 它尚未管理 `pc_server_identity`、接管普通 Server 启动检查或证明完整 Server readiness；维护命令会拒绝包含未管理表的 @@ -140,7 +147,7 @@ migration readiness marker。 uv run powercontext server identity-reset --env-file /path/to/clone.env --maintenance-confirmed ``` -该命令拒绝内存数据库，并要求显式 maintenance confirmation。它无法检测仍在运行的 replica，因此停服是 operator +该命令拒绝内存和临时数据库，并要求显式 maintenance confirmation。它无法检测仍在运行的 replica，因此停服是 operator 前置条件。逻辑 application-data import 不会复制 identity，除非显式包含 `pc_server_identity` 表。 ## Python Client diff --git a/src/powercontext/builtin/persistence/sqlite/__init__.py b/src/powercontext/builtin/persistence/sqlite/__init__.py index 7e0f4591c7..d04093813d 100644 --- a/src/powercontext/builtin/persistence/sqlite/__init__.py +++ b/src/powercontext/builtin/persistence/sqlite/__init__.py @@ -14,7 +14,7 @@ """SQLite async relational profile.""" -from powercontext.builtin.persistence.sqlite.profile import SQLiteConfig, SQLiteProfile +from powercontext.builtin.persistence.sqlite.profile import SQLiteConfig, SQLiteProfile, is_sqlite_lock_error from powercontext.builtin.persistence.sqlite.topic_memory_index import ( SQLiteTopicMemoryFTSIndex, SQLiteTopicMemoryVectorIndex, @@ -25,4 +25,5 @@ "SQLiteProfile", "SQLiteTopicMemoryFTSIndex", "SQLiteTopicMemoryVectorIndex", + "is_sqlite_lock_error", ) diff --git a/src/powercontext/builtin/persistence/sqlite/profile.py b/src/powercontext/builtin/persistence/sqlite/profile.py index bb4adfd992..4c35dd8885 100644 --- a/src/powercontext/builtin/persistence/sqlite/profile.py +++ b/src/powercontext/builtin/persistence/sqlite/profile.py @@ -17,11 +17,12 @@ from __future__ import annotations import asyncio +import sqlite3 from collections.abc import AsyncIterator, Callable from contextlib import asynccontextmanager from pathlib import Path from typing import Any, Literal, cast -from urllib.parse import parse_qs, unquote, urlsplit +from urllib.parse import parse_qsl, unquote, urlsplit from weakref import WeakKeyDictionary, WeakSet import aiosqlite @@ -69,7 +70,13 @@ def require_async_sqlite(cls, value: str) -> str: def is_in_memory(self) -> bool: """Return whether this profile stores its database only in process memory.""" - return _is_memory_url(self.url) + return _storage_kind(self.url) == "memory" + + @property + def is_persistent(self) -> bool: + """Return whether data survives closing the last connection.""" + + return _storage_kind(self.url) == "persistent" class SQLiteProfile: @@ -92,11 +99,11 @@ async def open( _create_database_directory(config.url) engine_options: dict[str, object] = {"echo": config.echo, "hide_parameters": True} - if config.is_in_memory: + if not config.is_persistent: engine_options["poolclass"] = StaticPool engine = create_async_engine(config.url, **engine_options) _configure_sqlite(engine, config, load_vector_extension=load_vector_extension) - database = AsyncDatabase.own(engine, shared_connection=config.is_in_memory) + database = AsyncDatabase.own(engine, shared_connection=not config.is_persistent) profile = cls(database=database, tables=tables) try: await _warm_sqlite(engine, config) @@ -107,17 +114,26 @@ async def open( await database.close() -def _is_memory_url(value: str) -> bool: +def _storage_kind(value: str) -> Literal["memory", "temporary", "persistent"]: url = make_url(value) # Match the driver's effective URI flag and filename, including boolean aliases. args, options = url.get_dialect()().create_connect_args(url) filename = str(args[0]) if filename == ":memory:": - return True - if not options.get("uri"): - return False - uri = urlsplit(filename) - return uri.scheme == "file" and (unquote(uri.path) == ":memory:" or parse_qs(uri.query).get("mode") == ["memory"]) + return "memory" + if not filename: + return "temporary" + if options.get("uri") and filename.startswith("file:"): + # SQLite recognizes only lowercase file:, and does not strip literal URI controls. + uri = urlsplit(filename.replace("\t", "%09").replace("\n", "%0A").replace("\r", "%0D")) + # SQLite terminates decoded filenames and parameter strings at the first NUL. + path = unquote(uri.path).partition("\0")[0] + parameters = {name.partition("\0")[0]: value.partition("\0")[0] for name, value in parse_qsl(uri.query)} + if path == ":memory:" or parameters.get("mode") == "memory" or parameters.get("vfs") == "memdb": + return "memory" + if not path: + return "temporary" + return "persistent" def _create_database_directory(value: str) -> None: @@ -224,7 +240,7 @@ async def _warm_sqlite(engine: AsyncEngine, config: SQLiteConfig) -> None: await connection.commit() except OperationalError as error: remaining = deadline - loop.time() - if not _database_is_locked(error) or remaining <= 0: + if not is_sqlite_lock_error(error) or remaining <= 0: raise await asyncio.sleep(min(_WARMUP_RETRY_SECONDS, remaining)) else: @@ -232,7 +248,7 @@ async def _warm_sqlite(engine: AsyncEngine, config: SQLiteConfig) -> None: def _warmup_lock(value: str) -> asyncio.Lock: - if _is_memory_url(value): + if _storage_kind(value) != "persistent": return asyncio.Lock() loop = asyncio.get_running_loop() locks = _WARMUP_LOCKS.setdefault(loop, {}) @@ -240,5 +256,11 @@ def _warmup_lock(value: str) -> asyncio.Lock: return locks.setdefault(key, asyncio.Lock()) -def _database_is_locked(error: OperationalError) -> bool: - return "database is locked" in str(error.orig).lower() +def is_sqlite_lock_error(error: OperationalError) -> bool: + """Recognize SQLite contention, including shared-cache table/schema locks.""" + + original = error.orig + return isinstance(original, sqlite3.OperationalError) and (getattr(original, "sqlite_errorcode", 0) & 0xFF) in ( + sqlite3.SQLITE_BUSY, + sqlite3.SQLITE_LOCKED, + ) diff --git a/src/powercontext/builtin/runtime/composition.py b/src/powercontext/builtin/runtime/composition.py index 75cf1bd0ad..0d54cc4cad 100644 --- a/src/powercontext/builtin/runtime/composition.py +++ b/src/powercontext/builtin/runtime/composition.py @@ -788,7 +788,7 @@ def _artifact_processing_bindings( # noqa: C901 - validate and assemble one reg or (family == "memory" and injected_memory_write_gate is not None) ): raise BuiltinConfigurationError("artifact-processing-child-resources") - if isinstance(config.database, SQLiteConfig) and config.database.is_in_memory: + if isinstance(config.database, SQLiteConfig) and not config.database.is_persistent: raise BuiltinConfigurationError("topic-memory-database") prefix = family.replace("-", "_") if family == "topic-memory": diff --git a/src/powercontext/server/cli.py b/src/powercontext/server/cli.py index 760ab41ccf..d1ec86837d 100644 --- a/src/powercontext/server/cli.py +++ b/src/powercontext/server/cli.py @@ -132,7 +132,7 @@ async def _processing_maintenance( manifest = canonical_processing_manifest(config) database = settings.database if isinstance(database, SQLiteConfig): - if database.is_in_memory: + if not database.is_persistent: raise typer.BadParameter("offline migration requires a persistent database") # noqa: TRY003 opened = SQLiteProfile.open(database, tables=()) elif isinstance(database, OceanBaseConfig): @@ -179,7 +179,7 @@ def identity_reset( "identity reset requires --maintenance-confirmed after stopping every Server process" ) with server_settings_context(env_file=env_file) as settings: - if isinstance(settings.database, SQLiteConfig) and settings.database.is_in_memory: + if isinstance(settings.database, SQLiteConfig) and not settings.database.is_persistent: raise typer.BadParameter("identity reset requires a persistent database") # noqa: TRY003 server_id = asyncio.run(_reset_server_identity(settings)) typer.echo(server_id) diff --git a/src/powercontext/server/cursor_secret.py b/src/powercontext/server/cursor_secret.py index be8815fffd..cdb668dc75 100644 --- a/src/powercontext/server/cursor_secret.py +++ b/src/powercontext/server/cursor_secret.py @@ -35,7 +35,7 @@ def resolve_cursor_secret(database: DatabaseConfig, configured_secret: str | Non if configured_secret is not None: return configured_secret.encode() if isinstance(database, SQLiteConfig): - if database.is_in_memory: + if not database.is_persistent: return None database_name = make_url(database.url).database if database_name: diff --git a/src/powercontext/server/identity.py b/src/powercontext/server/identity.py index 886c93ebf0..f98bcc50f1 100644 --- a/src/powercontext/server/identity.py +++ b/src/powercontext/server/identity.py @@ -16,22 +16,27 @@ from __future__ import annotations -from collections.abc import AsyncIterator, Callable +import asyncio +from collections.abc import AsyncIterator, Awaitable, Callable from contextlib import asynccontextmanager +from typing import TypeVar from uuid import uuid4 from sqlalchemy import CheckConstraint, Column, Integer, MetaData, String, Table, insert, select, update -from sqlalchemy.exc import IntegrityError +from sqlalchemy.exc import IntegrityError, OperationalError from sqlalchemy.schema import CreateTable from powercontext.builtin.persistence.database import AsyncDatabase from powercontext.builtin.persistence.oceanbase import OceanBaseConfig, OceanBaseProfile from powercontext.builtin.persistence.seekdb import SeekDBConfig, SeekDBProfile -from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile +from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile, is_sqlite_lock_error from powercontext.builtin.runtime.config import DatabaseConfig _IDENTITY_METADATA = MetaData() _SINGLETON_KEY = 1 +_INITIALIZATION_TIMEOUT_SECONDS = 5.0 +_LOCK_RETRY_SECONDS = 0.05 +_T = TypeVar("_T") SERVER_IDENTITY_TABLE = Table( "pc_server_identity", @@ -45,24 +50,29 @@ class ServerIdentityRepository: """Own the singleton deployment identity in the primary relational backend.""" - def __init__(self, database: AsyncDatabase, *, id_factory: Callable[[], str] | None = None) -> None: + def __init__(self, database: AsyncDatabase) -> None: self._database = database - self._id_factory = (lambda: str(uuid4())) if id_factory is None else id_factory async def initialize(self) -> None: """Create the identity schema safely across concurrent initializers.""" + await _retry_initialization(self._initialize) + + async def _initialize(self) -> None: async with self._database.transaction() as connection: await connection.execute(CreateTable(SERVER_IDENTITY_TABLE, if_not_exists=True)) async def load_or_create(self) -> str: """Return the durable identity, creating it once across concurrent replicas.""" + return await _retry_initialization(self._load_or_create) + + async def _load_or_create(self) -> str: server_id = await self._load() if server_id is not None: return server_id - candidate = self._id_factory() + candidate = str(uuid4()) try: async with self._database.transaction() as connection: await connection.execute( @@ -79,7 +89,7 @@ async def load_or_create(self) -> str: async def rotate(self) -> str: """Replace the identity during an operator-confirmed offline clone procedure.""" - candidate = self._id_factory() + candidate = str(uuid4()) async with self._database.transaction() as connection: result = await connection.execute( update(SERVER_IDENTITY_TABLE) @@ -101,6 +111,23 @@ async def _load(self) -> str | None: return None if value is None else str(value) +async def _retry_initialization(operation: Callable[[], Awaitable[_T]]) -> _T: + # SQLite's busy timeout does not wait for shared-cache table/schema locks. + # Replay only these rolled-back, idempotent initialization operations. + loop = asyncio.get_running_loop() + deadline = loop.time() + _INITIALIZATION_TIMEOUT_SECONDS + while True: + try: + return await operation() + except OperationalError as error: + remaining = deadline - loop.time() + if not is_sqlite_lock_error(error) or remaining <= 0: + raise + await asyncio.sleep(min(_LOCK_RETRY_SECONDS, remaining)) + if loop.time() >= deadline: + raise + + @asynccontextmanager async def open_server_identity_repository(config: DatabaseConfig) -> AsyncIterator[ServerIdentityRepository]: """Open the configured primary database with only the Server identity schema.""" diff --git a/tests/builtin/persistence/test_sqlite_profile.py b/tests/builtin/persistence/test_sqlite_profile.py index de6d283e0f..7dfa29ea9b 100644 --- a/tests/builtin/persistence/test_sqlite_profile.py +++ b/tests/builtin/persistence/test_sqlite_profile.py @@ -399,10 +399,17 @@ def test_sqlite_config_requires_the_async_dialect() -> None: "sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=on", "sqlite+aiosqlite:///file::memory:?cache=shared&uri=true", "sqlite+aiosqlite:///file:%3Amemory%3A?cache=shared&uri=true", + "sqlite+aiosqlite:///file:%3Amemory%3A%00tail?uri=true", + "sqlite+aiosqlite:///file:deployment?mode=memory%2500tail&uri=true", + "sqlite+aiosqlite:///file:deployment?mode%2500tail=memory&uri=true", + "sqlite+aiosqlite:///file:deployment?mode=rwc&mode%2500tail=memory&uri=true", + "sqlite+aiosqlite:///file:deployment?vfs=memdb&uri=true", ], ) def test_sqlite_config_recognizes_memory_urls(url: str) -> None: - assert SQLiteConfig(url=url).is_in_memory + config = SQLiteConfig(url=url) + assert config.is_in_memory + assert not config.is_persistent @pytest.mark.parametrize("uri", ["", "&uri=false", "&uri=0", "&uri=no", "&uri=off"]) @@ -410,6 +417,45 @@ def test_sqlite_config_does_not_treat_uri_like_filename_as_memory_without_uri_mo assert not SQLiteConfig(url=f"sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared{uri}").is_in_memory +@pytest.mark.parametrize( + "filename", + [ + "FILE:deployment?mode=memory", + " file:deployment?mode=memory", + "file::mem\nory:", + "file:deployment?mode=memory&mode%2500tail=rwc", + ], +) +def test_sqlite_config_preserves_persistent_targets(filename: str) -> None: + separator = "&" if "?" in filename else "?" + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{filename}{separator}uri=true") + assert config.is_persistent + assert not config.is_in_memory + + +@pytest.mark.parametrize("uri", ["file:?uri=true", "file:?cache=shared&uri=true", "file:%00tail?uri=true"]) +def test_temporary_sqlite_database_is_connection_local_and_not_persistent(uri: str) -> None: + async def scenario() -> None: + config = SQLiteConfig(url=f"sqlite+aiosqlite:///{uri}") + assert not config.is_in_memory + assert not config.is_persistent + async with SQLiteProfile.open(config, tables=()) as profile: + async with profile.database.transaction() as connection: + await connection.exec_driver_sql("CREATE TABLE probe (value INTEGER)") + await connection.exec_driver_sql("INSERT INTO probe VALUES (1)") + async with profile.database.transaction() as connection: + assert (await connection.exec_driver_sql("SELECT value FROM probe")).scalar_one() == 1 + async with ( + SQLiteProfile.open(config, tables=()) as reopened, + reopened.database.transaction() as connection, + ): + assert ( + await connection.exec_driver_sql("SELECT count(*) FROM sqlite_master WHERE name = 'probe'") + ).scalar_one() == 0 + + asyncio.run(scenario()) + + def test_sqlite_profile_creates_a_missing_database_directory(tmp_path) -> None: async def scenario() -> None: database = tmp_path / "nested" / "powercontext.db" diff --git a/tests/test_api_contract.py b/tests/test_api_contract.py index 623f6905f5..be8048ca2c 100644 --- a/tests/test_api_contract.py +++ b/tests/test_api_contract.py @@ -206,22 +206,6 @@ def test_server_info_contract_is_observable_and_forward_compatible() -> None: ] assert "additionalProperties" not in schema - parsed = http_models.ServerInfo.model_validate({ - "schema_version": {"major": 1, "minor": 0}, - "product": "powercontext", - "server_id": "server-a", - "package_version": "1.2.3", - "api_contract_version": {"major": 1, "minor": 2}, - "feature_contracts": { - "memory.explicit": { - "version": {"major": 1, "minor": 0}, - "operations": ["remember_memory"], - } - }, - "future_optional_field": {"added_in_schema_minor": 1}, - }) - assert parsed.server_id == "server-a" - def test_server_info_feature_contracts_match_openapi_versions_and_membership() -> None: contract = yaml.safe_load(CONTRACT_PATH.read_text()) diff --git a/tests/test_cli.py b/tests/test_cli.py index 9999ea5350..222ee251f5 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -12,6 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. +import asyncio import json import os import subprocess @@ -28,6 +29,7 @@ from typer.testing import CliRunner import powercontext.client.cli as client_cli +from powercontext.builtin.persistence.sqlite import SQLiteConfig from powercontext.cli.app import create_cli from powercontext.client import ServerResponseError from powercontext.client.receiver_service import ReceiverServiceInstallation @@ -68,6 +70,7 @@ UnpublishRemoteSkillRequest, ) from powercontext.server.cli import app as server_app +from powercontext.server.identity import open_server_identity_repository def _empty_inventory() -> dict[str, object]: @@ -651,15 +654,26 @@ def test_server_identity_reset_requires_offline_confirmation_and_rotates(tmp_pat assert first.exit_code == second.exit_code == 0 assert first.output.strip() != second.output.strip() + async def readback() -> str: + async with open_server_identity_repository(SQLiteConfig(url=f"sqlite+aiosqlite:///{database}")) as repository: + return await repository.load_or_create() + + assert asyncio.run(readback()) == second.output.strip() + @pytest.mark.parametrize( "url", [ + "sqlite+aiosqlite:///:memory:", "sqlite+aiosqlite:///file:deployment?mode=memory&cache=shared&uri=1", - "sqlite+aiosqlite:///file:%3Amemory%3A?cache=shared&uri=true", + "sqlite+aiosqlite:///file:?uri=true", + "sqlite+aiosqlite:///file:?cache=shared&uri=true", + "sqlite+aiosqlite:///file:%00tail?uri=true", + "sqlite+aiosqlite:///file:deployment?mode=memory%2500tail&uri=true", + "sqlite+aiosqlite:///file:deployment?vfs=memdb&uri=true", ], ) -def test_server_identity_reset_rejects_sqlite_memory_uri(tmp_path, url: str) -> None: +def test_server_identity_reset_rejects_nonpersistent_sqlite(tmp_path, url: str) -> None: environment = tmp_path / "server.env" environment.write_text(f"POWERCONTEXT_SERVER_DATABASE_URL={url}\n") diff --git a/tests/test_server.py b/tests/test_server.py index 2407e40595..a8765a5ec8 100644 --- a/tests/test_server.py +++ b/tests/test_server.py @@ -290,20 +290,6 @@ def test_server_info_uses_one_durable_identity_across_restarts(tmp_path) -> None assert first.json() == second.json() assert first.json()["schema_version"] == {"major": 1, "minor": 0} assert first.json()["api_contract_version"] == {"major": 1, "minor": 2} - assert first.json()["feature_contracts"] == { - "access.principal": { - "version": {"major": 1, "minor": 0}, - "operations": ["get_access_principal"], - }, - "scope.selection": { - "version": {"major": 1, "minor": 0}, - "operations": ["list_scopes", "get_scope", "get_default_scope"], - }, - "memory.explicit": { - "version": {"major": 1, "minor": 0}, - "operations": ["remember_memory", "search_memory", "get_memory_entry"], - }, - } def test_server_startup_fails_when_identity_initialization_fails(tmp_path, monkeypatch) -> None: diff --git a/tests/test_server_identity.py b/tests/test_server_identity.py index 297e62ba39..845b27a3b1 100644 --- a/tests/test_server_identity.py +++ b/tests/test_server_identity.py @@ -16,12 +16,20 @@ import asyncio import shutil +from contextlib import AsyncExitStack +import pytest +from sqlalchemy import event, insert from sqlalchemy.dialects import mysql +from sqlalchemy.exc import OperationalError from sqlalchemy.schema import CreateTable -from powercontext.builtin.persistence.sqlite import SQLiteConfig -from powercontext.server.identity import SERVER_IDENTITY_TABLE, open_server_identity_repository +from powercontext.builtin.persistence.sqlite import SQLiteConfig, SQLiteProfile +from powercontext.server.identity import ( + SERVER_IDENTITY_TABLE, + ServerIdentityRepository, + open_server_identity_repository, +) def test_server_identity_singleton_key_is_not_auto_incremented_by_mysql_profiles() -> None: @@ -69,16 +77,65 @@ async def initialize() -> str: asyncio.run(scenario()) -def test_in_memory_server_identity_is_stable_only_for_one_open_repository() -> None: +def test_shared_memory_initializers_converge_on_one_identity(tmp_path) -> None: async def scenario() -> None: - config = SQLiteConfig() - async with open_server_identity_repository(config) as repository: - first = await repository.load_or_create() - assert await repository.load_or_create() == first + config = SQLiteConfig(url=f"sqlite+aiosqlite:///file:{tmp_path / 'identity'}?mode=memory&cache=shared&uri=true") + async with AsyncExitStack() as resources: + repositories = [ + await resources.enter_async_context(open_server_identity_repository(config)) for _ in range(8) + ] + identities = await asyncio.gather(*(repository.load_or_create() for repository in repositories)) + assert len(set(identities)) == 1 + assert await repositories[0].load_or_create() == identities[0] + + asyncio.run(scenario()) - async with open_server_identity_repository(config) as repository: - second = await repository.load_or_create() - assert second != first +@pytest.mark.parametrize("phase", ["schema", "read"]) +def test_identity_initialization_recovers_from_locks_but_exhaustion_still_fails(tmp_path, monkeypatch, phase) -> None: + async def scenario() -> None: + config = SQLiteConfig( + url=f"sqlite+aiosqlite:///file:{tmp_path / 'locked'}?mode=memory&cache=shared&uri=true", + busy_timeout_ms=0, + ) + async with ( + SQLiteProfile.open(config, tables=()) as owner, + SQLiteProfile.open(config, tables=()) as contender, + ): + repository = ServerIdentityRepository(contender.database) + if phase == "read": + await repository.initialize() + operation = repository.initialize if phase == "schema" else repository.load_or_create + contended = asyncio.Event() + + @event.listens_for(contender.database.engine.sync_engine, "handle_error") + def observed_lock(context) -> None: + contended.set() + + async with owner.database.transaction() as connection: + if phase == "schema": + await connection.exec_driver_sql("BEGIN IMMEDIATE") + await connection.exec_driver_sql("CREATE TABLE lock_probe (value INTEGER)") + else: + await connection.execute( + insert(SERVER_IDENTITY_TABLE).values(singleton_key=1, server_id="committed") + ) + with monkeypatch.context() as budget: + budget.setattr("powercontext.server.identity._INITIALIZATION_TIMEOUT_SECONDS", 0) + with pytest.raises(OperationalError, match="locked"): + await operation() + contended.clear() + pending = asyncio.create_task(operation()) + try: + await asyncio.wait_for(contended.wait(), 2) + except BaseException: + pending.cancel() + await asyncio.gather(pending, return_exceptions=True) + raise + result = await pending + if phase == "read": + assert result == "committed" + else: + assert await repository.load_or_create() asyncio.run(scenario())