@adobe/data 0.9.36 → 0.9.39

package/AGENTS.md

@@ -0,0 +1,91 @@
+# @adobe/data — Agent guide
+
+Adobe data-oriented programming library. Use this file when editing code in this package or when consuming `@adobe/data` in an application.
+
+## Stack
+
+- **Package manager:** pnpm
+- **Build:** TypeScript (`tsc -b`), AssemblyScript for WASM
+- **Test:** Vitest (browser tests use Playwright)
+- **Lint:** ESLint
+
+## Commands (from package root `packages/data`)
+
+| Task | Command |
+|------|---------|
+| Build | `pnpm build` |
+| Test (headless, exit when done) | `pnpm test [filename] -- --run` |
+| Test (watch) | `pnpm dev:test` |
+| Lint | `pnpm lint` |
+| Lint fix | `pnpm lint-fix` |
+
+Run tests for a single file: `pnpm test create-storage-persistence-service.test.ts -- --run`
+
+## Paradigm and code style
+
+- **Data-oriented, functional.** Prefer composition over inheritance. No classes, enums, or inheritance.
+- **Immutable data** by default; mutation allowed only where needed for performance (e.g. ECS internals).
+- **TypeScript:** modern TS, semicolons, `const`/`let`, `??` for nullish coalescing (not `||`).
+- **Separation of concerns:** pure functions and clear module boundaries.
+
+## Package layout and imports
+
+Consumers use **subpath exports**. Do not rely on deep paths; use the public entry points:
+
+| Import | Purpose |
+|--------|---------|
+| `@adobe/data` | Core: Data, equals, normalize, mutableClone |
+| `@adobe/data/observe` | Observables (fromConstant, fromPromise, withMap, withFilter, etc.) |
+| `@adobe/data/ecs` | ECS: Store, Database, Plugin, createStore, createDatabase |
+| `@adobe/data/cache` | Cache, memoize, hashing, BlobStore |
+| `@adobe/data/schema` | JSON Schema helpers, validation |
+| `@adobe/data/service` | AsyncDataService, service patterns |
+| `@adobe/data/blob` | Blob / BlobRef |
+| `@adobe/data/table` | Table utilities |
+| `@adobe/data/math` | Vec2, Vec3, Vec4, Mat4, etc. |
+| `@adobe/data/types` | Shared types |
+| `@adobe/data/functions` | Serialization and pure helpers |
+
+Source lives under `src/` with one main `index.ts` per area; built output is in `dist/`.
+
+## ECS (Entity Component System)
+
+- **Store:** low-level, synchronous, direct mutations. No transactions, no observability.
+- **Database:** wraps a Store; **transaction-based** and **observable**. All mutations go through transaction functions; undo/redo and observers are supported.
+- **Plugins:** use `Database.Plugin.create()`. Property order is **enforced at runtime:** `extends` → `services` → `components` → `resources` → `archetypes` → `computed` → `transactions` → `actions` → `systems`. Wrong order throws.
+- **Composition:** one plugin via `extends`; multiple peers via `Database.Plugin.combine(...)`.
+- **Transactions:** synchronous and deterministic. Receive `(store, payload)`. Mutate via `store.update(entity, data)`, `store.resources.x = value`, etc.
+- **Actions:** may be async; call at most one transaction per action to keep undo/redo correct. Callers should not rely on return values for UI flow (data down via Observe, actions for side effects).
+
+## Observables
+
+- `Observable<T>` = subscription function `(callback: (value: T) => void) => Unobserve`.
+- May call back synchronously (once) and/or asynchronously. Use `fromConstant`, `fromPromise`, `fromObservableProperties`; modify with `withMap`, `withFilter`, `withDefault`, `withOptional`, `withDeduplicate`.
+
+## Testing
+
+- Unit tests live **next to** the code: `<my-file>.test.ts` next to `my-file.ts`.
+- Use Vitest: `describe` for the unit under test, `test`/`it` for the case. Prefer `assert({ given, should, actual, expected })`-style where the project uses it.
+- Before changing behavior: confirm whether the test or the implementation is wrong and state which one you are fixing.
+- Focus on behavior and edge cases; avoid testing types/shapes that TypeScript already enforces.
+
+## Data and schemas
+
+- **Data:** immutable, JSON-serializable values. Use `normalize()` for stable keys (e.g. cache keys).
+- **Schemas:** JSON Schema with `as const` so `FromSchema` (or equivalent) can derive TypeScript types. Use schema namespaces for component/resource definitions in ECS.
+
+## Gotchas
+
+- **Breaking changes:** Before 1.0.0, minor version bumps may include breaking API changes.
+- **ECS plugin order:** Reordering plugin properties (e.g. putting `transactions` before `components`) will throw at runtime.
+- **BlobStore / BlobRef:** Prefer BlobRef for persistence and cache keys; resolve to Blob when needed.
+
+## References
+
+Source for peer packages and sample apps is included under `references/` (when present). Use these as living reference code:
+
+- **references/data-lit** — Extra support for Lit-based projects.
+- **references/data-react** — Same but for React.
+- **references/data-lit-todo** — Sample with best practices for Lit apps.
+- **references/data-react-hello** — Minimal starting React sample.
+- **references/data-react-pixie** — Sample of using React Pixie for 2D rendering.

package/dist/ecs/database/observe-select-deep.d.ts

@@ -0,0 +1,23 @@
+import { Observe } from "../../observe/index.js";
+import { StringKeyof } from "../../types/types.js";
+import { RequiredComponents } from "../required-components.js";
+import { Components } from "../store/components.js";
+import { EntitySelectOptions } from "../store/entity-select-options.js";
+import { Database } from "./database.js";
+/**
+ * Entity data shape returned by observeSelectDeep.
+ * Includes required components (id) and each queried component with its correct type.
+ */
+export type SelectDeepEntityData<C, Include extends StringKeyof<C>> = RequiredComponents & {
+    readonly [K in Include]: C[K];
+};
+/**
+ * Deeply observe entity data for an archetype query.
+ *
+ * Unlike `db.observe.select` (which returns entity IDs and only triggers on
+ * set membership changes), `observeSelectDeep` returns full typed entity data
+ * and re-emits whenever ANY included component value changes on any matched entity.
+ *
+ * This IS NOT an efficient pattern, so use sparingly and with small number of entities.
+ */
+export declare const observeSelectDeep: <C extends Components, Include extends StringKeyof<C>>(db: Database<C, any, any, any, any, any, any, any>, include: readonly Include[], options?: EntitySelectOptions<C, Pick<C & RequiredComponents, Include>>) => Observe<readonly SelectDeepEntityData<C, Include>[]>;

package/dist/ecs/database/observe-select-deep.js

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Deeply observe entity data for an archetype query.
+ *
+ * Unlike `db.observe.select` (which returns entity IDs and only triggers on
+ * set membership changes), `observeSelectDeep` returns full typed entity data
+ * and re-emits whenever ANY included component value changes on any matched entity.
+ *
+ * This IS NOT an efficient pattern, so use sparingly and with small number of entities.
+ */
+export const observeSelectDeep = (db, include, options) => {
+    // TODO: implementation — returns a stub for now so the type signature compiles.
+    return (_notify) => () => { };
+};
+//# sourceMappingURL=observe-select-deep.js.map

package/dist/ecs/database/observe-select-deep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-select-deep.js","sourceRoot":"","sources":["../../../src/ecs/database/observe-select-deep.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAkBvD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAI/B,EAAkD,EAClD,OAA2B,EAC3B,OAAuE,EACjB,EAAE;IACxD,gFAAgF;IAChF,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAChC,CAAC,CAAC"}

package/dist/ecs/database/observe-select-deep.type-test.js

@@ -0,0 +1,111 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Database } from "./database.js";
+import { observeSelectDeep } from "./observe-select-deep.js";
+/**
+ * Type-only tests for observeSelectDeep type inference.
+ *
+ * These tests verify that:
+ * 1. observeSelectDeep infers entity data types from included components
+ * 2. Only queried components appear in the result type
+ * 3. RequiredComponents (id) is always included
+ * 4. The helper type SelectDeepEntityData resolves correctly
+ *
+ * Note: These are compile-time type checks only — they don't need to execute.
+ */
+// ============================================================================
+// SelectDeepEntityData HELPER TYPE
+// ============================================================================
+function testSelectDeepEntityDataType() {
+}
+// ============================================================================
+// BASIC INFERENCE FROM DATABASE
+// ============================================================================
+function testObserveSelectDeepBasicInference() {
+    const plugin = Database.Plugin.create({
+        components: {
+            position: { type: "number" },
+            velocity: { type: "number" },
+            name: { type: "string" },
+        },
+        archetypes: {
+            Moving: ["position", "velocity"],
+        },
+    });
+    const db = Database.create(plugin);
+    // Querying position and velocity should infer correct entity data
+    const observed = observeSelectDeep(db, ["position", "velocity"]);
+}
+// ============================================================================
+// SINGLE COMPONENT QUERY
+// ============================================================================
+function testObserveSelectDeepSingleComponent() {
+    const plugin = Database.Plugin.create({
+        components: {
+            position: { type: "number" },
+            name: { type: "string" },
+        },
+    });
+    const db = Database.create(plugin);
+    // Querying only name should produce id + name
+    const observed = observeSelectDeep(db, ["name"]);
+}
+// ============================================================================
+// INVALID COMPONENT NAMES REJECTED
+// ============================================================================
+function testObserveSelectDeepRejectsInvalidComponents() {
+    const plugin = Database.Plugin.create({
+        components: {
+            position: { type: "number" },
+        },
+    });
+    const db = Database.create(plugin);
+    // @ts-expect-error - "nonexistent" is not a valid component name
+    observeSelectDeep(db, ["nonexistent"]);
+}
+// ============================================================================
+// WITH OPTIONS (where/order)
+// ============================================================================
+function testObserveSelectDeepWithOptions() {
+    const plugin = Database.Plugin.create({
+        components: {
+            position: { type: "number" },
+            velocity: { type: "number" },
+            name: { type: "string" },
+        },
+        archetypes: {
+            Moving: ["position", "velocity"],
+        },
+    });
+    const db = Database.create(plugin);
+    // Should accept where/order options scoped to included components
+    const observed = observeSelectDeep(db, ["position", "velocity"], {
+        where: { position: { ">": 0 } },
+        order: { velocity: true },
+    });
+}
+// ============================================================================
+// EXTENDED PLUGIN INFERENCE
+// ============================================================================
+function testObserveSelectDeepWithExtendedPlugin() {
+    const basePlugin = Database.Plugin.create({
+        components: {
+            position: { type: "number" },
+        },
+        archetypes: {
+            Positioned: ["position"],
+        },
+    });
+    const extendedPlugin = Database.Plugin.create({
+        extends: basePlugin,
+        components: {
+            velocity: { type: "number" },
+        },
+        archetypes: {
+            Moving: ["position", "velocity"],
+        },
+    });
+    const db = Database.create(extendedPlugin);
+    // Should work with components from both base and extended plugins
+    const observed = observeSelectDeep(db, ["position", "velocity"]);
+}
+//# sourceMappingURL=observe-select-deep.type-test.js.map

package/dist/ecs/database/observe-select-deep.type-test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-select-deep.type-test.js","sourceRoot":"","sources":["../../../src/ecs/database/observe-select-deep.type-test.ts"],"names":[],"mappings":"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"}

package/dist/ecs/persistence-service/create-storage-persistence-service.js

@@ -1,5 +1,6 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import { deserializeFromStorage, serializeToStorage } from "../../functions/serialization/serialize-to-storage.js";
+import { debounce } from "../../internal/function/debounce.js";
 export const createStoragePersistenceService = async (options) => {
     const { database, defaultFileId, autoSaveOnChange: autoSave, autoLoadOnStart, storage = sessionStorage } = options;
     const service = {
@@ -18,10 +19,10 @@ export const createStoragePersistenceService = async (options) => {
         await service.load();
     }
     if (autoSave) {
+        const debouncedSave = debounce(() => service.save(), 300);
         database.observe.transactions(t => {
-            if (!t.transient) {
-                service.save();
-            }
+            if (!t.transient)
+                debouncedSave();
         });
     }
     return service;

package/dist/ecs/persistence-service/create-storage-persistence-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-storage-persistence-service.js","sourceRoot":"","sources":["../../../src/ecs/persistence-service/create-storage-persistence-service.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,uDAAuD,CAAC;AAInH,MAAM,CAAC,MAAM,+BAA+B,GAAG,KAAK,EAAE,OAMrD,EAA+B,EAAE;IAC9B,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,GAAG,cAAc,EAAE,GAAG,OAAO,CAAC;IACnH,MAAM,OAAO,GAAuB;QAChC,WAAW,EAAE,2BAA2B;QACxC,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,EAAE;YACnC,MAAM,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,EAAE;YACnC,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC3D,IAAI,IAAI,EAAE,CAAC;gBACP,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACL,CAAC;KACJ,CAAA;IACD,IAAI,eAAe,EAAE,CAAC;QAClB,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACX,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;YAC9B,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,EAAE,CAAC;YACnB,CAAC;QACL,CAAC,CAAC,CAAA;IACN,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC"}
+{"version":3,"file":"create-storage-persistence-service.js","sourceRoot":"","sources":["../../../src/ecs/persistence-service/create-storage-persistence-service.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,uDAAuD,CAAC;AACnH,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAI/D,MAAM,CAAC,MAAM,+BAA+B,GAAG,KAAK,EAAE,OAMrD,EAA+B,EAAE;IAC9B,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,GAAG,cAAc,EAAE,GAAG,OAAO,CAAC;IACnH,MAAM,OAAO,GAAuB;QAChC,WAAW,EAAE,2BAA2B;QACxC,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,EAAE;YACnC,MAAM,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,EAAE;YACnC,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC3D,IAAI,IAAI,EAAE,CAAC;gBACP,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACL,CAAC;KACJ,CAAA;IACD,IAAI,eAAe,EAAE,CAAC;QAClB,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACX,MAAM,aAAa,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;QAC1D,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;YAC9B,IAAI,CAAC,CAAC,CAAC,SAAS;gBAAE,aAAa,EAAE,CAAC;QACtC,CAAC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC"}

package/dist/ecs/persistence-service/create-storage-persistence-service.test.js

@@ -0,0 +1,52 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createStoragePersistenceService } from "./create-storage-persistence-service.js";
+import { Database } from "../index.js";
+function createMinimalDatabase() {
+    return Database.create(Database.Plugin.create({
+        components: {
+            n: { type: "number" },
+        },
+        archetypes: { N: ["n"] },
+        transactions: {
+            tick(t, _args) {
+                t.archetypes.N.insert({ n: 0 });
+            },
+        },
+    }));
+}
+describe("createStoragePersistenceService", () => {
+    describe("autoSaveOnChange with rapid transactions", () => {
+        beforeEach(() => {
+            vi.useFakeTimers();
+        });
+        afterEach(() => {
+            vi.useRealTimers();
+        });
+        it("given rapid non-transient transactions, invokes save once after debounce window (debounced)", async () => {
+            let saveInvokeCount = 0;
+            const database = createMinimalDatabase();
+            const service = await createStoragePersistenceService({
+                database,
+                defaultFileId: "test-id",
+                autoSaveOnChange: true,
+                autoLoadOnStart: false,
+            });
+            const originalSave = service.save;
+            Object.assign(service, {
+                save: async (fileId) => {
+                    saveInvokeCount++;
+                    return originalSave.call(service, fileId);
+                },
+            });
+            const transactionCount = 5;
+            for (let i = 0; i < transactionCount; i++) {
+                database.transactions.tick({});
+            }
+            vi.advanceTimersByTime(350);
+            await vi.runAllTimersAsync();
+            expect(saveInvokeCount).toBe(1);
+        });
+    });
+});
+//# sourceMappingURL=create-storage-persistence-service.test.js.map

package/dist/ecs/persistence-service/create-storage-persistence-service.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-storage-persistence-service.test.js","sourceRoot":"","sources":["../../../src/ecs/persistence-service/create-storage-persistence-service.test.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,+BAA+B,EAAE,MAAM,yCAAyC,CAAC;AAC1F,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,SAAS,qBAAqB;IAC1B,OAAO,QAAQ,CAAC,MAAM,CAClB,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;QACnB,UAAU,EAAE;YACR,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SACxB;QACD,UAAU,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE;QACxB,YAAY,EAAE;YACV,IAAI,CAAC,CAAC,EAAE,KAA4B;gBAChC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACpC,CAAC;SACJ;KACJ,CAAC,CACL,CAAC;AACN,CAAC;AAED,QAAQ,CAAC,iCAAiC,EAAE,GAAG,EAAE;IAC7C,QAAQ,CAAC,0CAA0C,EAAE,GAAG,EAAE;QACtD,UAAU,CAAC,GAAG,EAAE;YACZ,EAAE,CAAC,aAAa,EAAE,CAAC;QACvB,CAAC,CAAC,CAAC;QAEH,SAAS,CAAC,GAAG,EAAE;YACX,EAAE,CAAC,aAAa,EAAE,CAAC;QACvB,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6FAA6F,EAAE,KAAK,IAAI,EAAE;YACzG,IAAI,eAAe,GAAG,CAAC,CAAC;YACxB,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,MAAM,+BAA+B,CAAC;gBAClD,QAAQ;gBACR,aAAa,EAAE,SAAS;gBACxB,gBAAgB,EAAE,IAAI;gBACtB,eAAe,EAAE,KAAK;aACzB,CAAC,CAAC;YACH,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YAClC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE;gBACnB,IAAI,EAAE,KAAK,EAAE,MAAe,EAAE,EAAE;oBAC5B,eAAe,EAAE,CAAC;oBAClB,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC9C,CAAC;aACJ,CAAC,CAAC;YAEH,MAAM,gBAAgB,GAAG,CAAC,CAAC;YAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC;gBACxC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnC,CAAC;YAED,EAAE,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;YAC5B,MAAM,EAAE,CAAC,iBAAiB,EAAE,CAAC;YAE7B,MAAM,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/dist/service/agentic-service/link.d.ts

@@ -0,0 +1,15 @@
+import type { AgenticService } from "./agentic-service.js";
+/**
+ * A link to another agentic service. Used to expose related services (e.g. parent,
+ * children, sibling workflows) so the UI can navigate or delegate to them.
+ * Either `service` (in-process) or `serviceId` (resolved by host) must be set.
+ */
+export type Link = {
+    service: AgenticService;
+    label?: string;
+    description?: string;
+} | {
+    serviceId: string;
+    label?: string;
+    description?: string;
+};

package/dist/service/agentic-service/link.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=link.js.map

package/dist/service/agentic-service/link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.js","sourceRoot":"","sources":["../../../src/service/agentic-service/link.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/service/async-data-service/is-valid.d.ts

@@ -3,7 +3,9 @@ import { Observe } from "../../observe/index.js";
 import { Service } from "../service.js";
 type ValidReturnType<R> = R extends Observe<infer T> ? T extends Data ? true : false : R extends void ? true : R extends Promise<infer P> ? P extends Data | void ? true : false : R extends AsyncGenerator<infer G, any, any> ? G extends Data ? true : false : false;
 type AllArgsAreData<Args extends readonly any[]> = Args extends readonly [] ? true : Args extends readonly [infer First, ...infer Rest] ? First extends Data ? AllArgsAreData<Rest> : false : Args extends readonly (infer Element)[] ? Element extends Data ? true : false : false;
-type IsValidProperty<P> = P extends Observe<infer T> ? T extends Data ? true : false : P extends (...args: infer Args) => infer R ? AllArgsAreData<Args> extends true ? ValidReturnType<R> : false : false;
+type IsValidProperty<P> = P extends Observe<infer T> ? T extends Data ? true : false : P extends (...args: infer Args) => infer R ? AllArgsAreData<Args> extends true ? ValidReturnType<R> : false : P extends object ? keyof P extends never ? false : {
+    [K in keyof P]: IsValidProperty<P[K]>;
+} extends Record<keyof P, true> ? true : false : false;
 type AllPropertiesValid<T extends Service> = {
     [K in Exclude<keyof T, keyof Service>]: IsValidProperty<T[K]>;
 } extends Record<Exclude<keyof T, keyof Service>, true> ? true : false;

package/dist/service/async-data-service/is-valid.type-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/service/async-data-service/is-valid.type-test.js

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export {};
+//# sourceMappingURL=is-valid.type-test.js.map

package/dist/service/async-data-service/is-valid.type-test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-valid.type-test.js","sourceRoot":"","sources":["../../../src/service/async-data-service/is-valid.type-test.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/service/dynamic-service/semantic-service.d.ts

@@ -0,0 +1,19 @@
+import { Observe } from "../../observe/index.js";
+import { Schema } from "../../schema/index.js";
+import { Service } from "../service.js";
+export type SemanticState<S extends Schema = Schema> = {
+    schema: S;
+    value: Schema.ToType<S>;
+};
+export type SemanticAction<S extends Schema | false = Schema> = {
+    schema: S;
+    execute: Schema.ToType<S> extends void ? (() => void) : ((state: Schema.ToType<S>) => void);
+};
+export interface SemanticService extends Service {
+    states: Observe<{
+        [key: string]: SemanticState;
+    }>;
+    actions: Observe<{
+        [key: string]: SemanticAction;
+    }>;
+}

package/dist/service/dynamic-service/semantic-service.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=semantic-service.js.map

package/dist/service/dynamic-service/semantic-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-service.js","sourceRoot":"","sources":["../../../src/service/dynamic-service/semantic-service.ts"],"names":[],"mappings":""}

package/dist/service/semantic-service/semantic-service.d.ts

@@ -0,0 +1,19 @@
+import { Observe } from "../../observe/index.js";
+import { Schema } from "../../schema/index.js";
+import { Service } from "../service.js";
+export type SemanticState<S extends Schema = Schema> = {
+    schema: S;
+    value: Schema.ToType<S>;
+};
+export type SemanticAction<S extends Schema | false = Schema> = {
+    schema: S;
+    execute: Schema.ToType<S> extends void ? (() => void) : ((state: Schema.ToType<S>) => void);
+};
+export interface SemanticService extends Service {
+    states: Observe<{
+        [key: string]: SemanticState;
+    }>;
+    actions: Observe<{
+        [key: string]: SemanticAction;
+    }>;
+}

package/dist/service/semantic-service/semantic-service.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=semantic-service.js.map

package/dist/service/semantic-service/semantic-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-service.js","sourceRoot":"","sources":["../../../src/service/semantic-service/semantic-service.ts"],"names":[],"mappings":""}