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 |
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 / buildProfileDraft |
yes | no | no | read-only probe | 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 | no | read-only allowlist | no | none | exit code 1 (findings) / 2 (mechanism) |
renderReportAction / checkReportAction |
yes | only --out/--binding |
no | no | no | default stdout only | SFC3001/SFC3002/SFC3003 |
probeGitState / probeGitFacts |
yes | no | no | 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 command | per command | per command | per command | no | per command | 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.
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.
- Projection: any validation failure rejects wholesale, zero writes; overwriting an existing file requires declaring the
expect.sha256pre-state. - adopt-plan / check: structurally read-only, byte-level zero change before and after running.
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.