# OPS Unified Person System Development Receipt ## Scope and starting point - Repository: `astrbot_plugin_private_companion-main` - Actual branch and commit: `ops-main`, `54b4aa297a0f27791d9e677c598094457c67c64a` - Scope completed here: P0 shared contract, identity key normalization, read-only producer endpoints, fixed projection sample, and a non-automatic reversible legacy migration foundation. - No code from the memory repository, root documentation, `peiban`, deployment scripts, VM, or remote was modified. ## Contract - Name/version: `ops.unified_person.v1` / `1.0` - Sample version: `1.0` - Descriptor keys: `name`, `version`, `sample_version`, `required_fields`, `enums`, `identity_key_fields` - Deterministic fingerprint: `633e2d235345d5c1bb72f8e6247e61932c5215ad2817242eefb709b502aefe03` - Fingerprint algorithm: SHA-256 of canonical JSON with `sort_keys=True` and `separators=(',', ':')`. - Identity key: `ops-origin-v1:`. It requires `companion_instance_id`, `bot_account_id`, `adapter_instance_id`, `subject_namespace`, and `platform_subject_id`; it never emits a bare platform identifier or raw canonical identity JSON. - Identity normalization accepts strings and non-boolean integers only, rejects booleans, floats (including NaN/Infinity), and containers, applies NFC and edge trimming only, preserves internal whitespace, rejects NUL and values longer than 160 characters, and lowercases only `subject_namespace`. - The fingerprinted enum includes all frozen relationship capabilities, including `comfort`, `proactive_care`, `hugging`, `public_favoritism`, and `nsfw`; legal configured capabilities are preserved in the projection. - Fixed consumer sample: `docs/unified_person_projection_v1.sample.json`. ## Data and migration - New persisted root: `unified_person`, with `profiles`, `identity_links`, `relation_policies`, `group_overlays`, and scoped migration metadata. - Store initialization only installs empty containers. It never performs a migration at startup. - `preview_unified_person_migration` is non-mutating. Incomplete companion/Bot/adapter/namespace context returns `legacy_unresolved` and applies no change. `apply_unified_person_migration` retains a scoped, non-recursive pre-migration backup and is idempotent by `migration_id`. `rollback_unified_person_migration` restores that scoped backup while retaining the current backup registry, without deleting legacy `users`, `groups`, scores, or configuration. - Legacy `relationship_score` is preserved only as `affinity_baseline`; no event history is fabricated. - Legacy `private_user_aliases` become `legacy_alias_candidates`, not identity links. They require explicit owner confirmation before any binding. - Legacy `relationship_role=owner` is only a warning unless an explicit backend owner ID is supplied to the migration call. ## Read-only producer bridge `PrivateCompanionExtensionAPI` now exposes: - `get_unified_person_contract()` - `get_unified_person_projection(person_id)` - `resolve_unified_person_identity(identity)` Resolution requires the exact complete identity. An unregistered identity returns `state=pending_companion`; it creates nothing. Invalid or incomplete input returns `state=quarantined` with `error_code=invalid_identity`. ## Hook order No request Hook order was changed in this P0-only patch. Firewall classification, prompt sanitation, affinity ledger settlement, confinement, owner commands, and memory write/recall gates remain deliberately unimplemented and must not be considered enabled. ## Verification - Directed: `C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m unittest tests.test_unified_person_contract -v` - 9 tests passed. - Full: `C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m unittest discover -s tests -q` - 259 tests passed. - The directed tests are counterfactual for the old unsafe behavior: a raw/missing namespace key, auto-linking legacy aliases, a mutable unresolved resolve, an invalid sample, or a non-idempotent migration makes them fail. ## Remaining work and cross-plugin dependency - The companion side must still implement explicit administrator merge/split, person creation from real message identity, relation policies, owner-profile configuration, affinity event ledger, confinement/recovery state machine, command authorization, firewall, and page/API controls. - Memory must compare the descriptor fingerprint before consuming a projection, call only the read-only bridge methods above, and map unavailable/unresolved input to the frozen coordination states. It must not construct `person_id` from an identity key. - The scoped migration backup is a compatibility rollback mechanism, not a substitute for an operator's normal persisted-store backup before a production migration. No commit, push, or deployment was performed.