TAR Harness

Abstract

TAR is a local-first work platform for a general workforce. Owners and admins define Data, Bots, Workflows, Steps and access. Workers receive role-filtered Data, Inbox work and Action Cards. Deterministic code owns official state changes; bounded AI may assist or control an agentic Step without gaining authority to commit changes. The Gateway enforces this boundary across online, offline and external-system work.

1. Product model

Workspace
|-- Data
|   `-- Products, customers, orders, sales and any custom business records
|-- Bots
|   `-- Bot
|       `-- Workflows
|           `-- Workflow
|               `-- ordered Steps
`-- Gateway
    `-- validates and records every official change

A Step may use any combination of a Card, App function and AI help. Most Steps do not need a Card. Step is the only builder term for work.

AI may propose a result but cannot directly write records, process payments, change permissions or call consequential external systems.

2. Step execution standard

A Step is the only unit of work exposed by the builder. Its implementation may combine one or more registered action primitives.

Step
|-- mode            deterministic | agentic
|-- actions[]       one or more registered primitives
|-- card?           optional human interface
|-- entry           conditions required to start
|-- access          permitted roles and record scope
|-- next            success transition
`-- on_error        deterministic failure transition

2.1 Execution modes

AI help is a capability; agentic is a control mode. Therefore, a deterministic Step may use AI to extract or draft a declared output, while an agentic Step may decide how to pursue a bounded objective.

An agentic Step declares:

objective
context
allowed_actions
allowed_transitions
output_schema
budget
timeout
fallback

The LLM may read permitted context, call allowlisted read/draft capabilities, select an allowed transition and propose a change. It cannot expand its allowlist, change its budget, bypass approval or directly commit Data, payments, permissions or external effects. Invalid, uncertain or exhausted runs follow the declared fallback.

Agentic Step reasons
  -> selects allowed action or transition
  -> Gateway validates authority, input and current state
  -> deterministic code executes or rejects
  -> result and rationale are recorded

2.2 Action primitives

Primitives are implementation details beneath a Step. People build and run Steps; they do not manually orchestrate primitives. Every primitive declares validation, permission, idempotency, timeout, retry and audit behavior. AI primitives can propose outputs but cannot grant themselves authority to commit changes.

2.3 Card standard

Cards are reusable interfaces, not separate business records or execution primitives.

A Step Card belongs to the active Step. A Workspace Work Card is a role-filtered projection or Workflow launcher. A Data Card presents Data; it does not become the Data itself. Card definitions live inside approved Data or Bot definitions and are rendered from their authorized runtime context. No separate Cards table is required.

3. AI-first builder

Describe the work
  -> TAR asks short guided questions
  -> TAR checks existing Workspace Data
  -> TAR reuses suitable Data or proposes new Data and fields
  -> TAR drafts the Bot, Workflows and ordered Steps
  -> person reviews Data, fields and actions
  -> Gateway creates the approved definitions

The review stays simple:

POS Bot
  Data: Products, Customers, Sales, Inventory

  Checkout
    1. Select products
    2. Calculate total
    3. Take payment
    4. Update inventory
    5. Send receipt

  [Create Bot]  [Change something]  [More options]

TAR never silently creates structures, copies sensitive information or grants access. More options exposes field types, relationships, validation, statuses and permissions.

4. Storage architecture

Control DB    -> identity, Workspaces, memberships and database routing
Workspace DB  -> official shared truth
Personal DB   -> private Me plans and local-first authorized working set
R2 / OKF      -> files, long content and knowledge
Gateway       -> permission, validation, commitment, sync and audit

The mobile app syncs only the Personal DB and never receives unrestricted Workspace DB credentials.

4.1 Control DB

4.2 Workspace DB

Each Workspace DB has six tables. It does not repeat a Workspace ID in every row.

defs(id, kind, name, body, version, status, created, updated)
  kind: data | bot

records(id, type, title, data, status, version, owner, created, updated)

links(id, from_id, to_id, kind, data, created)

runs(id, bot, workflow, step, state, data, version, created, updated)

access(role, type, scope, read, add, edit, remove, offline)
  scope: all | team | assigned | own | none

events(id, kind, actor, ref, data, idem, created)

defs.body contains fields, validation and display rules when kind = data; it contains Bot settings and complete ordered Workflows and Steps when kind = bot. Approvals and file metadata are typed records; binary files are not.

4.3 Personal local-first DB

Every Personal DB row that can be rendered carries source metadata. Private Me rows use source: private; synced Workspace rows retain their source Workspace identity. Rows without a valid private source or accessible Workspace origin are not rendered.

Me is a private view, not a Workspace. It renders only confirmed private Plans, Routines, manual private tasks, their active Runs, real report data and pending user-confirmed Plan updates. It never renders Workspace Inbox items, Workspace work, Workspace Data definitions or Workspace reports. Workspace shortcuts may open a Workspace but never copy its work into Me.

The authorized working set contains assigned, owned, recent, Inbox-linked, offline-pinned or explicitly downloaded Workspace records. These records are complete enough to use offline; their Workspace versions remain official. The working set is not Me content.

Turso partial sync reduces bootstrap and bandwidth for this authorized Personal DB. Partial sync is not an authorization boundary.

5. R2 and OKF

users/{user}/files/{file}
spaces/{space}/files/{record}/{file}
spaces/{space}/okf/{type}/{record}.md
spaces/{space}/exports/{export}

Use one OKF Markdown file per record by default for its long description, detailed specifications, FAQ, provenance and Agent knowledge. Images, video, audio and PDFs remain separate R2 objects. Split the OKF file only for size, permission or independent-update needs.

External content is stored only when the person owns it or has permission.

6. Access and local-first operation

Roles set the maximum permission. A Bot or Step may narrow it but cannot broaden it. Offline access is explicit per Data type; sensitive Data can set offline = false.

Workspace person acts locally
  -> UI updates immediately
  -> command enters Personal DB
  -> Turso pushes when connected
  -> Gateway checks membership, role, Bot, Step, schema and base version
  -> Workspace DB accepts or rejects
  -> Gateway appends an event
  -> confirmed result returns to Personal DB

commands(id, space, action, target, data, base_version, status, created)
  status: pending | accepted | rejected | conflict

The device can read authorized Workspace defs, records, links and inbox, and append commands. It cannot directly edit Workspace records, definitions or permissions. Private Routine completion may update Me immediately on-device and is replayed with its idempotency key after reconnection.

The UI shows Pending sync until confirmation. Ordinary independent field changes may merge deterministically. Payments, approvals, inventory deductions and permissions never use automatic last-write-wins; conflicts pause for review or a registered resolution function.

Local databases are encrypted with a device-protected key. Access expires, membership changes increment the access version, revoked records are removed on reconnection, and logout removes the local key and cache.

7. Gateway

For every official change, the Gateway checks:

1. Workspace membership and role.
2. Bot and Step authority.
3. Data schema and current state.
4. Record version and idempotency key.
5. Approval and duplicate-protection requirements.

It then rejects the request or commits it and appends an audit event. A rejection remains visible with a corrective message.

8. Inbox Step functions

Inbox connects a person to a waiting Workflow:

inbox.create
inbox.assign
inbox.request_input
inbox.request_approval
inbox.complete

Workflow waits for a person
  -> Gateway creates Personal Inbox item
  -> person responds online or offline
  -> response becomes a command
  -> Gateway validates it
  -> Workflow continues and Inbox item completes

inbox(id, space, run, step, kind, title, body,
      status, priority, due, version, created)

The Inbox item references the official Workspace run; it does not replace it.

9. Agent access

Agents query official Workspace Data through Gateway tools. They receive only relevant definitions, permission-filtered query results, current Workflow context and registered Step actions. They never receive an entire database or use Personal projections for official decisions.

The same safety boundary applies to AI help and agentic Steps. AI help returns a declared result to fixed control flow. An agentic Step may select allowlisted actions or transitions, but every official effect remains a deterministic Gateway execution.

Agent proposes -> Gateway validates -> person approves when required -> code commits

Use indexed SQL and full-text search before embeddings. Use embeddings only for semantic retrieval over long OKF knowledge.

10. App UI

Workspace
|-- Work
|-- Inbox
|-- Data
`-- Build                    owner/admin only
    |-- Bots
    |-- Data definitions
    `-- Workflows

Me
`-- Today
    |-- confirmed private Plan and Routine cards
    |-- pending Plan-update cards
    `-- Plan / add action

Workspace navigation is Work · Inbox · Data for workers and Work · Inbox · Data · Build for owners and admins. Build is the internal owner/admin selector; workers do not see it. The app opens the last selected real Workspace by default. Me is opened explicitly from the Workspace switcher.

Me uses normal language: Today, Plan and Routine. Bots and definitions remain internal implementation terms for private planning and do not appear in Me.

10.1 Ownership and visibility

Workers do not normally see builder definitions. Build is visible only when the person's role grants management access.

10.2 Workspace Work and Inbox

Work      -> active role-filtered runs, report cards, approved Data views and action launchers
Inbox     -> waiting assigned work only
Data      -> permitted Workspace Data
Build     -> Bots, Data definitions and Workflows for owners and admins

Starting an Inbox item moves it into Work in that same Workspace. Inbox does not duplicate active work. Workspace Work is derived from authorized Bot definitions, Workflow state and Workspace Data. It is not manually assembled per person and requires no separate Work or Cards table.

To stay uncluttered, Work shows active work first, then permitted action launchers, report cards and approved Data views. Priority is deterministic: urgent work, due work, active runs, then permitted launchers and summaries.

Data supports browse, search, add, view, permitted editing, archive, offline availability and pending-sync state. Destructive actions use an overflow menu and confirmation. Normal UI always says Data, not Artifact.

11. Canonical rules

1. Workspace DB holds official shared truth; Personal DB enables authorized local-first work.
2. Bots own Workflows; Workflows contain ordered Steps.
3. A Step may combine optional Card, App function and AI help.
4. Gateway is the only path to official Data or external-system changes.
5. Inbox is a deterministic human-action primitive that can pause and resume runs.
6. R2/OKF holds heavy content, not operational truth; default to one OKF file per record.
7. Synchronize only the active authorized working set and project changes only to affected people.
8. Use one Personal sync connection per person and one database per real Workspace, never per Bot.
9. Use SQL search before embeddings.
10. AI plans and assists; deterministic code authorizes and commits.
11. Owners and admins manage definitions in Build; workers receive role-filtered Workspace Work, Data and Inbox work.
12. Action primitives remain beneath Steps and never appear as a second builder model.
13. Every Step declares deterministic or agentic control mode.
14. Agentic Steps may choose only allowlisted actions and transitions; the Gateway retains execution authority.
15. Me is private life only: it contains private Plans, Routines, active private Runs and user-confirmed Plan changes; it never becomes a cross-Workspace inbox or data browser.

“Bots provide capability. Workflows organise Steps. Workspace Data holds truth. Personal Data enables offline work. Inbox connects people to work. Gateway protects every official change.”