Failure and Side-Effect Matrix¶
This page lists, per public entry point, read/write, spawn, Git, network, residual state, and stable error codes. It serves callers judging risk before integrating, and is the human-readable projection of the sideEffects and failureSemantics fields in capability-catalog.json. All facts are based on the real implementation and negative tests.
Symbol convention: read = reads the filesystem; write = writes the filesystem; spawn = launches a subprocess; Git = reads/writes Git; network = accesses a remote; residual = state still left on disk/in-process after the call ends.
Contracts (Pure-Function Layer)¶
| Entry | read | write | spawn | Git | network | residual state | stable error code |
|---|---|---|---|---|---|---|---|
validateDocument |
no | no | no | no | no | none (compile cache memory-resident only) | SFC1001/SFC1002/SFC1006 |
compileSchema / detectDialect |
no | no | no | no | no | none | SFC1006/SFC1012 |
loadRegistry / findSchemaByObject / findProtocol |
no | no | no | no | no | none | SFC1003/SFC1004 |
runChecks / collectUnresolvedRefs |
no | no | no | no | no | none | SFC1002–SFC1010 |
verifyAllFixtures / verifyFixture |
no | no | no? no | no | no | none | SFC1010 |
ERROR_CODES / stableError |
no | no | no | no | no | none | frozen registry, no additions |
Contracts are all pure functions, with no file/Git/network/process side effects; error objects contain stableError and details.kind for easy caller classification.
Harness (Mechanism Layer, Contained)¶
| Entry | read | write | spawn | Git | network | residual state | stable error code |
|---|---|---|---|---|---|---|---|
validateContractDocument |
no | no | no | no | no | none (validator cache in memory) | SFC validation failure |
resolveContained / readFileContained |
yes (read-only) | no | no | no | no | none | SFC2004 (path-traversal/symlink-escape/realpath-escape) |
writeFileAtomic |
no | yes (contained) | no | no | no | failed rollback temp file | SFC2004 (atomic-write-failed) |
TemporaryWorkspace / withTemporaryWorkspace |
no | yes (temp directory) | no | no | no | temp directory cleaned on exit | SFC2004 (workspace-disposed) |
computeResourceClosure / digestBytes |
no | no | no | no | no | none | SFC (declaration/content violation) |
parseRequest / processRequest |
no | no | no | no | no | none (pure-function pipeline) | SFC2004 |
validateReportModel / renderReportMarkdown / buildBinding / checkReport |
no | no | no | no | no | none (pure function) | SFC3001/SFC3002/SFC3003 |
buildAdapterClosure / verifyAdapterBuildManifest |
no | no | no | no | no | none | SFC2004 (missing-resource) |
verifyPeerAdapterDirectories |
yes (bound peer roots) | no | no | no | no | none | SFC2003/SFC2004 (identity, mapping, closure, or path failure) |
materializeAdapterBuild |
no | yes (contained, sibling + rename) | no | no | no | none (atomic rename) | SFC2004 |
probeVersionVector |
no | no | default no (requires explicit --allow-host-spawn) |
no | no | none | SFC2004 |
openStateStore / appendEvent / readEvents / writeSnapshot |
yes | yes (event/snapshot/lock files) | no | no | no | event log + lock file | SFC2004 (store-locked/chain broken) |
inspectStateStoreLock / recoverStateStoreLock |
yes | yes (recovery write-lock only) | no | no | no | lock file (monotonic fencing) | SFC2004 |
runMechanismCliBatch / mechanisms-cli.mjs --batch (since 0.19.0, candidate) |
no | no | no | no | no | none (only the caller-provided output/error streams are written) | exit code 0 (all succeeded) / 2 (at least one item failed or whole batch refused); details.kind closed to batch-structure-invalid/batch-item-limit/batch-input-limit/batch-output-limit |
applyFileSet / recoverFileSet / pruneFileSetRecovery (since 0.21.0, candidate) |
yes (contained read-only; recovery materials and root-binding re-verification) | yes (strict publication / atomic replacement on business targets plus recovery materials under the fixed in-root .foundation-file-apply) |
no | no | no | recovery materials (journal and operations/<id>/{before,after}/<index>) are retained by default; only an explicit prune removes the materials of a terminal operation |
catchable failures return a file-set-result; the outer code stays SFC2004 with closed details.kind and details.phase enums, and outcome/paths/materials report per-path facts |
The file-set entry point likewise determines observable effects by failure stage. Whole-group preflight failure, unsupported environment, and capacity breach return before any business write and leave zero business writes. Domain validation that returns false, throws, times out, or returns an invalid result triggers automatic recovery, with validation state reported separately from recovery state. Recovery keeps external content for conflicting paths and continues with the remaining safe paths. A valid commit event is never rolled back; when target re-verification or durability is unconfirmed the result is commit-unconfirmed and the materials are retained. No business path is touched before a durable apply-intent fact exists for that path, instantaneous multi-file visibility is not promised, and uncooperative concurrent writers are not resisted; recovery requires the caller to establish an exclusive maintenance interval first, while prune takes the normal writer when nothing is left over and requires that same maintenance precondition only for a fault takeover.
The failure stage determines the observable effects of the batch entry point. Request-byte, item-count, and structure preflight rejection invokes no mechanism and leaves stdout empty. Output capacity can be checked only after the current item returns, so that item may already have executed; later items are not executed and stdout remains empty. An output-channel failure may leave partial bytes sent and returns 2. If the error channel also fails, delivery of the error object is not guaranteed.
Harness's HARNESS_EXCLUSIONS explicitly excludes release-state, remote-network-access, business-semantics, workflow-orchestration, model-calls, git-writes.
Engineering Kit (Engineering Command Layer)¶
| Entry | read | write | spawn | Git | network | residual state | stable error code / exit code |
|---|---|---|---|---|---|---|---|
scaffoldTarget |
no | yes (contained skeleton, atomic + contained) | no | no | no | none (no half-product on failure) | SFC2004 (target-not-empty) |
planAdoption |
yes | no | default may spawn one frozen read-only Git status probe (disableable) | read-only probe | no | none (stdout output) | SFC completion false |
buildProfileDraft |
no | no | no | no | no | none (stdout output) | SFC completion false |
runProjection |
yes (reads manifest) | yes (managed path, two-phase) | no | no | no | none (zero write/rollback on failure) | SFC2004 (unauthorized-path/handwritten-overwrite/conflict-drift) |
runChecks (check) |
yes | no | default may spawn one frozen read-only Git status probe; --no-git-spawn disables it |
read-only allowlist | no | none | exit code 1 (findings) / 2 (mechanism) |
runChecks (declared version) |
yes (declared references only) | no | no | no | no | none | exit code 1 (findings) / 2 (mechanism) |
runEntryContractCheck (legacy / declared) |
yes | no | no | no | no | none | exit code 1 (findings) / 2 (mechanism) |
runCommand("check") / checkEntriesAction + conclusionOutput |
yes | yes (exclusive creation of one file under an existing output root) | no | no | no | conclusion file retained on success; conflicts never overwrite | exit code 0/1/2; structure SFC1001, publication SFC2004 |
check relock |
yes | yes (explicit controlled write) | no | no | no | controlled relock transaction state | exit code 0/1/2 |
check qualification / runQualification |
reads request and bindings | writes private evidence under caller-bound roots | yes, after preflight | no | bound executable may access the network | evidence is retained when the end state is indeterminate | exit code 0/1/2; four-state result |
runPluginVerification |
yes (bound roots) | yes (fresh workspace, host state, private evidence) | yes, local executable only | no | bound executable may access the network | uncertain evidence is retained | four-state plugin-verification-result |
runSkillFamilyDirectoryVerification |
yes (bound roots) | yes (private raw evidence) | yes, local executable only | no | bound executable may access the network | uncertain evidence is retained | four-state directory result |
renderReportAction / checkReportAction |
yes | only --out/--binding |
no | no | no | default stdout only | SFC3001/SFC3002/SFC3003 |
probeGitState / probeGitFacts |
yes | no | default may spawn one frozen read-only Git subprocess; disableable | read-only allowlist | no | none | SFC (over-privileged parameter refused) |
describeHost / resolveHostId / probeHost / buildHostAdapter / verifyHostPeers / planHost |
yes | build writes (contained) | probe default no | no | no | none | SFC2003/SFC2004 |
applyHostPlan |
yes | bounded local install/update | no | no | no | staging is cleaned; result records partial/indeterminate publication | SFC2003/SFC2004; uninstall returns manual-recovery-required without deleting |
loadLicensingProfile / generateLicenseContent etc. |
no | no (pure-function generation) | no | no | no | none | SFC (illegal Profile) |
checkIdentityDrift / validateIdentityAgainstProfile |
yes | no | no | no | no | none | findings |
cliMain / runCommand |
per action | per action | per action | per action | per action (bound executable may access the network) | per action | exit code 0/1/2 |
Kit's FORBIDDEN_SIDE_EFFECTS includes git-init/commit/push/tag, publish, remote-write; REFUSED_MUTATION_FLAGS (including --apply) are refused at the CLI entry point. The package API applyHostPlan does not add a fifth command or grant generic/remote apply.
Foundation itself does not issue network requests, but a bound executable may access the network. Foundation provides no sandbox or egress blocking; callers and the execution environment own that isolation. The Qoder, WorkBuddy, and Kimi entries remain manual/candidate; controlled fixtures prove production wiring only and do not grant real-host qualification.
Residual-State Collection¶
- Atomic write: on failure, rolls back the temp file, leaving no half-product in the target directory.
- Temporary workspaces are cleaned on exit, including exception paths.
- State store: the event log is the sole authority, and the snapshot is a derived cache; a crash-left lock requires the caller, outside Foundation, to confirm the old writer has terminated before explicitly recovering; no silent lock-stealing.
- File set: recovery materials are retained by default under the fixed in-root
.foundation-file-apply; only an explicit prune removes the exact materials of a terminal operation and keeps the journal. Materials of unfinished or conflicting operations are never cleaned. The mechanism never deletes unknown adjacent staging files by suffix; it only reportspossible-unknown. - Projection: any validation failure rejects wholesale, zero writes; overwriting an existing file requires declaring the
expect.sha256pre-state. - adopt-plan, ordinary runChecks, and ordinary check are structurally read-only and write no files; by default they may spawn one frozen read-only Git status subprocess, disabled by
--no-git-spawn(or APIallowGitSpawn: false), with byte-level zero change before and after running. The side effects of check relock and check qualification are listed above. - Declared
runChecksandrunEntryContractCheckdo not probe Git, execute the target, or write files. Only the two existing wrappers exclusively create a conclusion file whenconclusionOutputis complete.
What the Caller Should Do After Failure¶
- Validation failure (
SFC1001/SFC2002/SFC2003): check whether the input satisfies the target Schema or parameter contract; do not retry a registration that has been frozen-refused. - Containment failure (
SFC2004+path-traversal, etc.): confirm whether the root directory and path are out of bounds; do not cram business-selection rules into Foundation. - State-lock conflict (
store-locked): outside Foundation, confirm the old writer has terminated, then call recovery with the exactly-matching owner/fencing. - check findings (exit code 1): address the findings; Kit does not auto-fix.
Windows failure and cleanup boundaries¶
publishFixedSetGeneration writes a pointer and retains all generations. resolveFixedSetGeneration is read-only. Unknown temporary files are preserved without suffix-based cleanup. A whole-group file-set preflight refusal leaves zero business writes. Job Object cleanup requires zero active processes, both streams flushed and closed, and all handles closed within killGraceSeconds. Do not retry uncertain states.