Workflow service integration

WorkflowService(engine=None, *, work_relative="work/services") connects the deterministic conversation engine to fixed storage and diagnostic adapters. Every toolkit-generated record remains under the executing repository's work/. Fixture mutations are restricted to explicitly selected owned fixture children. This service is a trusted coordinator boundary in a quiet workspace, not an OS sandbox against another process running with the same privileges. Numbered schema/backend/catalog identifiers below describe internal formats within the single PatchCairn workflow.

The public methods are prepare_storage_action, prepare_diagnostic_action, prepare_external_action, record_external_preflight, register_recovery, execute_action, complete_external, complete_external_after_restart, complete_diagnostic, inspect_operation and reconcile_operation. Preparation registers exact immutable adapter/inventory bytes and returns the concrete action specification for an engine plan. It never approves that plan. Execution rechecks the exact registered adapter payload, lower-level plan, source inventory, scope, mode, output and protection policy before consuming an engine operation ticket.

Storage dispatch uses only storage.backup_create.v3, storage.backup_restore.v3, storage.cleanup_quarantine.v3, storage.quarantine_restore.v3 and storage.permanent_purge.v3. Diagnostic dispatch uses only diagnostic.read_recipe.v3 with the fixed recipe IDs documented in the diagnostic API. No payload chooses a Python method, shell, executable path or fallback command.

system.reviewed_external.v3 returns a concrete reviewed update handoff for the assistant's supported official host tool. It does not execute its argv. OS/app repair handoffs remain held until supported typed recovery covers that exact component; an ordinary file ZIP cannot establish OS rollback. The engine operation stays active until the trusted coordinator records the actual update outcome with fresh evidence. Success is never synthesized from issuing a handoff or reading a stored plan.

Normal coordination

1. Create a fresh engine session with its immutable fixture/real mode and native platform. Select exact roots and obtain the owner's actual scope decision using authorize_scope. A Python object, quote copied from a file, or imported approved flag does not establish human authority.
2. Obtain any separate content-read decision before the storage library hashes selected ordinary files. Build the lower-level native plan using the storage API, or select a fixed diagnostic recipe. Keep backup/output destinations and protection policy exact.
3. Call the corresponding preparation method. It registers canonical inventory and adapter payload bytes in the engine and returns an action with exact payload, lower-plan and inventory SHA-256 bindings. It performs no maintenance effect. Preparation still needs the current authorized collection scope.
4. Register a concrete engine plan containing the returned action. Complete the job's evidence stages, two independent reviews, actual owner plan/action decision, selected checkpoints and protected OS-consent steps. The service never fabricates those decisions.
5. Register fresh exact-action preconditions. execute_action first rejects paused/stopped/non-apply/checkpoint states, revalidates actual owned payload bytes and native freshness, then calls begin_operation. Only the resulting one-use durable operation ticket permits a fixed library call or reviewed external handoff.
6. The service persists the complete original payload, action, mode/platform, scope, settings revision and operation binding before the first effect. The original intent is also registered as engine-owned evidence with its exact hash. Quarantine stores its ordered original-file-to-numbered-destination mapping before a move. Native storage attempts separately preserve their complete exact plan.
7. Actual fixed-adapter outcomes are verified from native artifacts and registered as owned evidence before finish_operation. Verification of the original application behavior and any security remediation remains a separate engine stage. An exit status or matching version is not whole-system verification.

The coordinator writes service and engine state sequentially. The service uses a cooperative lock, exclusive immutable files and flushed writes. A missing creation marker, changed intent/evidence hash, missing native receipt or unsupported capability is a hold. Generated evidence is private and is never part of the public website or source package.

The dedicated service, operation and diagnostic namespaces use the common private_workspace.py admission boundary before private writes. New Windows directories have an actual verified current-owner/SYSTEM/Administrators-only protected DACL; new private files receive and verify an explicit descriptor before payload bytes. POSIX requires actual effective-user ownership and 0700 directories/0600 files plus the native platform checks below. Service control reads recheck file privacy. Existing broad namespaces are refused without ACL/mode repair, while the ordinary repository and work/ ancestors may remain shared. The storage library separately requires a private output namespace for archive, probe and copied contents.

Linux additionally checks the actual filesystem using pinned ordinary descriptors and read-only fstatfs before allocation and private-object use. The reviewed x86-64 LP64 little-endian glibc 2.x ABI admits ext2/3/4, XFS, Btrfs, tmpfs and ramfs; unknown ABIs/types, network/FUSE and Windows-mounted or NTFS-emulated storage hold even if reported modes appear private. Native ext4 under WSL can satisfy the type gate; the tested /mnt/c path is refused before private bytes. Its earlier functional results predate this privacy guard, and mocked positive filesystem tests are not an actual ext4 host certification.

Darwin additionally requires the source-verified read-only volume gate: reviewed writable local APFS/HFS+ with ownership enforced, using the fixed 64-bit x86-64/arm64 ABI. Ignored ownership, FSKit, unsupported volume types/ABIs and query errors hold. The native ACL checker must also establish a valid empty extended ACL or the precise source-verified absent-ACL result, with stable ordinary identity. Nonempty ACLs, unavailable APIs, unexpected results or changed identities hold; BSD mode alone is insufficient. Hosted macOS ARM64 jobs passed actual private-storage, archive/probe/record and integrated service fixtures through these gates; see platform evidence. Unsupported volume/ACL states and other ABI/filesystem variants retain their separate limits. No alternate public directory, outside-work destination or silent permission repair is used. Old broadly accessible run data remains unchanged and needs its own reviewed containment decision; the fix does not erase or silently migrate it. The diagnostic API describes these shared platform boundaries and primary permission-model references.

Public Python interface

Import WorkflowService and ServiceRefusal from scripts/workflow_service.py. Use an existing supported Python 3.12+ installation. The default engine and service root come from their scripts. New default namespaces are work/sessions for the engine and work/services for the service, with its diagnostics below work/services/diagnostics. Development root overrides must remain below the executing repository's work/. An explicit valid work-relative path selects only that store; no old namespace is discovered, adopted, migrated or deleted when these defaults are used.

All preparation methods require session_id plus keyword arguments action_id, target, benefit, risk, reversibility and verification. These explanations are reviewed nonsecret text. They return an engine action specification with bound owned evidence IDs; they do not register or approve the enclosing plan.

Storage preparation binds this payload, including the constructor's protection policy:

schema_version: patchcairn.storage.adapter.v3
operation: one of the five fixed storage adapter IDs
storage_plan: complete original native plan
storage_plan_sha256: actual canonical lower-plan SHA-256
output_root: exact existing owned work directory
mode: immutable session fixture/real mode
protected_roots: exact mandatory and explicitly selected protection boundaries
restore_probe_destination: optional exact new output child, backup_create only

storage.backup_create.v3 maps only to create_backup, storage.backup_restore.v3 only to restore_backup, storage.cleanup_quarantine.v3 only to quarantine, storage.quarantine_restore.v3 only to restore_quarantine, and storage.permanent_purge.v3 only to purge_quarantine. There is no dispatch through an imported Python method name. Lower-level plans keep their actual kinds backup, restore, quarantine, quarantine_restore and purge respectively. Native preconditions are checked again at the effect boundary by the storage library.

Recovery and irreversible loss

Required recovery uses actual ZIP/manifest hashes, exact member mapping and bounded contents, native artifact identities, a completed restoration probe and every probe file's verified bytes. Engine recovery validation reopens those artifacts; verified: true facts or a supplied JSON receipt alone do not establish recovery. Service native-origin records bind the archive/probe to the same engine and fixture/real platform. Retention records preserve all exact artifact hashes and conservatively protect their owned output directories from later host-cleanup scope. There is no automatic retention-release API.

A required backup may be protected before its archive is complete. Incomplete or unknown artifacts remain protected because an interrupted operation is not proof that no useful recovery data exists. The service protects existing evidence and required recovery across later sessions that use this service. It does not discover or claim authority over every backup elsewhere on the computer.

Every integrated quarantine also reserves its exact output namespace before the first move, including quarantines that do not require a ZIP. A typed retention record binds the complete original native plan, ordered original-to-numbered-file mapping, original intent/native provenance hashes and expected or pending native artifacts. The reservation survives completed, stopped, partial and unknown outcomes. Later sessions include that namespace in their protection policy; overlapping output/source plans are held. Only restoration or backed purge of the exact original receipt and mapping can operate on that reserved quarantine. There is no automatic release.

For an initial backup's verification, the reviewed backup_create payload can include an exact restore_probe_destination. This is a bounded substep of that same approved action: create/verify the selected archive, derive its exact restore mapping from the verified manifest, persist the complete derived native restore plan before writing, restore only to the reviewed new owned destination, and verify actual bytes. It does not overwrite original files. This supplies actual probe evidence without requiring a previously completed probe to authorize the first probe. A failed/incomplete substep preserves the action as unknown or partial until actual reconciliation.

These ZIPs preserve selected file contents; they are not encrypted system images and do not promise application, OS, ACL or firmware rollback. The assistant must explain recovery limits for the actual repair/update. A repair whose required recovery cannot be established remains held.

In particular, a verified ZIP of a small file in the authorized scope cannot satisfy recovery for Windows component-store or Linux package-state repair. Current fixed OS/app repair catalog entries are deliberately held until actual typed recovery for that precise component is supported. This implementation has no acknowledgment shortcut that pretends file-content recovery can roll back an OS repair. Diagnosis, selected evidence and official research can continue; the missing recovery capability and practical next decision must remain explicit.

The built-in file-content backup remains bounded to 10,000 metadata entries, 16 MiB per selected ordinary file, 48 MiB total selected logical bytes and a 64 MiB archive. These practical caps are not a whole-computer backup service. Larger contents require a narrower selected scope or a separately reviewed streaming design; this integration does not raise memory/buffer limits. Disk cost, duration and actual reclaimable space remain unknown where they have not been measured.

Restoring an existing quarantine has a narrower recovery guarantee: its actual bytes already remain in the numbered quarantine. prepare_storage_action for storage.quarantine_restore.v3 creates patchcairn.quarantine.recovery.v3 evidence containing the exact immutable quarantine receipt, exact restore plan/hash and retained current files/attempt/outcome hashes. The engine accepts that proof only for the same quarantine-restore adapter and native plan hash. Native checks reopen the original immutable provenance, verify every identity/content/mapping and require absent original destinations and a checked no-overwrite move. This supports restoration of an explicitly reviewed quarantine created without a separate ZIP; an unrelated backup is not required or accepted as a substitute. The typed quarantine binding cannot satisfy repair, permanent purge or generic backup restoration recovery.

Permanent purge is a separate plan/action from quarantine. It needs the current plan approval plus the engine's separate record_irreversible_ack record: typed permanent_data_loss, exact plan hash, action IDs, settings revision and scope hash, backed by the actual owner's acknowledgment. A boolean in an imported payload or a previous quarantine approval cannot satisfy it. Integrated purge is held when the original quarantine did not require recovery. For a backed quarantine, the accepted engine recovery must match that original receipt's exact backup, restoration probe, output root and covered file mapping; a valid backup of another selection cannot substitute. The service still checks exact current quarantine provenance/content and retained recovery before individual no-fallback removals.

Official update and repair handoffs

system.reviewed_external.v3 is a supported coordinator handoff, not a shell executor. The typed external plan includes kind, platform, immutable mode, catalog ID, exact official-tool identifier, exact argv/targets, primary source URLs, current owned provenance/compatibility evidence, a hash-bound recovery plan and a hash-bound original-behavior verification plan. Updates require target_versions and target_identities maps for every selected target. Each identity binds exact channel, architecture, installation scope, publisher, source ID and reviewed content SHA-256. Unknown publisher/content identities remain held. Repairs use empty update identity/version maps and their own precise fixed repair scope, but remain held in the current implementation. The supported catalog is deliberately narrow:

The assistant independently checks current installed-tool capabilities, actual target/channel/architecture/scope, official provenance and the reviewed transaction immediately before the host action. The local artifact path is itself part of the fixed reviewed argv, and the preflight artifact path must equal it. Package metadata must establish an unambiguous supported installation scope and variant; an ambiguous dual-scope/default selection is a hold. There is no generic EXE, shell, script, extra installer argument or parameter-substitution route.

Package scripts, dependencies, lock/consent questions, app interruption and OS writes outside work/ remain material considerations in that exact plan. MSI requests no automatic restart; other package scripts/interruption semantics still need an actual compatibility/restart review, and unsupported guarantees remain held. The service schedules no restart or force-close. The host's normal permission system still applies. No installer process, private installer log, broad log capture or temporary download is generated by issuing a handoff. A separately approved real installation necessarily can create native OS/package records outside work/; those are not toolkit cleanup targets. Unsupported catalog operations remain held for a separately implemented/reviewed adapter; an arbitrary command field never supplies a fallback.

Before the ticket or handoff, patchcairn.external.preflight.v3 evidence must bind the exact action/plan/external-plan hashes, mode/platform, fresh UTC observation and the one reviewed target variant. The target includes its exact identity/version, actual owned artifact_path, complete artifact_record, signature_evidence_id and metadata_evidence_id. The artifact must be the exact reviewed .msi, .pkg or .deb path under owned work, outside known credential boundaries, ordinary/single-link and no larger than the existing 64 MiB proof cap. The service and engine reopen and hash its actual bytes and compare its native identity before the gate; changed bytes or identity hold the operation before a ticket is consumed. Larger or unverifiable offers remain an explicit capability hold rather than an unbounded latest-version action.

The signature evidence is a fresh owned patchcairn.publisher.signature.v3 record containing exact mode/platform, artifact SHA-256, publisher, verified status, source ID, method and UTC observation. Methods are windows.authenticode, apple.pkgutil_check_signature or distribution.signed_metadata, selected by the actual platform. For macOS PKG, the relevant signature tool is pkgutil --check-signature; codesign verifies code and is not the PKG signature recipe. Required Gatekeeper/notarization checks remain separate selected official policy observations. Installed native man/help and actual capabilities must be checked before use; unavailable support is a hold. No native macOS result is claimed here.

patchcairn.installer.metadata.v3 is a second fresh owned observation with exact mode/platform, artifact SHA-256, actual target_id, version, channel, architecture, installation scope, publisher, source ID and UTC time. The target is the actual stable package/product-family identity selected from MSI ProductCode/UpgradeCode metadata, PKG package ID or DEB Package, rather than a prose label or caller-supplied map key alone. Every value must agree with the reviewed plan and the same actual artifact. The coordinator must obtain selected package metadata and signature/repository results using supported official observations, not copy a claim from a webpage or invent success. The service checks exact receipt bindings and actual content/native identity; it does not independently cryptographically validate a publisher from an imported status field. A separate explicit process-call flag records the trusted coordinator's actual verification. A current payload/signature/metadata comparison is required before the assistant's fixed host call; the first mismatch after installation is not an adequate precondition check.

The service returns the full hash-bound handoff and leaves the engine operation active. On Windows, execute_action drains its process-owned worker after consuming the intent and before creating the handoff; an unproved drain or changed owner state prevents the handoff. This is a point-in-time drain, not a reservation: the coordinator must keep toolkit native calls quiet through the external-installer interval. If it performs later native preflight, it must repeat windows_scoped.shutdown_worker() and require True before the official-tool call. The assistant performs only the reviewed official-tool call through its normal host tools and permissions, then registers selected actual target/outcome evidence. Calling the service alone installs or repairs nothing.

An external callback has exactly schema_version: patchcairn.external.receipt.v3, operation_id, action_id, plan_sha256, adapter_payload_sha256, mode, platform, catalog_id, observed_utc, outcome, nullable typed tool_exit_code, postcondition_state (verified, not_verified, unknown), evidence_ids, selected observed_effects, and explicit limitations. Ordinary completion requires actual exit code zero, observed exact-target state and fresh owned evidence after the operation began. The catalog-specific MSI3010 continuation below retains that original nonzero success-with-restart status. Free-text effects/limits are sanitized before persistence. This process-level callback records the trusted coordinator's observation; it cannot authenticate a human, independently infer factual applicability, or certify all security concerns from a submitted field.

For windows.msiexec.install, code3010 means Windows Installer completed the installation and requires a restart; it does not establish verified application behavior or security remediation. The coordinator reports outcome: installed_restart_pending, postcondition_state: not_verified | unknown and a fresh selected boot observation ID. The service privately preserves the exact original receipt and registers patchcairn.restart.pending.v3. The same engine operation stays active and its action remains consumed. No installer is repeated, no code is translated to zero, and no helper restarts Windows. Code1641 under the fixed /norestart arguments is an unexpected restart initiation and accepts only an unknown outcome pending reconciliation. Microsoft Installer result codes.

The pending record binds session, operation/action/plan, original settings/scope, mode/platform, adapter/external-plan hashes, original code3010, the actual private native-receipt path/hash and before_boot_evidence_id. Boot records use exactly patchcairn.windows.boot.observation.v3, mode, platform, observed_utc, last_boot_utc and source: windows.cim_last_boot_up_time; they contain no account or machine name. The trusted coordinator supplies actual selected observations through normal scoped host permissions. This adds no live collector or arbitrary command field.

The owner separately chooses defer or authorizes only the exact owner-handled restart through the engine's decide_restart; update consent is not restart consent. The engine binds that decision to the same operation and current timing. Final patchcairn.restart.verification.v3 evidence references the exact pending/before-boot record, the decision's message ID and a fresh after-boot record, with the actual boot after the authorized not-before time. It accounts for the selected target version/architecture/scope/publisher and every ordered original-behavior check. complete_external_after_restart asks the engine to validate that proof: success needs the exact target and all checks to pass, while a failed/unknown behavior observation supports only a failed or partial result. The actual authorized boot retires the restart item; failure still requires fresh effects/no-active-work/retained-recovery reconciliation and an owner decision before a new plan. No installer or restart is repeated. Pause/stop history is preserved. A stopped session may record a fresh protected owner defer/authorize decision solely to account for its retained exact unfinished MSI3010 operation, including a decision made after stop; the session stays stopped and gains no new plan, ticket, checkpoint or executor. An earlier valid decision can also support actual late result accounting. A missing decision or boot transition holds the same consumed operation. Every result preserves original code3010.

The relevant primary references were consulted 2026-10-24 UTC. Their commands describe capabilities, not authority to run them. Microsoft Windows Installer command line, Apple Gatekeeper and runtime protection, Debian dpkg. Exact installed PKG command capabilities remain a native precondition rather than a claim based on an unavailable archived manual.

Pause, stop and interrupted operations

Pause/stop blocks new dispatcher work before native precondition collection or a new operation begins. An already active effect reaches its safe receipt checkpoint; the helper does not kill an installer, force-close an application or resume a paused session. If the owner pauses/stops after ticket creation but before the first adapter effect, the service records that no adapter was invoked and consumes the ticket without an effect.

The engine accepts the late exact outcome of an already active operation after stop. The service preserves stopped/paused status when recording it; success does not silently resume the workflow. Changing scope/settings during an active operation is refused. Later material changes invalidate old plan/review/approval bindings. Selected checkpoints remain the engine's explicit current-owner decisions.

If a native call raises after entering its effect boundary, a file may already have moved or been written before its step receipt. The service records a categorical unknown with possible partial effects and retains the original full intent, ordered mappings, native attempt/step/outcome records and required recovery. It excludes raw exception text. No automatic retry occurs, even when a final outcome file is missing.

reconcile_operation can establish success only by reopening the exact immutable native outcome and verifying actual archive/restored/quarantined/purged state through the storage library. Native outcome and probe-outcome files must pass private-file admission before their content is read. A fresh real observation can resolve an earlier unknown through the engine while preserving history. Absent, privacy-refused or inconsistent native outcomes remain unknown and consumed. External and Windows diagnostic handoffs require their actual bounded callbacks; the service never manufactures an outcome because time passed or a process disappeared.

Old receipts cannot acquire a new scope or settings revision. Callbacks and reconciliation require the original intent's exact scope, settings revision and immutable operation binding to match the current session; reconciliation checks this before native artifacts are opened, and completion checks fresh state again before writing or registering an outcome. A mismatch is held without relabeling, migration or retry. Read-only inspection can still show the original historical intent. Pause/stop and ordinary event-revision changes under the same scope/settings authority still permit actual late outcome accounting.

Read-only terminal surface

scripts/patchcairn_service.py exposes catalog, status SESSION_ID and inspect-operation SESSION_ID OPERATION_ID, with optional internal --json. It accepts named work-relative engine/service storage only. There is no CLI operation that imports and executes a JSON action, approves a plan, creates a host schedule, purges files or runs a shell command. Use the coordinating assistant and the actual engine/library APIs for reviewed work.

Validation evidence and limits

The included service tests (source package: tests/test_workflow_service.py), diagnostic tests (source package: tests/test_diagnostic_core.py) and platform privacy tests provide reproducible fixture entrypoints; the repository's current CI selects supported platform groups. They use selected synthetic ordinary files, actual checked filesystem/archive operations where the host supports them, fictional owner/review decisions, mocked POSIX diagnostic output and non-executing official-tool handoffs. No test inventories the laptop, reads real logs, installs software or performs a live repair. Native OS command behavior is not inferred from fixture results.

The privacy delta has separate native Windows tests for owner-private namespace/file admission and refusal of preexisting broad namespaces before markers or payloads, plus actual mounted-filesystem refusal tests. Positive fixture groups skip only the identified unsupported privacy capability. The earlier archive/move/purge functional checks remain historical evidence for unchanged operation logic; a new private-mode guard is not represented as a passing functional run on the unsupported mounted filesystem.

The suite checks mismatched approved/actual plans, wrong root/output/type/hash, content and precondition freshness, reused tickets, pause/settings/stop/checkpoint boundaries, late callback evidence, exact protected recovery, separate purge loss acknowledgment, diagnostic fixture isolation, and interruptions after a real fixture write/move. A mounted filesystem that cannot provide native no-overwrite moves must hold/skip that success path; it must not use a copy/delete fallback. Actual host results and capability skips remain part of the evidence. Hosted Ubuntu and macOS ARM64 jobs passed native fictional backup/probe/retention and quarantine/restoration checks, including interrupted receipt accounting after an actual move; see the hosted fixture record. Diagnostic and installer contracts remain injected or nonexecuting, and broader native support is not inferred.

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