@camstack/types 1.2.267 → 1.2.269

package/dist/composition/field-kinds.d.ts

@@ -0,0 +1,42 @@
+import { type CompositionFieldSource } from './composition.js';
+import type { CompositionFeatureMode, CompositionFieldRole, CompositionProblem, CompositionProblemCode, CompositionUnavailableMode } from './composition-report.js';
+import { type ExpressionKindSet } from './expression-kinds.js';
+import { type StateFieldDescription } from './state-fields.js';
+import type { CapabilityLookup } from './validate-composition.js';
+interface KindsFound {
+    readonly ok: true;
+    readonly kinds: ExpressionKindSet;
+}
+interface KindsRefused {
+    readonly ok: false;
+    readonly code: CompositionProblemCode;
+    readonly message: string;
+}
+type KindsResult = KindsFound | KindsRefused;
+export declare function sourceKinds(source: CompositionFieldSource, lookupCap: CapabilityLookup): KindsResult;
+export declare function compatibility(cap: string, target: StateFieldDescription, kinds: ExpressionKindSet, at: string): readonly CompositionProblem[];
+/**
+ * An enum target whose source is a save-time-KNOWN string literal outside its
+ * `enumValues` is refused now rather than left to fail the write later. A
+ * dynamic source (a `from` read, a non-literal expression) is left to
+ * runtime — see {@link literalStringValue}.
+ */
+export declare function enumLiteralProblem(cap: string, target: StateFieldDescription, source: CompositionFieldSource, at: string): CompositionProblem | null;
+export declare function roleOf(source: CompositionFieldSource): CompositionFieldRole;
+interface UnavailableChosen {
+    readonly ok: true;
+    readonly unavailable: CompositionUnavailableMode;
+}
+interface UnavailableRefused {
+    readonly ok: false;
+    readonly problem: CompositionProblem;
+}
+export type UnavailableResult = UnavailableChosen | UnavailableRefused;
+/**
+ * How a planned field says "unavailable", per feature mode and AFTER `roleOf`
+ * (D393, D663 rulings S1 + S1b). The composer cannot take a device it does not
+ * own offline, and D393 forbids a stale number, so on an existing target a
+ * field that READS a source never gets `offline`.
+ */
+export declare function unavailableFor(tf: StateFieldDescription, role: CompositionFieldRole, mode: CompositionFeatureMode, cap: string, at: string): UnavailableResult;
+export {};

package/dist/composition/index.d.ts

@@ -3,7 +3,9 @@
  * inside @camstack/types import the deep modules, never this file.
  */
 export * from './composition.js';
+export * from './composition-events.js';
 export * from './composition-graph.js';
+export * from './composition-items.js';
 export * from './composition-report.js';
 export * from './evaluate-field.js';
 export * from './examples.js';

package/dist/composition/plan-result.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The result of planning part of a composition, and the two helpers every
+ * planner builds it with. Internal to the composition module — NOT in the
+ * barrel (`problem`/`refused` are too generic a name for `@camstack/types`).
+ */
+import type { CompositionFeaturePlan, CompositionFieldPlan, CompositionProblem, CompositionProblemCode } from './composition-report.js';
+import type { CompositionEventPlan } from './composition-events.js';
+export interface CompositionPlanResult {
+    readonly problems: readonly CompositionProblem[];
+    readonly fields: readonly CompositionFieldPlan[];
+    /** One entry per planned feature, with its mode; empty for a per-field or per-item result. */
+    readonly features: readonly CompositionFeaturePlan[];
+    readonly events: readonly CompositionEventPlan[];
+}
+export declare function problem(code: CompositionProblemCode, path: string, message: string): CompositionProblem;
+export declare function refused(...problems: readonly CompositionProblem[]): CompositionPlanResult;
+/** Where a planned field sits in the composition: `features[N].fields.<path>` or `features[N].items.<key>.fields.<path>`. */
+export declare function compositionFieldAt(field: CompositionFieldPlan): string;

package/dist/composition/state-fields.d.ts

@@ -17,3 +17,9 @@ export declare function describeStateField(schema: z.ZodType, path: string): Sta
 export declare function describeTopLevelStateFields(schema: z.ZodType): ReadonlyMap<string, StateFieldDescription>;
 /** Top-level keys a value MUST carry: those whose schema refuses `undefined`. */
 export declare function requiredTopLevelKeys(schema: z.ZodType): readonly string[];
+/**
+ * The proper prefixes of `path` whose schema accepts `undefined`: a required
+ * leaf under one of them is required only once something writes that parent
+ * (`remaining.unit` is required only when `remaining` is present).
+ */
+export declare function optionalAncestors(schema: z.ZodType, path: string): readonly string[];

package/dist/composition/validate-composition.d.ts

@@ -1,16 +1,19 @@
 /**
  * Save-time validation of a composition (D659): shape, capability fit, field
- * kinds, nullability, sources, cycles. Every refusal names its reason (D391),
+ * kinds, nullability, sources, cycles — and on an EXISTING target (D663),
+ * add vs replace per feature, self reads, one composition per device. Every refusal names its reason (D391),
  * and every variant a later slice implements is refused BY NAME with that slice.
  *
- * Pure: the caller DESCRIBES the sources (one read each) and passes the other
- * stored compositions. `planComposition` is the static half the composer
+ * Pure: the caller DESCRIBES the sources and an existing target (one read
+ * each) and passes the other stored compositions. `planComposition` is the static half the composer
  * re-runs at apply time, where the sources are the tracker's business.
  */
 import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
+import type { DeviceType } from '../device/device-type.js';
 import { type Composition, type CompositionSourceRef } from './composition.js';
+import { type CompositionPlanResult } from './plan-result.js';
 import { type CompositionPeer } from './composition-graph.js';
-import type { CompositionFieldPlan, CompositionProblem, CompositionValidation } from './composition-report.js';
+import { type CompositionValidation } from './composition-report.js';
 export type CapabilityLookup = (capName: string) => CapabilityDefinition | null;
 export declare function buildCapabilityLookup(defs: readonly CapabilityDefinition[]): CapabilityLookup;
 /** Caps every `BaseDevice` registers on itself; a second registration throws. */
@@ -28,19 +31,51 @@ export interface CompositionSourceUnreadable {
     readonly error: string;
 }
 export type CompositionSourceDescription = CompositionSourceFound | CompositionSourceAbsent | CompositionSourceUnreadable;
+/** An existing target device, read once: its type and each cap bound to it, with the addon serving it. */
+export interface CompositionTargetFound {
+    readonly kind: 'found';
+    readonly deviceId: number;
+    readonly type: DeviceType;
+    /** cap name → `nativeAddonId` (`getBindings`). A cap the composer grafted carries `COMPOSER_ADDON_ID`. */
+    readonly nativeCaps: ReadonlyMap<string, string>;
+}
+export type CompositionTargetDescription = CompositionTargetFound | CompositionSourceAbsent | CompositionSourceUnreadable;
 export interface ValidateCompositionContext {
     readonly lookupCap: CapabilityLookup;
     /** Keyed by `compositionSourceKey`. A ref with no entry was not read, and is refused as unreadable. */
     readonly sources: ReadonlyMap<string, CompositionSourceDescription>;
     /** The device this composition writes; null on create, when the block has no id yet. */
     readonly self: CompositionSourceRef | null;
+    /** The block being saved; null on create. Its stored old version is recognised by this id (D663). */
+    readonly blockId: string | null;
+    /** The EXISTING target device, read once; null for a new-device composition (a missing read is refused). */
+    readonly target: CompositionTargetDescription | null;
     /** Every OTHER stored composition; cycles run through them. */
     readonly peers: readonly CompositionPeer[];
+    /**
+     * Devices of stored customizations whose target could not be read, by
+     * `compositionSourceKey` → why. Their peers are OVER-approximated (nothing
+     * `replaced`, so every self-read is an edge — edges are only added, a cycle
+     * never hidden). A cyclic component holding a candidate node and such a
+     * device refuses NAMING the device ("possible cycle"); a component without a
+     * candidate node is never this save's cycle (`findCandidateCycles`).
+     */
+    readonly unreadTargets?: ReadonlyMap<string, string>;
 }
-export interface CompositionPlanResult {
-    readonly problems: readonly CompositionProblem[];
-    readonly fields: readonly CompositionFieldPlan[];
-}
-export declare function planComposition(composition: Composition, lookupCap: CapabilityLookup): CompositionPlanResult;
+export type { CompositionPlanResult } from './plan-result.js';
+/** The candidate's block id before its first save. Stored block ids are `randomUUID()`, so none can carry it. */
+export declare const PENDING_BLOCK_ID = "(unsaved)";
+/**
+ * The static plan. `target` describes an EXISTING target device (one read);
+ * it is ignored for a new one. On an existing target each feature REPLACES a
+ * cap the device has natively, else ADDS it (D663).
+ */
+export declare function planComposition(composition: Composition, lookupCap: CapabilityLookup, target?: CompositionTargetDescription): CompositionPlanResult;
 export declare function compositionSourceRefs(composition: Composition): readonly CompositionSourceRef[];
+/**
+ * `compositionFieldKey` of every field a REPLACE feature of `plan` owns — the
+ * candidate's own, and a stored peer's `CompositionPeer.replaced` (D663): one
+ * derivation, so the graph reads both the same way.
+ */
+export declare function replacedFieldKeys(plan: CompositionPlanResult): ReadonlySet<string>;
 export declare function validateComposition(composition: Composition, ctx: ValidateCompositionContext): CompositionValidation;