@hivecast/fleet-integration-owner (1.1.33)
Installation
@hivecast:registry=npm install @hivecast/fleet-integration-owner@1.1.33"@hivecast/fleet-integration-owner": "1.1.33"About this package
Fleet Integration Owner
The Matrix actor independently combines a ticket's exact candidate, checks the
combined head and publishes that exact head to source main. Its installed
completion policy then either stops at independently verified source publication,
or uses the incumbent delivery owner and verifies the target's served revision.
Only then does it close the central ticket with its own enrolled unit proof. It
does not run the source-writing agent.
Its installed configuration selects the target, checkout, authoritative source
branch and completion policy;
requests cannot override these operational settings.
mainBranch is restart-only installed configuration and defaults to main.
Repository adoption sets it to that repository's authoritative branch (for
example, master); preparation and publication both use the same installed
remote ref and never accept a caller-selected branch.
Under target-served, before fetching or combining source the owner asks the
incumbent lifecycle tool to prove that the configured checkout belongs to the
configured target. A missing, unreadable or mismatched status refuses without a
Git or delivery effect. The same target identity is checked again after delivery
before any served revision can be attributed to the operation. source-only
never calls that lifecycle or delivery boundary.
Each delivery attempt invokes the incumbent delivery module's land API once,
with its exact combined revision and normal rollback. It does not use the CLI's
queue-draining or failure-bisection mode: a failed candidate cannot silently deliver
a different revision under the same operation identity. The native child-process
regression in src/__tests__/git-land-output.spec.ts verifies that entry boundary.
The package factory reads the exact host-bound installed configuration once at
startup. These settings are restart-only; it creates no settings subscription or
fallback file. Composition-backed installs intentionally pass an empty config
envelope, so the installed owner—not that empty argument—supplies checkout,
target and receipt storage. Direct settings and the launcher envelope remain
supported for standalone use without an installed binding. A bound but
unavailable or mismatched source refuses startup rather than using those values.
Calling from a coordinator
Import UnitIntegrationClient from @open-matrix/package-runtime/host/unit-integration-client.js with the existing runtime host unit-proof port and a
request function bound to the configured qualified integration actor. Each
request borrows the host's current proof. No person's token is retained or
substituted. Central Tickets admits submission for the exact checked candidate
by its current source claimant, or the verified same-home owner/operator. That
is not permission to integrate. Only this target's independent integration unit
holds tickets.integrate; its current host proof and target grant are checked
before Git or delivery. A second runtime on the writer's host does not make a
different principal and is refused. No grant is minted by this client.
Delivery commands use the shared package-runtime ToolchainEnvironment, also
used by native coding/workspace commands. Combined-head source checks run with
bash -c, never a login shell, and receive only the selected tool PATH plus the
immutable HIVECAST_INTEGRATION_MAIN_BASIS and
HIVECAST_INTEGRATION_COMBINED revision fences. Ambient credential variables and
login-profile effects are not copied into those checks. The runtime's own
environment remains unchanged. Native child-process tests cover the tool and
source-check environment boundaries before a staging delivery; S30 exercises the
owner through the real integration route.
Reopening an existing receipt uses Tickets' observe admission, including after the exact execution is finished. A new operation requires submit admission for an active execution; a completed ticket cannot silently launch another delivery. Tickets remains the authority for claimant, candidate and checks.
const client = new UnitIntegrationClient(unitProof, (op, payload) =>
RequestReply.execute(context, configuredIntegrationOwner, op, payload));
const answer = await client.request({ operationId, ticketRef, generation, candidate, target });
// The same ID and tuple identify this operation throughout its lifetime.
const observation = await client.get(operationId, retainedRequest);
ok means the owner answered, not that code landed. Inspect receipt.state:
| State | Next action |
|---|---|
| queued / running | Observe the same operation; do not start another execution. |
| published | Terminal source-only completion: verify published === combined, no served revision, the exact retained workflow and central closure. Do not call this deployed. |
| landed | Read the central ticket and the distinct candidate, combined, published and served revisions. |
| refused | Address the reported refusal. Only a known INTEGRATION_SOURCE_CHECK_FAILED before publication, carrying sourceCheckReceiptRef, can fence one explicit same-operation recheck. |
| restored | Inspect published. New receipts retain source publication before a target rollback; older receipts may not. Continue only this retained operation when authorized. |
| unknown | Reconcile this operation with the target and ticket owners. Do not relaunch blindly. |
A safely restored attempt can be explicitly continued with
client.continue(retainedRequest, receipt.deliveryReceiptRef). The complete
ticket/generation/candidate/target tuple and the exact restoration receipt fence
must match. The owner rechecks current Tickets admission and its independent
integration grant, and keeps the same operation ID with a new attempt number and
bounded restoration history. The new attempt fetches current main, combines the
same candidate, independently checks that combined head and uses normal non-force
publication before target delivery. This includes repairs committed after the
restored attempt; it does not blindly redeploy its failed old revision. The old
combined, publication and delivery evidence remains in restoration history, not
as proof of the new attempt. Already-published ancestry needs no duplicate push.
A duplicate
continuation observes the active or finished attempt; lookup, reopen, unknown
outcomes and stale fences never start another delivery. The installed Fleet route
uses this operation only when the person explicitly continues the selected case.
A known source-check failure before publication can likewise be explicitly
continued with client.continue(retainedRequest, { expectedSourceCheckReceiptRef: receipt.sourceCheckReceiptRef }). The owner
accepts that fence only when the retained receipt is the same semantic operation,
is refused specifically with INTEGRATION_SOURCE_CHECK_FAILED, names that exact
failed check receipt, and has no publication or delivery evidence. It rechecks
the current ticket generation, candidate checks and independent integration
grant, then prepares and qualifies against current main as the next attempt. The
prior failed receipt remains in checkReceiptRefs. A mismatched fence, another
refusal, any publication/delivery uncertainty, duplicate call or reopen is
observation-only. There is no automatic retry.
Installed completion policy
completionPolicy is restart-only installed configuration and defaults to
{"kind":"target-served"}. That policy requires baseUrl and identityFile,
publishes the checked combined head, delivers it through the established target
lifecycle, and closes Tickets with integrationOutcome: "target-served" only
when served === combined.
A source-only occurrence is explicitly pinned to one admitted workflow identity:
{
"kind": "source-only",
"workflow": {
"recipe": "fleet.develop",
"revision": "sha256:<exact admitted revision>"
}
}
It needs no deployment URL or identity file. It still combines against current
main, runs the installed source checks, publishes through the configured remote,
verifies remote ancestry and closes Tickets independently. Its terminal receipt
is published; Tickets records published === combined, no served revision,
and integrationOutcome: "source-published". The workflow must match both the
installed policy and central Tickets before any Git effect. The owner retains the
policy and workflow on every receipt, so changing installed configuration cannot
reinterpret or continue an existing operation under a different disposition.
Neither a caller flag nor a request payload can select this policy.
Install source-only work as its own named Fleet Integration Owner occurrence.
Its settings contain authorityRoot, a distinct target, the integration
checkout, its authoritative mainBranch, isolated candidateSource and stateFile paths, trusted
sourceChecks, the exact completionPolicy, and optional receipt/Tickets
settings. Do not copy baseUrl, identityFile, sessionHome, journeys,
readySeconds or settleSeconds from a delivery occurrence: activation refuses
those target-lifecycle fields for a source-only owner. The matching Smithers
occurrence names this owner's exact qualified mount and target; it does not reuse
the target-serving Smithers occurrence or its work folder. This keeps source
publication independent from shared deployment custody while using the same
Tickets, workflow and integration contracts.
Installed source checks and migration
sourceChecks is a required restart-only installed setting. It is a bounded array
of trusted operator-owned commands; request payloads cannot supply or replace it.
Every command runs in the isolated worktree at the exact combined head. A normal
HiveCast installation uses the existing affected-owner qualifier rather than a
second test scheduler:
[
"pnpm install --frozen-lockfile --prefer-offline",
"node tools/qualification/run-affected-owner-suites.mjs --base \"$HIVECAST_INTEGRATION_MAIN_BASIS\" --head \"$HIVECAST_INTEGRATION_COMBINED\" --artifacts tmp/fleet-integration-owner-qualification"
]
For an existing occurrence, first call preferences.describeInstance for that
exact Fleet Integration Owner target. Then call preferences.set with
key: "sourceChecks", the array above as value, and the returned revision as
expectedRevision. Activate the restart-only change through the incumbent
target's normal idle restart path. Do not edit an occurrence file or restart a
shared target directly. The installed command redirects qualifier evidence to
the ignored tmp/fleet-integration-owner-qualification path inside the isolated
worktree. That output is removed only after Git proves the
checked head and tracked/untracked source are unchanged. Failed or mutated check
worktrees are preserved with their receipt for diagnosis.
A lost transport reply returns INTEGRATION_OUTCOME_UNKNOWN with the original
operation ID. Explicit lookup uses a newly borrowed proof. No automatic retry,
timer, worker, credential cache or subscription is created. Mismatched receipt
identities refuse rather than completing a different ticket. Supplying the retained
request to get checks the complete ticket/generation/candidate/target tuple, not
only its operation ID. Unverified proofs
invalidate the host's cache through its existing contract; a grant refusal does
not broaden authority or refresh-loop.
Executable help and acceptance
The integration receipt lesson is supplied through the existing Demos catalogue
(S27, applications/demos/src/catalogue/fleet-integration.ts). It reads an explicitly
selected operation and distinguishes missing inputs, refusal, running, unknown,
restoration and landing. It displays a retained sourceCheckReceiptRef when one
exists, but reading or running the lesson does not continue or submit delivery.
The same program is exercised by src/__tests__/integration-lesson.spec.ts against
the real integration actor and durable receipt store. Its fixture substitutes the
external delivery backend; it is not proof of installed target delivery.
The landing case also crosses the command-output adapter using the lifecycle
owner's actual multi-line JSON format. Incomplete status output remains unknown;
it cannot supply served-revision evidence or close the ticket.
The delivery tool's RESTORE INCOMPLETE also stays unknown, preserving its
failure and delivery reference for reconciliation. Only RESTORED proves the
rollback completed; the canonical lesson exercises both command results and
never tells the person an unfinished rollback restored their target.
Run pnpm --dir applications/fleet-integration-owner test and type-check for the
owner/client tests. Native ownership, lost-reply and restart tests remain alongside
the lesson. C05 still owns Smithers route wiring, the full ticket-to-completion
lesson and the two-improvement live acceptance. C06 owns qualified workflow
restart acceptance. This package's client and diagnostic do not close those orders.
The installed lesson's discovery and empty-input path have a separate browser regression at desktop and phone widths. It opens Demos from Start, finds S27 through Explorer, compares the installed program with the package catalogue and presses Run. It neither submits an integration request nor proves a retained operation:
HIVECAST_BASE_URL='<door>' HIVECAST_PROOF_IDENTITY_FILE='<machine-local-0600-file>' \
pnpm --dir tests/browser-regression exec playwright test \
journeys/fleet-integration-receipt.journey.spec.ts
The normal journey fixtures use a secondary session and restore their own state; the runner closes its browser. Actual receipt/delivery acceptance still requires the configured integration owner and an existing admitted operation.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @open-matrix/contracts | 1.1.33 |
| @open-matrix/package-runtime | 1.1.33 |
Development Dependencies
| ID | Version |
|---|---|
| @open-matrix/core | 1.1.33 |
| @open-matrix/omega-core | 1.1.33 |
| @types/node | ^25.0.10 |
| esbuild | ^0.25.0 |
| tsx | ^4.15.6 |
| typescript | ^5.7.0 |
Peer Dependencies
| ID | Version |
|---|---|
| @open-matrix/core | 1.1.33 |