The bundle

A bundle is the folder in your repository that holds an app's definition: authoric/ by default, or whichever folder you chose when you connected the repository. It always starts with an authoric.json.

authoric/
  authoric.json            # the root file: format version, what the bundle manages, layout
  deno.json                # optional: import map for the handlers
  deno.lock                # required whenever deno.json names a remote dependency
  tables/
    vendors.yaml           # one file per table, named for it
    invoices.yaml
  roles/
    approver.yaml          # one file per role, named by its key
  policies/
    refunds_small.yaml     # one file per policy, named by its key
  actions/
    orders.yaml            # a table's custom actions, named for the table
  agents/
    refunder.yaml          # one file per agent, named by its key
  jobs/
    nightly_dunning.yaml   # one file per scheduled job, named by its key
  storages/
    invoices.yaml          # one file per file storage, named by its key
  settings.yaml            # the app's brand, and the connections it may use
  environments/
    staging.yaml           # what differs for the app whose environment is staging
  handlers/
    _shared/money.mjs      # shared modules, copied into every handler
    refund_order/
      index.mjs            # one folder per handler; index.mjs is its entrypoint
    nightly_dunning/
      index.mjs

A bundle is read strictly. A file or folder the bundle does not know, a key authoric.json does not know, or a value of the wrong shape fails the deployment with the file and the fix, before anything changes. A typo never half-applies.

authoric.json

{
  "$schema": "https://authoric.ai/schema/authoric-v1.json",
  "formatVersion": 1,
  "manage": ["handlers"],
  "functionsRoot": "handlers",
  "entrypoint": "index.mjs",
  "shared": ["_shared"],
  "handlers": {
    "refund_order": {
      "entryAction": "orders:refund",
      "description": "Refunds an order up to its paid amount."
    },
    "nightly_dunning": { "kind": "worker" },
    "fixtures": { "exclude": true }
  }
}

Per handler folder:

A handler is named after its folder. A folder name that is not a valid handler name is turned into one (refund-order becomes refund_order), and two folders that would become the same name fail the deployment.

Tables

One file per table, tables/<name>.yaml, named for the table. List "tables" in manage to use them.

description: Vendors we pay.
scopeMode: shared        # or scoped: each row belongs to one of the app's organizations
deleteStrategy: soft     # or hard
locked: [delete]         # REST operations closed on this table
columns:
  - name: code
    type: varchar(32)
  - name: display_name
    type: varchar(190)
    renamedFrom: name    # rename, keeping the data
  - name: payment_terms
    type: enum('net_15','net_30','net_60')
    default: net_30
  - name: bank_account
    type: varchar(64)
    nullable: true
    redact: true         # never returned in reads
indexes:
  - columns: [code]
    unique: true
foreignKeys:
  - columns: [parent_vendor_id]
    references: { table: vendors, columns: [id] }
    onDelete: restrict

Per column:

Every table also has the platform's own columns (id, uid, org_id for a scoped table, and the timestamps). They are added for you; declaring one is refused.

How each change is classified:

Tables are created after the tables their foreign keys reference, and deleted before. A table made in the console that the bundle does not name is left alone.

Roles and policies

List "roles" and "policies" in manage to keep an app's access in the repository. A policy is its stored definition, unchanged; a role says which policies it carries.

# policies/refunds_small.yaml
name: Refunds up to $1,000
definition:
  version: "1.0"
  defaultEffect: deny
  actions:
    refunds:create:
      - effect: allow
        priority: 100
        when: { "arg.amount": { lte: 1000 } }

# roles/approver.yaml
display: Approver
policies:
  - policy: refunds_small
    priority: 100

The file name is the key: policies/refunds_small.yaml is the policy refunds_small in every app that deploys the bundle. A built-in role (such as User) is never defined by a bundle, only extended: its file lists the policies to attach, and nothing else. A bundle may also attach one of the platform's own policies by its key. Who holds a role stays in the app.

How each change is classified:

The bundle owns the bindings of the policies it manages. A policy made in the console stays on whatever roles it is on.

Custom actions

A table's custom actions live in actions/<table>.yaml. List "actions" in manage to use them.

# actions/orders.yaml
actions:
  - method: post
    path: /actions/refund
    description: Refund an order up to its paid amount.
    handler: refund_order
    allowedActions: [orders:read, refunds:create]
    schema:
      - { column_name: amount, data_type: decimal, is_nullable: "NO" }
    agentTool:
      name: refundOrder
      risk: high

How each change is classified:

Actions apply after the handlers they name, so a bundle can add a handler and the action that runs it in one deployment.

Agents

The app's own agents live in agents/<key>.yaml. List "agents" in manage to use them.

# agents/refunder.yaml
name: Refunder
description: Refunds an order when the customer is owed one.
effort: short
roles: [refund_operator]
llm:
  connection: Production OpenAI   # the AI connection's label in the console
autoApprove: false

An agent's on/off switch and its organization reach stay in the console: a deployment never turns an agent on or off, and only the owner, signed in, changes what organizations it reaches.

How each change is classified:

Scheduled jobs

The app's scheduled jobs live in jobs/<key>.yaml. List "jobs" in manage to use them.

# jobs/nightly_dunning.yaml
name: Nightly dunning
handler: nightly_dunning        # the handler it runs, by name
schedule:
  cron: '0 2 * * *'             # or every: 3600 (seconds)
  timezone: America/New_York
payload: { batch: 50 }
timeoutSeconds: 300
roles: [biller]

A job is born paused. A deployment creates it stopped and never starts or stops one: starting a job is a person's act in the console, and a later deployment leaves it running or paused as it was.

File storages

The app's file storages live in storages/<key>.yaml. List "storages" in manage to use them.

# storages/invoices.yaml
name: Invoices
visibility: private             # or public
maxFileBytes: 10485760
allowedMimeTypes: [application/pdf, image/png]

The file declares the storage, never its contents: folders, files and sharing are data and stay in the app. Where the files are kept is the app's own placement and never part of a bundle.

Settings

settings.yaml, at the root of the bundle, holds the app's brand and which of your connections the app may use. List "settings" in manage to use it.

# settings.yaml
branding:
  displayName: Cordell Group
  colors:
    light: { primary: '#1F4E79', accent: '#F2A900' }
  footer:
    company: Cordell Group LLC
    supportEmail: help@cordell.example
email:
  - alias: billing
    connection: Billing SMTP       # an email connection's label in the console
    default: true
tools:
  - alias: crm
    connection: Salesforce         # an external tool connection's label in the console
    tools: [lookup_account, update_account]

A connection is named by its label, so the same file works on every app you deploy it to, each using its own connection of that name. The label must name exactly one of your connections, and every tool must be one you have reviewed and enabled on it, or the plan fails before anything changes. A bundle never holds the connection's address or credentials.

The brand's images (logo, dark logo, icon) are files you upload in the console, so they stay the console's: a deployment keeps them as they are, and changing only an image in the console is allowed while the rest of the brand is managed by the repository.

Removing settings.yaml, or a grant from it, revokes only what a deployment granted. A grant made in the console that the file never named is left alone, and a brand the file no longer declares goes back to the console unchanged.

Environments

One repository can deploy several apps, such as staging and production, each connected to its own branch. Each app has an environment name, set by the app owner on its Deployments page, and environments/<name>.yaml holds what differs for that environment. A deployment merges it over the section files before checking them, so the result meets the same rules as any file.

# environments/staging.yaml
settings:
  email:
    - alias: billing
      connection: Staging SMTP
jobs:
  nightly_dunning:
    schedule: { cron: '0 * * * *' }
agents:
  refunder:
    llm: { connection: Staging OpenAI }

An environment changes where the app connects and how much it does, never what the app is or who may do what. These are the fields an environment may set:

Tables, roles, policies, custom actions and handlers are the same in every environment, and so are a job's or an agent's roles, an agent's auto-approval and a storage's visibility. What was reviewed and run in staging is what production runs, and an approval means the same thing everywhere.

Mappings merge key by key; a list or a value replaces what the file says, and null removes a key. An environment file changes objects the bundle declares; it never adds one. Every environment file is checked on every deployment, whichever one applies, so a mistake in one fails them all. An app with no environment, or one with no file, deploys the bundle as written.

Handlers

Each handler folder, with its shared folders and the bundle's Deno config, becomes one version of the handler. A deployment publishes a new version only when the files differ from what is live, so deploying an unchanged bundle changes nothing.

Every check the console runs on handler code runs on each handler in a bundle, before anything is applied: SQL passed to sdk.query() must be a string literal, external tool calls must be written literally and name a tool the app has, and none may run inside a transaction. A handler that fails one fails the deployment's plan.

Dependencies

A deno.json at the bundle root (or in functionsRoot) is the handlers' import map. When it names a remote dependency (npm:, jsr: or https:), a deno.lock must be committed beside it, or the deployment is refused: a rollback has to restore the same dependency graph as the code.

Limits

A bundle holds at most 2,000 files, none larger than 1 MB, and 16 MB in total. A bundle declares at most 500 handlers.

What a bundle never holds

Data (rows, users, files, runs, logs), secrets (keys, tokens, passwords) and who holds which role stay in the app. A bundle that needs a connection names it by its alias, never by its value.