# Managed local Server installation (https://powercontext.oceanbase.io/en/docs/operate/managed-local-server/)

The independent Ops tool prepares a fixed Server runtime and manages its current-user service. Ops has its own
interpreter and dependencies, so repairing a missing Server interpreter does not require the damaged environment to
run. Desktop integration uses this boundary; a running HTTP connection is not required for installation or repair.

## Installation and repair plans [#installation-and-repair-plans]

Installation and repair use the explicit `preflight`, `apply`, `operation_status`, `cancel`, and `resume` protocol
described in [Local Server operations](https://powercontext.oceanbase.io/en/llms.mdx/docs/operate/local-server-ops/content.md). The caller displays the complete plan and obtains approval
before applying it. Retain the operation ID when starting a request; after interruption, inspect the saved attempt and
current facts before approving a recovery plan.

If a later stop operation supersedes an interrupted repair, approve a new repair plan instead of resuming the
superseded operation. The new plan can continue the original repair guard only after checking its journal, installation
and resource identities, exact service definition, and completed native commands. It does not restart the service or
restore a registration that was subsequently removed.

The packaged Ops interpreter accepts one JSON request per process. Its trusted host supplies the protected catalog
and the SHA-256 digest pinned by the distribution:

```text
<ops-python> -I -S -B <ops-entry.py> --catalog-file <protected-catalog.json> --catalog-sha256 <trusted-sha256>
```

For example, send this single line on standard input to inspect a first installation:

```json
{"protocol_version":1,"request_id":"inspect-install","action":"preflight","operation":"install","options":{}}
```

The response includes the fixed resource, program/configuration/data locations, endpoint, database classification,
required space, and startup effects. Pass the returned complete plan unchanged to `apply`, with a unique operation ID
and explicit authorization for its `plan_id`, as in the shared Ops protocol. To prepare same-version repair, use
`"operation":"repair"`. Managed locations are selected by the host; `--state-dir` belongs to the separate operator-owned
`--target-file` mode and cannot override a managed installation. These commands require a qualified producer catalog;
they do not discover a public release or produce one.

Only the trusted producer selects resource URLs, executable layout, platform, architecture, package version, and file
digests. The renderer cannot supply a command, download URL, or arbitrary installation path. Resources are downloaded
to staging, checked against the fixed catalog, and verified before publication. A checksum supplied alongside an
untrusted download does not establish trust. A cache hit must pass the same integrity checks as a download.

Repair uses the same fixed resource identity and version. It preserves the installation identity, existing
configuration, and user data. It does not upgrade to `latest`, reset authentication or models, or delete an existing
database. Repair stops the owned service before replacing resources and completes without restarting it. A stopped
service stays stopped. Repeating installation for a verified current installation reports current
facts without restarting the service or opening its database.

Managed service definitions explicitly select isolated runtime startup (`isolated_runtime=true`). The target Python
runs with `-I -B`, excluding `PYTHONPATH` and user-site imports and avoiding generated bytecode changes in the verified
resource tree. Manage these definitions with the bundled Ops tool or a matching-version service tool. Older CLI
versions that do not recognize this field reject the definition; they are not a supported way to manage the new
registration. Existing definitions without this field retain their previous startup behavior.

An independent installation is not automatically adopted. Unknown ownership, damaged control records, mismatched
native service definitions, or unresolved native commands require inspection before modification. Removing a service
registration preserves the environment, configuration, and database; it is not a database deletion operation.

## New personal configuration [#new-personal-configuration]

The new-configuration policy explicitly sets:

| Setting | New managed installation |
| --- | --- |
| HTTP listener | `127.0.0.1` and the approved port |
| Database | SQLite at an explicit absolute path in the selected user-data directory |
| Dashboard | Enabled |
| Access mode | `disabled` |
| Legacy bearer authentication | Disabled, with no token |
| MCP | Uses the same local access mode as HTTP |
| Models | No generation, embedding, reranking, or decision model is configured |

This is local access without a token, not a separate anonymous credential. Keep the listener on loopback. The policy
does not change authentication for existing or remote connections, and repair does not overwrite an existing user's
choices. Selecting an authenticated existing installation retains its protected configuration.

The default data directory follows the platform's `powercontext_data_dir()` location while ignoring an inherited
`POWERCONTEXT_HOME`. New configuration also ignores inherited `POWERCONTEXT_SERVER_*`, `PYTHONPATH`, and `PYTHONHOME`
settings during resolution. It records the chosen data root and SQLite path explicitly. Existing installations retain
their verified registered data directory; program directories and data directories are separate.

Preflight reads configuration through the protected-file interface and returns only the file identity and necessary
local summary fields. Configuration contents, tokens, and model credentials do not enter plans or operation journals.
Preflight does not create a configuration file, data directory, or database.

## Database compatibility boundary [#database-compatibility-boundary]

Passive inspection inventories the selected SQLite file and recovery sidecars without opening SQLite or starting a
target process. Existing files remain `existing_unknown` in ordinary status. Program-only repair binds the file
identity and target version, allows normal writes and WAL checkpointing during resource preparation, and completes
with the service stopped. Replacing the database invalidates its repair plan.

Operations that can start the managed service perform a separate admission check: `start`, `restart`, registration,
and configuration changes that actually restart an active service. Ops verifies the owned target resource against its
fixed manifest, then invokes that bundle's Server admission entry with isolated Python (`-I -B`). Windows uses the
manifest's console Python from the same bundle. The child checks its installed package version against the selected
Server version. An older target without this entry remains unsupported; the Ops package version or a previous
successful startup cannot replace target admission.

The target checks the complete Server schema and indexes, supported revision history, configured domains and
embedding profile, SQLite integrity, original-path maintenance evidence, and unfinished archive restores. It reads a
private copy of the main database and WAL, including committed data not yet checkpointed into main. The original
database is never opened by SQLite during admission; its SHM is neither copied nor changed, and no original sidecars
are created or removed. File identities and modification evidence must remain stable while copying and checking.
Admission performs no initialization, migration, restoration, model call, HTTP startup, or worker startup.

| Observation | Startup behavior |
| --- | --- |
| Database and recovery evidence are absent | `new`; only the approved Server startup may initialize storage. |
| Existing storage passes the exact target's complete check | `existing_ready` for that explicit admission; same-version startup and restart require unchanged storage through apply. |
| Unknown schema, empty existing file, older layout, future revision, unsupported profile, or missing target helper | Block startup and preserve storage. |
| Interrupted maintenance/restore, rollback journal, active maintenance lock, orphan sidecars, unsafe location, or changing source | Block startup and preserve recovery evidence. |

A revision marker or a partial domain check is insufficient. Required migrations and recovery remain explicit
operator work under [Database migrations](https://powercontext.oceanbase.io/en/llms.mdx/docs/operate/database-migrations/content.md). `database_migration_required`,
`database_recovery_required`, and `database_configuration_mismatch` identify those boundaries;
`database_compatibility_unknown` means the exact target could not establish compatibility. Repair changes programs
only and does not remove these requirements.

Admission copies and hashes the complete main file and WAL, then scans the snapshot using Server validators. Each
preflight and apply revalidation repeats this work; it is not an incremental or cached check. The combined main/WAL
limit is **8 GiB**, the temporary filesystem needs their combined size plus **32 MiB** free, and copying plus target
validation has a **120-second** deadline. Oversize, insufficient space, and timeout return
`database_snapshot_too_large`, `database_snapshot_space_insufficient`, and `database_admission_timeout`. Recovery
journals are limited to 4 MiB each. Large or busy databases require an operator-controlled maintenance workflow;
raising a limit does not establish compatibility. Temporary copies are removed after the check.

Normal writes also invalidate approved database evidence. If the running Server keeps writing, or data changes
between preflight and apply, stop it through Ops, obtain a fresh `start` plan after writes have stopped, and approve
that plan. A rejected restart leaves the running service unchanged. Admission does not automatically stop writers or
relax the approved database identity; other processes writing the same database must also be quiescent.

A local macOS arm64 / CPython 3.12.15 measurement with 2,000 public Memory records, 4,000 revisions and a 168.4 MiB
SQLite main file took 3.78–3.86 seconds per admission across three runs; copying and hashing took 0.074–0.075 seconds.
Source hashes remained unchanged. This measurement excludes resource-manifest verification and native service
commands and does not qualify other machines, WAL sizes, or databases near the limit.

Apply repeats admission and compares the approved plan's database, configuration, target-resource and recovery
evidence. Changed evidence rejects the old plan before a service command. The running Server still owns its normal
startup checks. Inspection, stopping, registration removal, and stopped program repair remain available when the
target interpreter is damaged or absent. A stopped service stays stopped
when configuration changes request `restart=true`. The independent prepared-runtime operator binding retains its
existing contract.

## Startup and connection handoff [#startup-and-connection-handoff]

Resource integrity, configuration validity, service registration, process liveness, and readiness are separate facts.
For an approved first startup, the shared service controller performs bounded readiness verification and protects and
stops a newly started owned target when startup fails. A completed installation result is historical evidence; ordinary
status does not rerun readiness checks. Cancellation takes effect at supported safe boundaries and does not promise
rollback.

If first registration fails before creating a service, release the conflicting port or resolve the reported failure,
then confirm a fresh install plan and resume the recorded operation. The installation identity and owned configuration
are retained. A dispatch checkpoint alone does not establish that registration existed. Matching-version CLI and Ops
removal persist a private removal identity before native changes; an older install operation cannot undo that removal,
even when no registration existed yet. Pending records without this identity remain readable, but a legacy dispatch
checkpoint without registration evidence requires inspection rather than automatic replay.

A cancelled installation can reuse verified staging. If regular staged files are corrupt, resume or a new approved
install operation verifies the recorded directory ownership, discards that exact staging tree and prepares the fixed
resource again. Replaced directories, links and unsafe ownership are rejected and preserved.

The installer returns its actual endpoint and installation/resource identities. These are not Server deployment or
Principal identities. The connection layer must validate the actual endpoint and supported public identity and
compatibility contract before activating a connection or obtaining its default Scope. Installation does not invent a
Scope ID, select an arbitrary Scope, or prove that a Memory operation has succeeded.

## Release and platform acceptance [#release-and-platform-acceptance]

This implementation requires producer-supplied, fixed resources. The
[candidate producer](https://powercontext.oceanbase.io/en/llms.mdx/development/managed-resource-production/content.md) builds pinned native Server/Ops resources for
Windows x86_64 and macOS arm64/x86_64 with real consumer readback. Its catalogs remain unqualified.
The formal platform resource catalog and qualified artifacts belong to [#2112](https://github.com/oceanbase/powercontext/issues/2112); the implementation does not supply a
public production download URL or infer one from a version string. Development fixtures and locally built bundles
verify implementation behavior, not production distribution trust.

On Windows, preflight checks the producer's file layout against the actual final directory and the fixed staging
budget. Acquisition checks its exact staging directory again before downloading. Ordinary paths must fit the Windows
file and directory limits; unsupported layouts return `resource_path_unsupported`. Ops does not enable system-wide
long paths or assume Task Scheduler supports extended-path executable names. The producer must qualify a layout that
fits the intended user directories. A complete development bundle that starts from a shorter test directory does not
establish that the default installation layout works.

Release acceptance must use the exact downloaded artifacts on clean standard-user Windows 11 x64, macOS arm64, and
macOS x86_64 machines without preinstalled Python, uv, Git, or build tools. Independently verify signatures and macOS
notarization, independent Ops startup, actual Task Scheduler or LaunchAgent behavior, login/restart handling, and
preservation of configuration and data through repair and removal. Fake service adapters and repository-runtime
SQLite tests do not establish those platform results.
