Requirements, platform implementation and validation

This reference separates available implementation from actual test evidence. Windows, Linux, and macOS have platform-specific code and shared skills; that does not establish equal native validation or make every update/repair route available. The README introduces the skillset; this file supports capability checks and accurate operating decisions.

For the source-download, extraction, and local-assistant steps on each OS, use getting started. Start with the menu in the assistant's chat. No computer information is collected until the owner chooses a job and authorizes the selected assessment scope. PatchCairn: requests are chat instructions, not operating-system shell commands.

What the project provides

PatchCairn is a reusable instruction/skill set plus local scripts. The AI assistant conducts the investigation and coordinates supported official tools within the exact documented contracts and owner authority. The assessment-record backends manage selected metadata, records, reporting and owned-run housekeeping. The conversation workflow provides durable conversation state, bounded selected-file storage/backup services and fixed diagnostic recipes. Opening the project does not start an installer or a background maintenance service.

Use an assistant with project-file access, a suitable shell and current web research. Check its actual privileges and available tools. Use the host's computer-use skill only when GUI interaction is necessary. A missing capability is explained before the dependent operation.

Platform matrix

No extra Python packages are required by the portable helpers. The Windows Python adapter lazily starts an owned fixed PowerShell worker over framed inherited pipes and reuses only its interpreter/compiled type. Fresh native checks and private request/response packets remain per operation; no plan supplies executable code or authority. Import and the bare menu launch no worker. Missing prerequisites cause a hold, without a weaker launch fallback, elevation or silent installation. Check an existing runtime's supported source/channel as part of a real assessment.

The supplied CI is configured to discover every test_*.py unit/integration suite on Windows, Ubuntu and macOS with Python 3.12 and 3.15, retain the offline JavaScript report fixtures, and run the assessment-record, native selected-file and private-namespace PowerShell suites under PowerShell 7 and 5.1. Portable Windows jobs retain a 90-minute bound; the separate Windows PowerShell job remains at 60 minutes, and Ubuntu/macOS portable jobs remain at 15 minutes. Focused local Windows checks do not establish hosted timing or a completed hosted run of the published snapshot. Reusing interpreter/type startup preserves fresh native checks. A capability skip remains a skip; it does not establish that the skipped native action worked. Treat actual run results and their exact source binding as evidence when available; a checked-in workflow file is not a successful hosted run.

Hosted fixture evidence

Use the public fixture-safety workflow to check validation of the published source. Match a completed run to its source commit, runner, runtime and skips before carrying its result to that snapshot. The tested contexts below do not by themselves establish that the published snapshot has passed.

Recorded pre-worker hosted fixtures used Python 3.12 and 3.15 on ubuntu-24.04 and macos-26-arm64 runner images. They do not establish the new Windows worker's behavior or speed. Actual operations on fictional files inside owned work/ directories passed in those contexts: metadata/hash/bounded reads, exclusive file/directory creation, exact deletion, native no-overwrite quarantine and restoration, bounded ZIP/manifest creation and restoration, private-file admission, and integrated backup/probe/retention and quarantine/restoration. The native success tests assert source/destination state and file bytes; unsupported native capability routes skip rather than use a weaker fallback. Separately mocked rename/error contracts remain distinct. The offline report JavaScript fixtures also passed using a minimal fictional DOM; they are not browser/layout tests.

The reviewed Ubuntu context skipped Windows-only cases, a non-POSIX refusal case, a Windows-mounted WSL case and the unsupported-private-storage branch on an admitted workspace. The reviewed macOS context also skipped Linux-only runtime/filesystem/pipe cases and a case-sensitive-name collision case on its case-folding filesystem. Skips establish no successful action. Runner-image labels do not independently identify exact fixture-volume filesystem types; these results do not certify every APFS/HFS+, Linux filesystem, architecture or OS version.

Diagnostic collector output and installer handoffs remained fictional/injected or nonexecuting. No live inventory, diagnostic collection, package installation, repair, restart or whole-system assessment is claimed. Current published-source counts, capability skips and native success assertions must be checked in the matching completed public workflow; an implementation, a workflow definition or a green aggregate label alone is insufficient.

Capability and evidence boundaries

Local Windows Python 3.14 fixture discovery completed 523 cases: 471 passed, 52 skipped, no failures or errors, with the tested source unchanged. The discovered total includes pure and mocked contract tests; skips do not establish native success. Focused 64-MiB native create/inspect/read checks also passed under both PowerShell editions with verified bytes/hashes and completed owned-worker teardown; Windows evidence records the observed worker lifetime peaks. These results do not establish general workload speed or a matching published-source hosted run. Use actual completed evidence for those claims, including the configured workflow for the published snapshot.

The external update handoff accepts only those fixed local-artifact catalogs. Fresh preflight binds the actual owned staged path and content hash to the reviewed version, channel, architecture, installation scope, publisher and source, with the coordinator's actual package-metadata and supported publisher/signature verification evidence. The helpers prepare a reviewed handoff and record the observed receipt; the coordinating assistant performs the supported official-tool call and the owner handles protected consent. Package-manager catalog operations remain held because the current adapter cannot bind their transaction to the exact staged bytes. OS/application component repairs also remain held until recovery for that exact component is supported: a verified file-content ZIP is not OS rollback or package-state recovery. Fixture contract validation does not claim that any installation occurred; the hosted native macOS file-operation results above do not establish an installer or official-command execution pass.

Each integrated local installer artifact is bounded to 64 MiB and the documented fixed argument grammar. Only supported stable variants with established identity, publisher, channel, architecture and installation scope can pass the exact plan and preflight gates. An EXE, a larger MSI/PKG/DEB, an extra switch, or a matching package-manager offer is not a substitute for that supported route. The assistant can explain an official owner-performed procedure within agreed scope, while preserving the unavailable integration as a hold. Guidance alone never establishes execution or success.

The Windows MSI contract preserves code 3010 as installed with restart and behavior verification pending. The same operation stays active and its action remains consumed. The owner can defer or separately authorize only the exact owner-handled restart; actual before/after boot, selected target and original-behavior observations are required for final accounting. Success needs the reviewed target and every check to pass. Failed/unknown behavior supports only failed or partial accounting and fresh effects/no-active-work/retained-recovery reconciliation before eligible replanning. A stopped session can record the exact owner restart decision only as accounting for that retained unfinished effect; stopped status and the consumed action remain. No helper restarts Windows, repeats the installer, or rewrites 3010 as zero. Code 1641 under the fixed /norestart call is unexpected restart initiation and remains an unknown outcome pending reconciliation. These implemented contracts and fictional receipts do not establish that a live installer or restart has run. See service integration for the exact evidence and callback APIs.

The selected-root filesystem contract was also checked with 35 cases on Windows and WSL: Windows passed 12 contract/mock checks with 23 POSIX-only skips; WSL passed 32 with three filesystem-capability skips. The shared diagnostic core passed 13 cases with one Windows symlink-privilege skip, and nine POSIX recipe/parser cases passed with mocked collectors. These component results describe their tested scopes and do not claim a complete final integrated maintenance run.

Metadata assessment and content reading have separate budgets. The current storage service defaults to 16 MiB per selected content file, 48 MiB total selected payload and a 64 MiB bounded archive; it reports an explicit hold when a requested recovery set exceeds its supported content path. Metadata totals do not silently remove oversized files from an assessment. The Windows low-level read/stream/create path has a 64 MiB cap; a lower shared service limit still applies. For larger selections, propose a separately reviewed suitable backup route with exact contents, exclusions, destination and restoration verification. Never trim required recovery silently or claim ZIP compression provides encryption.

Operating limits

Private storage is a prerequisite

Before persisting selected evidence, the current workflow, service, diagnostic, backup and assessment-record backends verify their private namespaces. A shared repository or ordinary work/ ancestor is different from a private record store. Existing unsafe stores are held without changing their permissions or adopting old records. Assessment-record backends require their complete record work area to satisfy their admission contract; do not mix a shared development workspace into an assessment-record private run.

The earlier WSL storage/service functional results used the mounted Windows fixture filesystem before this private-storage gate was added. The final gate correctly refuses private record allocation on that tested /mnt/c filesystem. Those earlier successes are algorithm evidence for their recorded revisions, not positive final private-storage validation. The final negative capability checks confirm no private namespace or payload is written on the refused filesystem. Positive Linux filesystem and Darwin native-call variants retain mocked contract coverage; the hosted Ubuntu and macOS ARM64 jobs additionally passed actual private storage/archive/probe/record fixtures on their admitted workspaces. Windows private namespaces and records have actual owner/DACL fixture checks.

The native ABI, ACL and access-control boundaries are detailed in the filesystem contract, the Windows adapter, and the source helpers. A capability hold is not authority to weaken permissions, remount a filesystem, change its metadata options, or move fixtures outside the selected workspace to manufacture a pass.

• The collectors gather selected metadata. Current releases, vendor support, advisory applicability and compatibility still require fresh research and reconciliation.
• Keep different installation owners, architectures, project environments and publisher bundles distinct. A system runtime update does not patch every application-owned copy.
• A run's creation backend, mode and platform are immutable. Use a fresh run rather than promoting fictional evidence or silently migrating another backend's records.
• Assessment-record owned-run cleanup and selected-root operations have separate adapters and authority boundaries. No broad external root becomes safe because it was listed in an owned-run manifest.
• Keep selected scopes and output owner-controlled and quiet on every platform. Windows pins handles during each native call; POSIX uses checked directory descriptors. Neither provides a multi-operation transaction or an OS sandbox against same-user/privileged concurrent mutation. Avoid shared, synchronized or concurrently modified work folders. Interruption or a failed postcondition requires reconciliation before another action.
• Native no-overwrite rename is capability-gated. A missing symbol, unsupported filesystem, different volume, reparse/symlink, hard link, changed identity/content, inaccessible ancestor or permission barrier is a hold. Do not substitute ordinary overwrite-capable rename, cross-volume copy/delete, force, ACL repair or ownership changes.
• The local v9fs test filesystem did not establish native ACL-denial or actual FIFO-creation behavior. Injected admission checks passed; those limits do not become native ext4/APFS proof.
• Diagnostic requests are data, not proof of owner permission. The coordinator explicitly authorizes a bounded real recipe in the current process. Diagnostic evidence records distinguish observation, hypotheses, cause, confidence, repair and actual verification. No recipe executes a repair or reads arbitrary logs/credentials.
• Protected consent, authentication and separately authorized restarts remain owner interactions. Permissions and host tools, rather than Markdown instructions, enforce OS access boundaries.

Read the matching Windows adapter, Linux or macOS guide and the assessment-record helper API before operating those adapters. The selected-root filesystem contract, storage/backup API, diagnostic API, workflow engine and service integration document their separate capabilities. Follow security guidance and recovery/cleanup throughout.

Developed by Michael. Private session records belong locally under work/; this public guide contains no live computer records.