简体中文

Public API Reference

This page is the English entry point for the public APIs of the three Foundation packages. It is a human-readable route into the machine facts in the capability catalog; package exports, schemas, protocols, and stable error codes remain authoritative.

Choose the Owning Layer

Package	Use it for	Start with
skill-family-contracts	Object schemas, protocol registries, validation, stable error codes, fixtures, and deterministic audit surfaces	foundation.contracts.object-validation, foundation.contracts.registry-protocol, foundation.contracts.audit-surface
skill-family-harness-node	Business-neutral Node mechanisms such as contained paths, atomic writes, subprocess requests, durable local state, and deterministic reports	foundation.harness.path-containment, foundation.harness.atomic-write, foundation.harness.state-store, foundation.harness.report
skill-family-engineering-kit	The four engineering commands and controlled host/Profile integration	foundation.kit.scaffold, foundation.kit.adopt-plan, foundation.kit.projection, foundation.kit.check, foundation.kit.host-integration

The dependency direction is Contracts → Harness → Engineering Kit. A Profile declares host or project-shape differences horizontally; public core code does not depend on a concrete Profile.

Verified Capability Details

Use the following public data files before selecting an entry point:

1. Core capability facts contain stable IDs, packages, layers, entry points, stability, source references, and test references.
2. English capability explanations add intent, use and non-use conditions, inputs, outputs, failure semantics, caller ownership, and external routing for the same IDs.
3. Catalog schema defines the closed structure of both files.

The failure and side-effect matrix compares filesystem, process, Git, network, residual-state, and error behavior across public entry points. The architecture routing guide starts from design intent when the package or capability is not yet known.

Key Failure Rules

• Contracts document validation returns { valid: false, errorCode, errors } for ordinary validation failures. Callers inspect valid; validateDocument does not turn those failures into exceptions.
• Harness mechanism failures use SFC2004 (EXECUTION_FAILED) and distinguish the failure with a frozen details.kind value.
• Engineering Kit keeps exactly four top-level commands: scaffold, adopt-plan, projection, and check. Each command retains its documented read-only or controlled-write boundary.
• Candidate capabilities are marked stability: candidate in the catalog. Their presence in the public package does not promote them to the stable surface.

Quickstart Profile v2 Candidate

All three packages expose v2 through their existing candidate subpaths. Contracts defines the business-neutral execute-method exchange, Harness verifies bytes and bindings, and Kit turns explicit consumer schemas into an offline Bundle with standalone validators selected by schema $id. Version 0.3.0 candidate v2 is incompatible with the 0.2.1 candidate v1; consumers must pin the selected package versions exactly.

Detailed Package Pages

The current signature-level package pages are maintained in Chinese because they enumerate every verified export and test reference:

• Contracts API details
• Harness API details
• Engineering Kit API details

These pages are part of the same public site and link to source and test evidence. The English catalog overlay provides the complete English intent and failure semantics for every capability, so an agent can route and design against Foundation without inferring meaning from the Chinese prose.

Boundary

Foundation does not own domain schemas, business state machines, audit conclusions, task/retry orchestration, artifact relationships, or remote publishing. Keep those semantics with the caller, or route them to the external project named by the capability catalog.