Execution Fabric Spec

Research Preview — v0.1.0-alpha.1

Execution contracts for portable placement across client, edge, and server.

Execution Fabric Spec explores an execution-first architecture for applications whose work may run in more than one environment.

Instead of hard-coding a task to a location, an application declares an Execution Contract. A reference scheduler compares that contract with host capabilities, data location, trust constraints, effects, and estimated transfer cost. The result is an explainable placement decision with qualification evidence.

Task
  ↓
Execution Contract
  ↓
Capability Profile
  ↓
Placement Decision
  ↓
Qualification
  ↓
Evidence

This repository is not intended for production use. It is a small, inspectable research artifact for discussing the execution model, testing its contracts, and collecting feedback before a production runtime is attempted.

Why this exists

Portable code alone does not decide where work belongs. A useful execution layer also needs to represent:

• where input data already resides;
• which effects and capabilities a task requires;
• whether a client result may be trusted;
• privacy and data-affinity constraints;
• latency, queueing, bandwidth, and memory estimates;
• fallback behavior;
• what was actually qualified and what remains unverified.

The central proposal is therefore not “run the same binary everywhere.” It is:

Describe execution once, then select a conforming implementation and location without changing application intent.

What is included

• task.manifest/v0.1 — an Execution Contract;
• host.capability-profile/v0.1 — a host declaration;
• an explainable deterministic reference scheduler;
• placement.trace/v0.1 — the reason and estimated data movement;
• qualification evidence and aggregation contracts;
• minimal Node, browser-worker-shaped, and edge-mock hosts;
• JSON Schemas, fixtures, golden traces, tests, CLI, and examples.

What is deliberately absent

This preview does not claim to provide a hardened distributed runtime, a hosted operations layer, a real cloud adapter, a real browser qualification result, or a complete WebAssembly Component implementation. Those areas remain research and roadmap work.

Quick start

Requirements: Node.js 22 or newer. The preview has no third-party runtime dependencies.

npm test
npm run conformance
npm run demo
npm run verify

Validate a contract:

npm run efspec -- validate examples/image-thumbnail.manifest.json

Explain placement for a 50 MB client-local input:

npm run efspec -- schedule \
  examples/image-thumbnail.manifest.json \
  examples/hosts.json \
  --input-bytes 50000000 \
  --input-location client

The reference scheduler should keep this task on the client and report zero input-copy bytes.

A minimal Execution Contract

{
  "schemaVersion": "task.manifest/v0.1",
  "task": { "name": "image.thumbnail", "version": "0.1.0" },
  "contract": {
    "inputSchema": { "type": "object" },
    "outputSchema": { "type": "object" }
  },
  "semantics": {
    "deterministic": true,
    "idempotent": true,
    "purity": "pure"
  },
  "effects": {
    "required": ["blob.read"],
    "forbidden": ["secret.read"]
  },
  "placement": {
    "allowed": ["client", "edge", "server"],
    "preferred": "client",
    "dataAffinity": "input",
    "privacy": "local-preferred"
  },
  "trust": {
    "clientResult": "accepted",
    "authoritative": false
  },
  "resources": {
    "memoryHintMb": 64,
    "deadlineP95Ms": 500
  },
  "retry": { "maxAttempts": 2 },
  "implementations": [
    { "target": "javascript", "artifact": "registry:image.thumbnail" }
  ]
}

Repository map

spec/          architecture and contract notes
schemas/       public JSON Schemas
src/           dependency-free reference implementation
conformance/   fixtures, golden decisions, and runner
examples/      example contracts and host profiles
bin/           research CLI
tests/         contract, runtime, CLI, and boundary tests
tools/         public-tree verification

Status and naming

The project name is provisional. Stable protocol identifiers do not include the display name, so the repository can be renamed without changing task.manifest/v0.1, host.capability-profile/v0.1, or other public contract identifiers.

See STATUS.md, spec/06-research-questions.md, spec/07-non-goals.md, and spec/10-compatibility-policy.md.

Package-registry publication is intentionally disabled in this preview. The source archive and Git repository are the supported distribution forms.

Contributing

The most useful early contributions are:

• critiques of the Manifest and Capability Profile;
• adversarial placement examples;
• alternative cost models;
• qualification and evidence requirements;
• related work that should be compared explicitly;
• minimal adapters that do not weaken the capability boundary.

Read CONTRIBUTING.md and GOVERNANCE.md before proposing changes.

Participate on GitHub

• Report reproducible implementation, CLI, schema, or conformance defects with the bug-report form.
• Discuss focused changes to contracts, schemas, compatibility, or conformance examples with the specification-proposal form.
• Follow the contribution guide before opening a pull request; the repository includes a pull-request template for the required validation and compatibility information.
• Report vulnerabilities through the private reporting process described in SECURITY.md, not in a public issue.
• Follow the source-release procedure in PUBLICATION_CHECKLIST.md. Releases remain prereleases while this repository is a Research Preview.

License

Code, schemas, and documentation are licensed under Apache License 2.0. See LICENSE and NOTICE.