13 KiB
type, title, description, tags, sources, generated, verified
| type | title | description | tags | sources | generated | verified | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| release-readiness | CloudKit Schema Deployment and Signed-Device Release Readiness | Production CloudKit schema, compatibility, and signed-device checks for Vault, Settings, SFTP preferences, Metrics, and Keychain-backed secrets. |
|
|
|
|
CloudKit Schema Deployment and Signed-Device Release Readiness
A passing local build or sync test does not prove that the production CloudKit schema is deployed or that signed devices can exchange records. Treat schema deployment, App Store entitlements, iCloud account state, Keychain delivery, and multi-device behavior as separate release evidence.
The macOS and mobile targets use the private container iCloud.com.akinokaede.termind. The master iCloud switch and the Vault, Metrics, and Settings category selections default on when no explicit value exists; existing explicit choices survive upgrades. Category lifecycle and account bindings remain independent, and Pro access gates live synchronization without deleting local data.
Schema inventory
Validate the Development schema first, then explicitly deploy it to Production.
| Category | Zone | Record type | Subscription |
|---|---|---|---|
| Settings and AI configuration | TermindAIConfigurationV1 |
AIConfigurationItem |
termind-ai-configuration-v1-changes |
| SSH preferences | TermindAIConfigurationV1 |
SSHPreferencesItem |
termind-ai-configuration-v1-changes |
| SFTP preferences | TermindAIConfigurationV1 |
SFTPPreferencesItem |
termind-ai-configuration-v1-changes |
| Workspace preferences | TermindAIConfigurationV1 |
WorkspacePreferencesItem |
termind-ai-configuration-v1-changes |
| Metrics | TermindMetricsV1 |
MetricsItem |
termind-metrics-v1-changes |
Vault records use the same private container through their own coordinator and compatibility contract. A Vault envelope stores integer formatVersion and counter, Boolean isDeleted, strings kind, entityID, writerID, and payloadHash, date modifiedAt, inline bytes payload, or payloadAsset for payloads above the 700,000-byte inline limit. Preserve zone names, record types, subscription identifiers, envelope fields, and format compatibility: older clients must be able to ignore the distinct SFTPPreferencesItem record type before attempting to decode it.
Connection-history events and the reusable device directory use separate connectionHistory and device payload kinds inside the existing Vault VaultItem record type; neither requires a new CloudKit zone, record type, field or Production schema deployment. Release validation still needs mixed-version coverage because older clients cannot decode those payload kinds safely until the quarantine-capable build is deployed. On signed devices verify event start/end updates and tombstones, local-only Recents versus all-device History, and deterministic convergence to the newest 250 events. Independently rename a device and verify that one device update changes every history row resolving its stable ID, while event pruning, per-Host deletion and Clear History leave device records intact.
There is no public-database access in this design. Before release, verify the app entitlements, the private-container Development schema, and the deployed Production schema with credentials that actually have CloudKit management access. An unavailable management token or a successful local test is not deployment evidence.
Signed-device matrix
Use at least two Macs and one iPhone or iPad signed into the same Apple account, then repeat the critical path across an account switch.
- Add, edit, and delete providers, roles, MCP clients, skills, and terminal configuration. Include offline edits, independent category pause/resume, master pause/resume, delayed Keychain delivery, key rotation, and Pro expiration.
- Verify that an account switch merges before upload and that category selections and account bindings remain independent.
- Confirm that theme text, custom terminal text, and shell-integration changes update existing windows. Font family, size, and follow-theme-size are device-local; distinguish them from fonts authored inside synchronized theme text.
- Confirm that conversations, approval mode, and the local MCP listener's enabled state, port, tools, and token never synchronize.
- Before deleting the iCloud Keychain copy of a migrated MCP token, verify that the local replacement works.
- Verify Metrics ordering, pause state, disk choices, and network choices across platforms. Metrics records that arrive before their Vault Hosts must remain hidden until those Hosts exist.
- Verify that the published privacy-policy version and effective date match the release being shipped.
Exercise offline edits and delayed delivery deliberately. A clean online two-device pass does not cover journal replay, acknowledgement, account-transition, or missing-Keychain cases.
SFTP preference compatibility
SFTP preferences synchronize as v1/sftp/default; transfer jobs and byte progress are never Settings records. Deploy SFTPPreferencesItem before a client version that uploads it.
Current defaults are 30 global transfers, 10 per Host, and Smart topology. The accepted global range is 1–100; per-Host is 1–50 and is additionally clamped to the global value. Historical V21 migration imports an existing local value once, including older 3/2 or 15/5 choices; saved values are not silently reset to the new defaults.
For a release check, change 30/10 to 100/50, close Settings, and verify that another device adopts the new pair without interrupting active transfers. Repeat while offline and while the Settings category or master switch is paused, then resume. Include a device retaining 3/2 and, where compatibility testing is available, an older client that continues syncing the pre-existing record types while ignoring SFTPPreferencesItem.
First-stage mixed-version safety
Local schema V31 adds replica-scoped quarantine and recovery checkpoints. The current V34 schema retains that safety storage and adds the connection-history/device shapes through the direct V31→V34 migration. Those local changes do not add a Vault record type, change the existing zones, or raise the V1 envelope formats. Treat local database migration and cloud schema deployment as separate decisions; the distinct Settings record types in the inventory still require deployment before use.
The compatibility contract is now fail-closed for records a client detects it cannot safely understand: keep the received bytes and local pending edits, remove that record from upload scheduling, and recheck the final batch/provider. Other compatible records remain eligible. Unsupported fetches and serverRecordChanged replies share this path. Only successful supported-data reconciliation clears the restriction; pressing Retry, pausing a category or restarting does not discard it.
Include the following matrix in release validation:
| Scenario | Required result |
|---|---|
| New-format record with the same ID as a local pending edit | Block that ID without replacing it with defaults or clearing the local edit. |
| Another record in the same category remains compatible | Upload it; show pending and blocked counts separately. |
| Restored save queue, local tombstone, or physical-delete recreation | No path bypasses the restriction; never emit physical deletes from a restored queue. |
| Upload conflict returns an unsupported record | Preserve it in quarantine rather than retrying a stale local payload. |
| Persistence failure during fetch/conflict handling | Retire that engine; a later callback cannot reauthorize it, and restart fetches afresh. |
| Pause/retry/relaunch or account/environment change | Preserve restrictions in their original scope without leaking them into another replica. |
| Supported replacement arrives but its merge fails | Roll back data, metadata and unblock together. |
| Corrupt data rather than a recognized newer format | Explain the restriction without promising that an app update will repair corruption. |
Portable tests exercise real journals, coordinators, record coding and batch providers behind a fake CloudKit transport, plus on-disk migration and reopening. They do not establish signed-device delivery or Production behavior.
This first layer does not preserve arbitrary unknown JSON fields that a decoder silently ignores, retrofit already-shipped clients, or implement general capability-upgrade replay. A new V31 safety scope forces an initial fresh fetch; that is not a promise to replay every previously ignored record after every future app update. Roll out the safety-capable clients before relying on the new gate, and isolate incompatible additions from historical clients with distinct record types or an explicitly designed migration protocol. Keep a genuine new→old→edit→new binary test in the release matrix.
Evidence boundaries and release sign-off
The historical 2026-09-19 implementation record covered full TFI, focused iPad, focused TFM, multilingual visual, formatting, and localization checks. It did not establish a fully green macOS suite, Production schema deployment, or real signed-device delivery; failures outside the implementation scope remained. Treat those counts as historical context only and rerun current release checks.
Release sign-off should record, separately:
- the current pinned macOS and mobile build/test results;
- successful Development validation and explicit Production deployment for every required zone and record type;
- the signed multi-device/account-switch matrix, including offline and pause/resume behavior;
- Keychain-delivery and migrated-token checks;
- the SFTP preference and mixed-version safety matrices; and
- the published privacy-policy version and effective date.
See Settings, Vault, Metrics, and Cloud Sync Workflow for runtime lifecycle and journals, Persistent Data, Migrations, and Secret Boundaries for local stores and secret references, and Build, Validation, Localization, and Dependency Release Operations for ordinary build gates.