跳转至

简体中文

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 reports possible-unknown.
  • Projection: any validation failure rejects wholesale, zero writes; overwriting an existing file requires declaring the expect.sha256 pre-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 API allowGitSpawn: false), with byte-level zero change before and after running. The side effects of check relock and check qualification are listed above.
  • Declared runChecks and runEntryContractCheck do not probe Git, execute the target, or write files. Only the two existing wrappers exclusively create a conclusion file when conclusionOutput is 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.