Dependencies & Repositories

Dependencies are reusable artifacts — repositories, component definitions, pre-defined action chains, or device services — declared in a module’s dependencies array. All dependencies are initialized when the module is decoded.

5.1 Dependency Array Structure

"dependencies": [
{ "repository": { "remote":   { "id": "repo_api",    "config": { "endPoint": "https://..." } } } },
{ "repository": { "local":    { "id": "repo_local",  "config": {} } } },
{ "repository": { "secured":  { "id": "repo_keys",   "config": {} } } },
{ "repository": { "firebase": { "id": "repo_fb",     "config": { "collectionPath": "apps/app_id" } } } },
{ "component":  { "id": "my_template", "type": "vstack", ... } },
{ "action":     { "repo": { "id": "my_shared_action", ... } } },
{ "service":    { "audio": { "id": "audio_service_id" } } },
{ "service":    { "push":  { "id": "push_service_id"  } } }
]

ℹ Note: Ordering matters: a dependency MAY only reference dependencies declared earlier in the same array.

5.2 Addressing Dependencies

"repositoryId": "repo_api"          // In a repo action
"_source": "dp://my_template"       // In a template _source
"serviceId": "audio_service_id"     // In a service action
"dependencyId": "repo_fb"           // In a listen action

5.3 Repository Kinds

Repositories expose four CRUD operations: create, read, update, delete. HTTP mapping for remote: create=POST, read=GET, update=PUT/PATCH, delete=DELETE.

Kind	Description	config fields
remote	Network-backed REST repository.	endPoint (required): base URL string. interceptor (optional): see §5.4.
local	Document-oriented local JSON storage. Persists across app sessions.	No required fields for v1.0. Pass config: {}.
secured	Secure key/value store (platform keychain) for secrets and tokens.	No required fields for v1.0. Pass config: {}.
firebase	Realtime backend integration. Designed for use with the listen action.	collectionPath: root path in the Firebase project.
photos	Device photo library access. Presents a native picker UI on read.	No required fields for v1.0. Pass config: {}.
ai	Host-provided AI provider. The host injects the endpoint, credentials, and model routing; modules never carry AI credentials or provider URLs. Target of the ai action’s input.provider for host-managed inference (§10.11).	No required fields for v1.1. Pass config: {}.

photos repository — operations and params

Operation	Purpose	params fields
read	Open the native photo picker. On success, the output context key receives an array of the selected photo file:// URLs — one element per selection, [] if cancelled — for any selectionLimit. Unwrap a single pick with first(...) or [0]; each URL is usable directly as a media/image source.	selectionLimit (number, default 1): maximum photos the user can select. mediaTypes (array of strings): filter by "image" and/or "video".
create	Save a photo URL to the device library.	url (string/expr): the image URL to save.
delete	Delete a photo from the device library by its asset identifier.	assetIdentifier (string/expr): platform-native asset ID returned by a previous read.

"dependencies": [
  { "repository": { "photos": { "id": "photos", "config": {} } } }
]

{
  "repo": {
    "id": "pick_single_action_id",
    "repositoryId": "photos",
    "operation": "read",
    "params": {
      "selectionLimit": 1,
      "mediaTypes": ["image"]
    }
  },
  "output": {
    "success": [
      { "state": { "id": "set_photo", "input": { "photoURL": "@{pick_single_action_id}" } } }
    ]
  }
}

5.4 Remote Repository: Auth Interceptor

Remote repositories support an interceptor that reads one or more tokens from a secured repository and injects them into request headers automatically.

{ "repository": { "remote": {
"id": "repo_openai",
"config": {
"endPoint": "https://api.openai.com/v1/responses",
"interceptor": {
"adapter": {
"operations": [
{ "kind": "setBearerToken", "repositoryId": "repo_keys", "key": "openai_token" }
]
},
"retrier": { "maxRetries": 3, "retryDelay": 1.0 }
}
} } }

Interceptor field	Description
adapter.operations	Array of operation objects applied in order to every outgoing request.
adapter.operations[].kind	Operation kind: setHeader (named header), setBearerToken (Authorization: Bearer ), setQueryParam (URL query parameter).
adapter.operations[].field	Target header name or query param name. Required for setHeader and setQueryParam.
adapter.operations[].repositoryId	ID of a secured repository to read the token value from. Mutually exclusive with value.
adapter.operations[].key	Key to look up in the repository. Required when repositoryId is set.
adapter.operations[].value	Static string value to inject directly. Mutually exclusive with repositoryId/key.
retrier.maxRetries	Maximum retry attempts on transient failures. Default: 3.
retrier.retryDelay	Delay in seconds between retries. Default: 1.0. Retries on: serviceUnavailable, internalServer, noConnection, timeout.

5.5 Service Dependencies

Services expose device or platform capabilities. Declare them in the dependencies array and invoke them via the service action.

{ "service": { "audio": { "id": "audio_service_id" } } },
{ "service": { "push":  { "id": "push_service_id"  } } }

Known service kind	Purpose
audio	Plays sounds and triggers haptic feedback.
push	Schedules local notifications via UNUserNotificationCenter. Does not send remote push notifications.

5.6 Component & Action Dependencies

Reusable component subtrees and pre-defined action chains can be registered as dependencies. Component dependencies are referenced with dp:// from template components. Action dependencies are invoked by their id via the template action kind.