#A3S Flow Workflows

A cognitive-package Flow is a first-class workflow contribution powered by A3S Flow. It shares the package's version, Registry provenance, dependency lock, generation, and atomic install/uninstall boundary.

There is one workflow engine:

package source / Code flow.json design
                 ↓ typed adapter
              A3S Flow
                 ↓
        local Code host / remote OS target

a3s-flow owns durable execution, event history, replay, scheduling, storage, and observation. A3S Use owns distribution, integrity, SemVer dependency resolution, capability dependencies, and package lifecycle. A3S Code provides product discovery and an injected runtime host.

#Manifest contract

Schema v3 declares a named Flow inside a3s-use-extension.acl:

flow "review" {
  engine         = "a3s-flow"
  runtime        = "native-ts"
  source         = "flows/review.ts"
  export         = "run"
  requires_tool  = ["convert"]
  requires_mcp   = ["library"]
  requires_okf   = ["domain-knowledge"]
  optional       = false
}

skill "review" {
  path          = "skills/review/SKILL.md"
  requires_flow = ["review"]
  optional      = false
}

ui "review" {
  entry     = "ui/review/index.html"
  skill     = "review"
  bind_flow = ["review"]
  optional  = false
}

engine = "a3s-flow" is fixed. native-ts is the first admitted runtime adapter, not another workflow engine. The source must be a bounded UTF-8 TypeScript file and export must be a portable TypeScript identifier.

#Dependency and lifecycle order

Flow owns no ambient permission ceiling. It can use only explicitly declared Tool, MCP, and OKF capabilities, each authorized and observed by its owning host.

Tool / MCP / OKF
        ↓
      Flow
        ↓
      Skill
        ↓
        UI

Install prepares this graph forward and publishes one package generation. Disable hides the generation before stopping it. Uninstall drains accepted work and removes surfaces in reverse. A missing or corrupted required Flow withholds its dependent Skill/UI and the new package generation.

#What flow.json means

A3S Code uses flow.json as the visible Workflow-as-a-Service design document. It is not a second package format or execution engine. An executable design carries a strict, path-free installedFlow reference that maps it to one exact installed package generation:

• Native TypeScript is an A3S Flow execution adapter.
• flow.json is a visual design/deployment document.
• A3S Code is a local editor and host.
• A3S OS is a remote deployment target.

No adapter may create a parallel package receipt, dependency graph, or lifecycle journal.

#Current implementation boundary

A3S Use implements manifest admission, exact source evidence, signed catalog closure, package lifecycle ordering, reconciler ownership, host-capabilities v6, managed scope v2, manager tools v5, typed capability projection, and a concrete A3sFlowLifecycleHost. That host delegates to the real a3s-flow Native TypeScript preflight, persists an exact-generation source/compiled-artifact binding, and reinspects both artifacts during observation. The standalone CLI composes it only when A3S_FLOW_NATIVE_TS_COMPILER names an absolute compiler path; otherwise required Flow packages fail before mutation. There is no source-presence or implicit PATH fallback.

The inactive Control Store qualification now also includes a committed-authority Flow owner. It reads a bounded source snapshot through the verified Artifact Store lease, publishes a durable no-clobber content-addressed copy in an owner-controlled workspace, and passes only that copy to the typed a3s-flow Native TypeScript preflight. The Artifact Store package root never crosses the owner boundary. Compiler/cache paths are operational host configuration rather than desired-state authority; source substitution and failed preflight reject without a Control observation, while Artifact Store contention safely defers under the same effect key. Stop and remove remain path-independent receipts. This owner is not wired into production composition until the Runtime and dispatcher cutover gates are complete.

The same explicit compiler path is used for install, upgrade, and uninstall after process restart. A compiler launch or preflight failure leaves the exact candidate installed-disabled. The capability snapshot retains only a non-active diagnostic record with capabilityReady = false; Flow, Skill, OKF, and UI projections remain absent. The durable receipt, plan, prepared dependency evidence, and lifecycle journal allow a repaired retry to resume the same admitted generation without exposing partial readiness.

Valid source bytes are necessary but not sufficient readiness evidence. A Flow remains pending and absent from the published catalog until the typed A3S Flow host reports successful preflight for that admitted generation; source corruption overrides even a stale positive host observation.

A3S Code injects the concrete host through its shared package lifecycle factory. CLI and TUI resolve the same strict flow.json identity. Before a new run, Code reinspects the current regular package source, verifies containment, size, UTF-8, and SHA-256, stages only the verified bytes, and completes Native TypeScript preflight before creating a binding or event. Both entrypoints use one cross-process-locked .a3s/flow-runtime/ event store without requiring an OS login.

CLI and TUI are the interactive local execution surfaces. The current implementation provides single-node crash/restart durability. Distributed worker placement, automatic resumption of suspended waits/retries/hooks, production retention/garbage collection, and complete real-process cross-platform coverage remain release gates. The roadmap tracks those gates explicitly.