4.8 KiB
4.8 KiB
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=Trueandseparators=(',', ':'). - Identity key:
ops-origin-v1:<sha256(canonical normalized five-part identity)>. It requirescompanion_instance_id,bot_account_id,adapter_instance_id,subject_namespace, andplatform_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, andnsfw; 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, withprofiles,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_migrationis non-mutating. Incomplete companion/Bot/adapter/namespace context returnslegacy_unresolvedand applies no change.apply_unified_person_migrationretains a scoped, non-recursive pre-migration backup and is idempotent bymigration_id.rollback_unified_person_migrationrestores that scoped backup while retaining the current backup registry, without deleting legacyusers,groups, scores, or configuration.- Legacy
relationship_scoreis preserved only asaffinity_baseline; no event history is fabricated. - Legacy
private_user_aliasesbecomelegacy_alias_candidates, not identity links. They require explicit owner confirmation before any binding. - Legacy
relationship_role=owneris 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_idfrom 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.