@byok-sdk/client 0.8.0 → 0.8.1

package/README.md

@@ -108,6 +108,14 @@ createDaemon({
 });
 ```
 
+For task-free desired-state projection, use
+`createAgentHomeProjectionConsumer`. Its hook must atomically and idempotently
+ensure its opaque product bytes. BYOK may invoke it again under the same
+canonical-home writer lease when a new request carries the exact current
+revision/hash; the terminal outcome remains `idempotent`. This permits repair
+of locally lost derived files without giving the SDK product path or schema
+knowledge. Stale and same-revision/different-hash requests do not invoke it.
+
 Startup materializes and write-probes the canonical root before publishing
 `agent-home-contract`. `agentHome` and `gitWorkspace` are mutually exclusive;
 strict Agent execution has one workspace authority and never falls back to a
@@ -131,6 +139,13 @@ keeps runtime activity metadata/status-only; enabling it is an explicit product
 decision and requires the server capability. Reliable events are fsynced under
 the canonical Agent home and retire only after an exact ack.
 
+Hosts that need cold setup or diagnostic state use
+`readDeviceEnrollmentStatus({ productId, storeDir })`. It validates the
+complete SDK-owned record but returns only `unpaired`, `paired` with
+`deviceId`, or `re_pair_required`; tenant, token, expiry and device keys are
+never projected. Only explicit pairing may replace `re_pair_required` state,
+while filesystem-safety failures remain errors.
+
 ```ts
 createDaemon({
   // ...normal device, transport and agentHome configuration

package/dist/agent-home.d.ts

@@ -48,7 +48,11 @@ export interface AgentHomeProjectionApplyInput extends AgentHomeProjectionInput
 export interface AgentHomeProjection {
     /** Optional creation/task-time host preparation retained as a distinct lifecycle. */
     prepare?(input: AgentHomeProjectionInput): void | Promise<void>;
-    /** Task-free opaque projection consumer. Its successful return means its own bytes are durable. */
+    /**
+     * Task-free opaque desired-state consumer. It must atomically and
+     * idempotently ensure its own durable bytes because exact revision/hash
+     * requests may replay after local derived-file loss or transport failure.
+     */
     apply?(input: AgentHomeProjectionApplyInput): void | Promise<void>;
 }
 export type AgentHomeProjectionFunction = (input: AgentHomeProjectionInput) => void | Promise<void>;
@@ -82,7 +86,15 @@ export declare class AgentHomeLayout {
      * file is created by this preflight.
      */
     preflight(): Promise<void>;
+    /**
+     * Construction-time validation is deliberately non-mutating. The actual
+     * writable preflight runs asynchronously after daemon ownership is acquired
+     * and before transport/capability publication, where it can participate in
+     * the cross-process relocation gate without a sync shadow lock.
+     */
+    preflightSync(): void;
     private resolveRoot;
+    private acquireRootMutationGate;
 }
 export declare function stableAgentHomeOwnerId(storeDir: string, productId: string): string;
 /** One-writer lease backed by both a process registry and an exclusive marker. */
@@ -108,6 +120,8 @@ export declare class AgentHomeManager {
     prepare(agentRef: AgentRef): Promise<AgentHomeBinding>;
     /** Validate the configured root before capability publication. */
     preflight(): Promise<void>;
+    /** Synchronous construction-time preflight for strict Agent-only admission. */
+    preflightSync(): void;
     /** Resolve and lease without applying downstream projection side effects. */
     acquire(agentRef: AgentRef): Promise<AgentHomeBinding>;
     /** Initialize only after any requested session exact-match has succeeded. */
@@ -115,11 +129,17 @@ export declare class AgentHomeManager {
     supportsTaskFreeProjection(): boolean;
     /**
      * Apply one task-free projection under the same canonical-home writer lease
-     * used by Agent execution. Only a successful host hook followed by the
-     * SDK-owned fsynced ordering record can return `applied`.
+     * used by Agent execution. The host hook owns an atomic/idempotent ensure of
+     * its opaque product bytes, so an exact desired-state replay invokes it again
+     * before returning `idempotent`. Only a successful new-state hook followed
+     * by the SDK-owned fsynced ordering record can return `applied`.
      */
     project(input: AgentHomeProjectionPayload): Promise<AgentHomeProjectionOutcome>;
 }
 export declare function createAgentHomeProjection(prepare: AgentHomeProjectionFunction): AgentHomeProjection;
-/** Create only the task-free opaque projection consumer; no task-time fallback is inferred. */
+/**
+ * Create the task-free atomic/idempotent opaque desired-state consumer.
+ * Exact revision/hash delivery may invoke it again before an idempotent receipt;
+ * no task-time fallback is inferred.
+ */
 export declare function createAgentHomeProjectionConsumer(apply: AgentHomeProjectionApplyFunction): AgentHomeProjection;