@ankhorage/contracts 25.1.0 → 26.0.0

package/src/bindings.ts

@@ -1,123 +1,76 @@
+import type { Capability } from './capability';
 import type { EntityRegistry, ValueMap } from './collections';
-import type { ApiId, EndpointId, OperationId } from './data';
 import type { SerializableValue } from './serializable';
 
 export type ComponentInstanceId = string;
 export type ComponentTypeId = string;
-
 export type BindingValue = SerializableValue;
-
 export type BindingDataPath = string;
-
 export type BindingValueTransform = 'lowercase' | 'trim' | 'uppercase';
 
-export interface BindingOperationRef {
-  readonly apiId: ApiId;
-  readonly operationId: OperationId;
-  readonly endpointId?: EndpointId;
+/** A portable reference to a readable capability value or a cached invocation result. */
+export interface BindingCapabilityReference {
+  readonly capability: Capability['id'];
+  readonly path?: BindingDataPath;
+  readonly result?: string;
 }
 
-export type BindingValueSource =
-  | {
-      readonly kind: 'context';
-      readonly path: BindingDataPath;
-    }
-  | {
-      readonly kind: 'event';
-      readonly path: BindingDataPath;
-    }
-  | {
-      readonly kind: 'literal';
-      readonly value: BindingValue;
-    }
+/** A portable request to invoke a capability and optionally retain its result in a local slot. */
+export interface BindingInvocation {
+  readonly capability: Capability['id'];
+  readonly input?: BindingInputMap;
+  readonly result?: string;
+}
+
+/** A recursive, serializable value expression used by bindings and invocation inputs. */
+export type BindingExpression =
+  | BindingCapabilityReference
+  | { readonly kind: 'array'; readonly items: readonly BindingExpression[] }
   | {
-      readonly kind: 'operation';
-      readonly operation: BindingOperationRef;
-      readonly path?: BindingDataPath;
+      readonly kind: 'fallback';
+      readonly value: BindingExpression;
+      readonly fallback: BindingExpression;
     }
+  | { readonly kind: 'literal'; readonly value: BindingValue }
+  | { readonly kind: 'object'; readonly fields: ValueMap<string, BindingExpression> }
   | {
-      readonly kind: 'state';
-      readonly path: BindingDataPath;
+      readonly kind: 'transform';
+      readonly value: BindingExpression;
+      readonly transforms: readonly BindingValueTransform[];
     };
 
-export interface BindingValueExpression {
-  readonly source: BindingValueSource;
-  readonly transforms?: readonly BindingValueTransform[];
-}
+export type BindingInputValue = BindingExpression;
+export type BindingInputMap = ValueMap<string, BindingInputValue>;
+export type BindingConditionOperator = 'eq' | 'exists' | 'neq' | 'notExists';
 
-export interface BindingFallback {
-  readonly value?: BindingValue;
-  readonly source?: BindingValueSource;
+/** A condition evaluated from portable binding expressions. */
+export interface BindingCondition {
+  readonly source: BindingExpression;
+  readonly operator: BindingConditionOperator;
+  readonly value?: BindingExpression;
 }
 
-export type BindingLifecycleState = 'empty' | 'error' | 'loading';
-
+/** A lifecycle-specific expression rendered when a bound value reaches one state. */
 export interface BindingLifecycleBehavior {
   readonly state: BindingLifecycleState;
-  readonly fallback?: BindingFallback;
+  readonly value?: BindingExpression;
   readonly message?: string;
 }
 
+export type BindingLifecycleState = 'empty' | 'error' | 'loading';
+
 export interface PropBinding {
-  readonly source: BindingValueSource;
-  readonly fallback?: BindingFallback;
+  readonly value: BindingExpression;
   readonly loading?: BindingLifecycleBehavior;
   readonly error?: BindingLifecycleBehavior;
   readonly empty?: BindingLifecycleBehavior;
-  readonly transforms?: readonly BindingValueTransform[];
 }
 
-export type BindingInputValue =
-  | {
-      readonly kind: 'array';
-      readonly items: readonly BindingInputValue[];
-    }
-  | {
-      readonly kind: 'literal';
-      readonly value: BindingValue;
-    }
-  | {
-      readonly kind: 'object';
-      readonly fields: ValueMap<string, BindingInputValue>;
-    }
-  | {
-      readonly kind: 'source';
-      readonly source: BindingValueSource;
-      readonly transforms?: readonly BindingValueTransform[];
-    };
-
-export type BindingInputMap = ValueMap<string, BindingInputValue>;
-
-export interface OperationScreenDataLoaderDefinition {
-  readonly kind: 'operation';
-  readonly id?: string;
-  readonly operation: BindingOperationRef;
-  readonly input?: BindingInputMap;
-}
-
-export type ScreenDataLoaderDefinition = OperationScreenDataLoaderDefinition;
-
-export type BindingConditionOperator = 'eq' | 'exists' | 'neq' | 'notExists';
-
-export interface BindingCondition {
-  readonly source: BindingValueSource;
-  readonly operator: BindingConditionOperator;
-  readonly value?: BindingValue;
-}
-
-export type EventBindingTarget =
-  | {
-      readonly kind: 'action';
-      readonly type: string;
-    }
-  | {
-      readonly kind: 'operation';
-      readonly operation: BindingOperationRef;
-    };
+/** A screen loader is one capability invocation, optionally storing its result by slot name. */
+export type ScreenDataLoaderDefinition = BindingInvocation;
 
 export interface EventBinding {
-  readonly target: EventBindingTarget;
-  readonly input?: BindingInputMap;
+  readonly target: BindingInvocation;
   readonly when?: BindingCondition;
 }
 

package/src/contracts.test.ts

@@ -219,7 +219,7 @@ describe('contracts', () => {
     expect(theme.recipes?.patterns?.Panel?.padding).toBe('xl');
   });
 
-  it('accepts screens with operation data loaders and repeat empty-state nodes', () => {
+  it('accepts screens with capability loaders and repeat empty-state nodes', () => {
     const manifest: Pick<AppManifest, 'screens'> = {
       screens: {
         products: {
@@ -230,12 +230,8 @@ describe('contracts', () => {
             type: 'Grid',
             repeat: {
               source: {
-                kind: 'operation',
-                operation: {
-                  dataSourceId: 'nutrition-api',
-                  endpointId: 'products',
-                  operationId: 'nutrition.products.list',
-                },
+                capability: 'api.nutrition.productsList',
+                result: 'products',
                 path: 'products',
               },
               empty: [
@@ -252,20 +248,12 @@ describe('contracts', () => {
           },
           dataLoaders: [
             {
-              kind: 'operation',
-              id: 'product-detail',
-              operation: {
-                dataSourceId: 'nutrition-api',
-                endpointId: 'products',
-                operationId: 'nutrition.products.getById',
-              },
+              capability: 'api.nutrition.productsGetById',
+              result: 'product',
               input: {
                 id: {
-                  kind: 'source',
-                  source: {
-                    kind: 'context',
-                    path: 'route.params.id',
-                  },
+                  capability: 'context.route',
+                  path: 'params.id',
                 },
               },
             },
@@ -275,7 +263,9 @@ describe('contracts', () => {
     };
 
     expect(JSON.parse(JSON.stringify(manifest))).toEqual(manifest);
-    expect(manifest.screens.products?.dataLoaders?.[0]?.kind).toBe('operation');
+    expect(manifest.screens.products?.dataLoaders?.[0]?.capability).toBe(
+      'api.nutrition.productsGetById',
+    );
     expect(manifest.screens.products?.root.repeat?.empty?.[0]?.type).toBe('Notice');
   });
 

package/src/storage-schemas.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'bun:test';
+
+import { isDataSchema } from './data';
+import {
+  STORAGE_ADAPTER_ERROR_SCHEMA,
+  STORAGE_ASSET_REFERENCE_SCHEMA,
+  STORAGE_BYTES_SCHEMA,
+  STORAGE_ERROR_RESULT_SCHEMA,
+  STORAGE_IDENTITY_SCHEMA,
+  STORAGE_LIST_INPUT_SCHEMA,
+  STORAGE_LIST_OPERATION_RESULT_SCHEMA,
+  STORAGE_LIST_RESULT_SCHEMA,
+  STORAGE_OBJECT_METADATA_SCHEMA,
+  STORAGE_PUBLIC_URL_INPUT_SCHEMA,
+  STORAGE_PUBLIC_URL_OPERATION_RESULT_SCHEMA,
+  STORAGE_PUBLIC_URL_RESULT_SCHEMA,
+  STORAGE_REMOVE_INPUT_SCHEMA,
+  STORAGE_RESOLVE_INPUT_SCHEMA,
+  STORAGE_RESOLVE_OPERATION_RESULT_SCHEMA,
+  STORAGE_RESOLVE_RESULT_SCHEMA,
+  STORAGE_RESOLVED_ASSET_SCHEMA,
+  STORAGE_SUCCESS_SCHEMA,
+  STORAGE_UPLOAD_INPUT_SCHEMA,
+  STORAGE_UPLOAD_OPERATION_RESULT_SCHEMA,
+  STORAGE_UPLOAD_RESULT_SCHEMA,
+  STORAGE_VOID_RESULT_SCHEMA,
+} from './storage';
+
+const STORAGE_SCHEMAS = [
+  STORAGE_BYTES_SCHEMA,
+  STORAGE_IDENTITY_SCHEMA,
+  STORAGE_ASSET_REFERENCE_SCHEMA,
+  STORAGE_OBJECT_METADATA_SCHEMA,
+  STORAGE_UPLOAD_INPUT_SCHEMA,
+  STORAGE_UPLOAD_RESULT_SCHEMA,
+  STORAGE_REMOVE_INPUT_SCHEMA,
+  STORAGE_PUBLIC_URL_INPUT_SCHEMA,
+  STORAGE_PUBLIC_URL_RESULT_SCHEMA,
+  STORAGE_LIST_INPUT_SCHEMA,
+  STORAGE_LIST_RESULT_SCHEMA,
+  STORAGE_RESOLVE_INPUT_SCHEMA,
+  STORAGE_RESOLVED_ASSET_SCHEMA,
+  STORAGE_RESOLVE_RESULT_SCHEMA,
+  STORAGE_ADAPTER_ERROR_SCHEMA,
+  STORAGE_SUCCESS_SCHEMA,
+  STORAGE_ERROR_RESULT_SCHEMA,
+  STORAGE_VOID_RESULT_SCHEMA,
+  STORAGE_UPLOAD_OPERATION_RESULT_SCHEMA,
+  STORAGE_PUBLIC_URL_OPERATION_RESULT_SCHEMA,
+  STORAGE_LIST_OPERATION_RESULT_SCHEMA,
+  STORAGE_RESOLVE_OPERATION_RESULT_SCHEMA,
+] as const;
+
+describe('storage capability schemas', () => {
+  it('publishes valid, serializable schema sources for every storage operation and value', () => {
+    expect(STORAGE_SCHEMAS.every(isDataSchema)).toBe(true);
+    expect(JSON.parse(JSON.stringify(STORAGE_SCHEMAS))).toEqual(STORAGE_SCHEMAS);
+  });
+
+  it('serializes upload bytes as standard Base64 without changing the adapter input contract', () => {
+    expect(STORAGE_UPLOAD_INPUT_SCHEMA.required).toEqual(['bucket', 'path', 'body']);
+    expect(STORAGE_UPLOAD_INPUT_SCHEMA.properties.body).toEqual({
+      type: 'string',
+      format: 'base64',
+    });
+  });
+
+  it('keeps public and signed resolution under the existing access selection', () => {
+    expect(STORAGE_RESOLVE_INPUT_SCHEMA.properties.access).toEqual({
+      type: 'string',
+      enum: ['public', 'signed'],
+    });
+    expect(STORAGE_RESOLVED_ASSET_SCHEMA.properties.access).toEqual({
+      type: 'string',
+      enum: ['public', 'signed'],
+    });
+  });
+
+  it('requires result data for non-void operations and keeps errors portable', () => {
+    expect(STORAGE_UPLOAD_OPERATION_RESULT_SCHEMA.oneOf[0].required).toEqual(['ok', 'data']);
+    expect(STORAGE_PUBLIC_URL_OPERATION_RESULT_SCHEMA.oneOf[0].required).toEqual(['ok', 'data']);
+    expect(STORAGE_LIST_OPERATION_RESULT_SCHEMA.oneOf[0].required).toEqual(['ok', 'data']);
+    expect(STORAGE_RESOLVE_OPERATION_RESULT_SCHEMA.oneOf[0].required).toEqual(['ok', 'data']);
+    expect(STORAGE_ADAPTER_ERROR_SCHEMA.properties).not.toHaveProperty('cause');
+  });
+});

package/src/storage.ts

@@ -1,3 +1,5 @@
+import type { DataSchema } from './data/schemas.js';
+
 export interface StorageAdapterError {
   code: string;
   message: string;
@@ -154,3 +156,198 @@ export interface StorageResolveAdapter {
  */
 export interface MediaStorageAdapter
   extends StorageAdapter, StorageListAdapter, StorageResolveAdapter {}
+
+/**
+ * Portable schema sources for provider-neutral storage values and operations.
+ *
+ * Upload bytes use a standard Base64 string. The source `StorageUploadInput` remains a
+ * `Uint8Array` at the adapter boundary; catalogs serialize its `body` with this schema and
+ * reconstruct the bytes before invoking an adapter.
+ */
+export const STORAGE_BYTES_SCHEMA = {
+  type: 'string',
+  format: 'base64',
+} as const satisfies DataSchema;
+
+export const STORAGE_IDENTITY_SCHEMA = {
+  type: 'object',
+  required: ['bucket', 'path'],
+  properties: {
+    storageId: { type: 'string' },
+    bucket: { type: 'string' },
+    path: { type: 'string' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_ASSET_REFERENCE_SCHEMA = {
+  ...STORAGE_IDENTITY_SCHEMA,
+  properties: {
+    ...STORAGE_IDENTITY_SCHEMA.properties,
+    publicUrl: { type: 'string' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_OBJECT_METADATA_SCHEMA = {
+  ...STORAGE_IDENTITY_SCHEMA,
+  properties: {
+    ...STORAGE_IDENTITY_SCHEMA.properties,
+    contentType: { type: 'string' },
+    sizeBytes: { type: 'integer' },
+    createdAt: { type: 'string' },
+    updatedAt: { type: 'string' },
+    etag: { type: 'string' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_UPLOAD_INPUT_SCHEMA = {
+  ...STORAGE_IDENTITY_SCHEMA,
+  required: ['bucket', 'path', 'body'],
+  properties: {
+    ...STORAGE_IDENTITY_SCHEMA.properties,
+    body: STORAGE_BYTES_SCHEMA,
+    contentType: { type: 'string' },
+    cacheControl: { type: 'string' },
+    upsert: { type: 'boolean' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_UPLOAD_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['asset'],
+  properties: { asset: STORAGE_ASSET_REFERENCE_SCHEMA },
+} as const satisfies DataSchema;
+
+export const STORAGE_REMOVE_INPUT_SCHEMA = {
+  ...STORAGE_IDENTITY_SCHEMA,
+  description: 'Identifies the stored object to remove.',
+} as const satisfies DataSchema;
+
+export const STORAGE_PUBLIC_URL_INPUT_SCHEMA = {
+  ...STORAGE_IDENTITY_SCHEMA,
+  description: 'Identifies the stored object whose public URL is requested.',
+} as const satisfies DataSchema;
+
+export const STORAGE_PUBLIC_URL_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['publicUrl'],
+  properties: { publicUrl: { type: 'string' } },
+} as const satisfies DataSchema;
+
+export const STORAGE_LIST_INPUT_SCHEMA = {
+  type: 'object',
+  required: ['bucket'],
+  properties: {
+    storageId: { type: 'string' },
+    bucket: { type: 'string' },
+    prefix: { type: 'string' },
+    cursor: { type: 'string' },
+    limit: { type: 'integer' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_LIST_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['objects'],
+  properties: {
+    objects: { type: 'array', items: STORAGE_OBJECT_METADATA_SCHEMA },
+    nextCursor: { type: 'string' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_RESOLVE_INPUT_SCHEMA = {
+  ...STORAGE_IDENTITY_SCHEMA,
+  properties: {
+    ...STORAGE_IDENTITY_SCHEMA.properties,
+    access: { type: 'string', enum: ['public', 'signed'] },
+    expiresInSeconds: { type: 'integer' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_RESOLVED_ASSET_SCHEMA = {
+  ...STORAGE_IDENTITY_SCHEMA,
+  required: ['bucket', 'path', 'url', 'access'],
+  properties: {
+    ...STORAGE_IDENTITY_SCHEMA.properties,
+    url: { type: 'string' },
+    access: { type: 'string', enum: ['public', 'signed'] },
+    expiresAt: { type: 'string' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_RESOLVE_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['asset'],
+  properties: { asset: STORAGE_RESOLVED_ASSET_SCHEMA },
+} as const satisfies DataSchema;
+
+export const STORAGE_ADAPTER_ERROR_SCHEMA = {
+  type: 'object',
+  required: ['code', 'message'],
+  properties: {
+    code: { type: 'string' },
+    message: { type: 'string' },
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_SUCCESS_SCHEMA = {
+  type: 'object',
+  required: ['ok'],
+  properties: { ok: { const: true } },
+} as const satisfies DataSchema;
+
+export const STORAGE_ERROR_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['ok', 'error'],
+  properties: {
+    ok: { const: false },
+    error: STORAGE_ADAPTER_ERROR_SCHEMA,
+  },
+} as const satisfies DataSchema;
+
+export const STORAGE_VOID_RESULT_SCHEMA = {
+  oneOf: [STORAGE_SUCCESS_SCHEMA, STORAGE_ERROR_RESULT_SCHEMA],
+} as const satisfies DataSchema;
+
+export const STORAGE_UPLOAD_OPERATION_RESULT_SCHEMA = {
+  oneOf: [
+    {
+      ...STORAGE_SUCCESS_SCHEMA,
+      required: ['ok', 'data'],
+      properties: { ...STORAGE_SUCCESS_SCHEMA.properties, data: STORAGE_UPLOAD_RESULT_SCHEMA },
+    },
+    STORAGE_ERROR_RESULT_SCHEMA,
+  ],
+} as const satisfies DataSchema;
+
+export const STORAGE_PUBLIC_URL_OPERATION_RESULT_SCHEMA = {
+  oneOf: [
+    {
+      ...STORAGE_SUCCESS_SCHEMA,
+      required: ['ok', 'data'],
+      properties: { ...STORAGE_SUCCESS_SCHEMA.properties, data: STORAGE_PUBLIC_URL_RESULT_SCHEMA },
+    },
+    STORAGE_ERROR_RESULT_SCHEMA,
+  ],
+} as const satisfies DataSchema;
+
+export const STORAGE_LIST_OPERATION_RESULT_SCHEMA = {
+  oneOf: [
+    {
+      ...STORAGE_SUCCESS_SCHEMA,
+      required: ['ok', 'data'],
+      properties: { ...STORAGE_SUCCESS_SCHEMA.properties, data: STORAGE_LIST_RESULT_SCHEMA },
+    },
+    STORAGE_ERROR_RESULT_SCHEMA,
+  ],
+} as const satisfies DataSchema;
+
+export const STORAGE_RESOLVE_OPERATION_RESULT_SCHEMA = {
+  oneOf: [
+    {
+      ...STORAGE_SUCCESS_SCHEMA,
+      required: ['ok', 'data'],
+      properties: { ...STORAGE_SUCCESS_SCHEMA.properties, data: STORAGE_RESOLVE_RESULT_SCHEMA },
+    },
+    STORAGE_ERROR_RESULT_SCHEMA,
+  ],
+} as const satisfies DataSchema;

package/src/structure/generated.ts

@@ -2,12 +2,12 @@
 import type { StructureDescriptorDocument } from '@ankhorage/contracts/structure';
 
 export const STRUCTURE_DESCRIPTOR_COMPILER_VERSION = '6.0.3';
-export const STRUCTURE_DESCRIPTOR_FINGERPRINT = 'sha256:05419311d2828869c0ffc554890df986b462de036e7399cf2e9057c4ca381928';
+export const STRUCTURE_DESCRIPTOR_FINGERPRINT = 'sha256:535fb077e79daec8b09c756ed220bd7cb29bdf62d53559e3032ca246dd3f5bd3';
 
 export const STRUCTURE_DESCRIPTOR = {
   "protocolVersion": 1,
   "packageName": "@ankhorage/contracts",
-  "packageVersion": "25.1.0",
+  "packageVersion": "26.0.0",
   "roots": {
     "auth-flow": "AuthFlowConfig",
     "auth-profile": "AuthProfileSpec",

package/src/types.ts

@@ -2,7 +2,7 @@ import type { ColorHarmony } from '@ankhorage/color-theory';
 
 import type { AuthIdentifierKind, AuthSignUpField } from './auth';
 import type {
-  BindingValueSource,
+  BindingExpression,
   ComponentDataBindingRegistry,
   ScreenDataLoaderDefinition,
 } from './bindings';
@@ -153,7 +153,7 @@ export interface SvgIconSpec extends IconPresentationSpec {
 export type IconSpec = NamedIconSpec | SvgIconSpec;
 
 export interface UiNodeRepeatSpec {
-  source: BindingValueSource;
+  source: BindingExpression;
   itemAlias?: string;
   keyPath?: string;
   empty?: readonly UiNode[];