Documentation
¶
Overview ¶
Package bundle builds Release C artifacts: installable, target-shaped Facet packages for external agentic CLIs.
RELEASE C is the projection where the TARGET CLI is the reasoning driver. Facet ships the creative intelligence -- agents, skills, packs, instructions and tool wiring -- shaped to whatever that harness natively expects.
The target-adapter rule, same as Operations:
canonical Facet asset -> target adapter -> target-shaped release asset
Different packaging is allowed. Different product semantics are not. Four hand-maintained copies of one skill is the failure this prevents, and it is the duplicated-truth defect one layer up from a second effects table.
A bundle is a DIRECTORY plus a manifest, not an opaque archive: an installer must be able to see what it is about to write before it writes it, and a human must be able to read what was installed afterwards.
Index ¶
Constants ¶
const AdapterVersion = "1"
AdapterVersion is the version of the PROJECTION LOGIC, distinct from the Facet version.
These answer different questions. FacetVersion says which product truth was projected; AdapterVersion says how it was shaped for this target. A fix to a target's layout changes the second without changing the first, and an installer needs to tell those apart to decide whether a reinstall is warranted.
const CapabilityID = "xibodev.facet"
const ManifestSchema = "xibodev.facet.bundle/v1"
ManifestSchema identifies the bundle manifest format.
Versioned separately from Facet itself: an installer reads the manifest BEFORE it knows anything else about the bundle, so the manifest's own shape has to be the one thing it can rely on.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Compatibility ¶
type Compatibility struct {
// InstallRoot is where the target discovers assets, relative to a project
// or a user home depending on Scope.
InstallRoot string `json:"install_root"`
// Scope is "project" or "user".
Scope string `json:"scope"`
// ToolTransport is how this target actually invokes Facet.
//
// DELIBERATELY NOT ALWAYS MCP. Facet exposes no MCP server today -- tools
// are CLI-invoked -- so declaring MCP would describe a transport that does
// not exist. Every listed target can shell out, so "cli" is the honest
// answer now, and a target better served by MCP later gains a projection
// rather than forcing a rewrite.
ToolTransport string `json:"tool_transport"`
// FacetBinary is the executable an agent must invoke.
FacetBinary string `json:"facet_binary,omitempty"`
// NativeProvider identifies the in-process provider compiled into a host.
NativeProvider string `json:"native_provider,omitempty"`
// KernelModule and KernelVersion identify the compatible public kernel API.
KernelModule string `json:"kernel_module,omitempty"`
KernelVersion string `json:"kernel_version,omitempty"`
}
Compatibility is what the target harness must supply for this bundle to work.
type Entry ¶
type Entry struct {
// Path is relative to the target's install root, forward-slashed so a
// manifest built on Windows installs identically elsewhere.
Path string `json:"path"`
Bytes int64 `json:"bytes"`
Digest string `json:"digest"`
// Kind records which canonical asset class this came from, so an installer
// can explain what it is writing rather than listing opaque paths.
Kind string `json:"kind"`
}
Entry is one file the bundle will install, with the digest of its content.
The digest is over the PROJECTED bytes rather than the canonical source: what an installer verifies must be what it writes. A digest of the source would confirm the bundle was built from something intact without confirming that what lands on disk is what was measured.
type Manifest ¶
type Manifest struct {
Schema string `json:"schema"`
// --- identity ---
CapabilityID string `json:"capability_id"`
FacetVersion string `json:"facet_version"`
Target Target `json:"target"`
AdapterVersion string `json:"adapter_version"`
// --- compatibility ---
// Compatibility states what the TARGET must provide, so an installer can
// refuse a bundle rather than write files that will not be discovered.
Compatibility Compatibility `json:"compatibility"`
// --- content ---
Entries []Entry `json:"entries"`
// BundleDigest covers every entry digest in sorted order. It answers "is
// this the bundle that was built", which is a different question from any
// single file being intact.
BundleDigest string `json:"bundle_digest"`
// Tools names the public vocabulary this bundle exposes. Recorded so an
// installed bundle can be compared against the running Facet: a bundle
// naming tools the binary does not have is a stale install, and that is
// otherwise invisible.
Tools []string `json:"tools"`
}
Manifest is the bundle's identity, provenance and install plan.
func Build ¶
Build projects the canonical source into a target-shaped bundle on disk and returns its manifest.
outDir is created if absent and must be empty or nonexistent: a builder that merges into a populated directory can produce a bundle whose manifest does not describe its contents.
func Verify ¶
Verify checks an installed or built bundle against its own manifest.
Answers "is this bundle intact and complete", which is different from "did the build succeed". A build that succeeded and a bundle that is whole are separate claims, and this repo has already shipped a bundle that reported success while missing the files that made it renderable.
type Source ¶
type Source struct {
// SkillsDir and PacksDir are canonical product truth. The builder reads
// them and projects the same semantics into every target.
SkillsDir string
PacksDir string
AgentsDir string
SchemasDir string
// Tools is the public vocabulary, supplied by the caller so the builder
// never holds a second copy of it.
Tools []string
// FacetVersion is the product version being projected.
FacetVersion string
}
Source is the canonical asset tree a bundle is projected from.
Source Files