PtcRunner.Kernel.Manifest (PtcRunner v0.14.0)

Copy Markdown View Source

Strict, path-confined version 1 JSON manifest loader.

The supported top-level shape is:

{
  "version": 1,
  "workflow": {
    "components": [
      {"id": "workflow.main", "path": "workflow.clj", "dependencies": ["agent.core"]},
      {"library": "agent.core"}
    ],
    "entry": "workflow.main/run"
  },
  "missions": {
    "default": {"components": [], "data": {}, "providers": []}
  },
  "input": {"value": {}},
  "contracts": {
    "input_schema": {"path": "input.schema.json"},
    "result_schema": {"path": "result.schema.json"}
  },
  "providers": {"workflow": [], "mission": []},
  "limits": {},
  "events": {"policy": "normal"},
  "labels": {}
}

Required top-level fields are version, workflow, and input. Every object rejects unknown and duplicate keys.

workflow.components and optional mission.components contain a strict tagged union: local id/path/optional dependencies objects or exact {"library": id} selections resolved only through PtcRunner.Kernel.Library. Installed dependencies expand deterministically and their invalid closures fail loading. Explicit duplicates and local/installed ID collisions also fail loading; local missing dependencies and cycles survive until bounded bundle compilation. The workflow entry is a qualified function name; PtcRunner.Kernel.RunBuilder renders the executable entry expression. Input contains exactly one of a JSON object in value or a manifest-relative JSON file in path. Optional manifest-local contracts validate input before provider activity and Result.value before publication. Contract schemas use the bounded PtcRunner.Kernel.ValueContract profile.

Provider entries contain a bounded name and JSON config. The manifest can select only builders installed in PtcRunner.Kernel.ProviderRegistry; there are no implicit provider names. An MCP installation containing a write mapping requires an explicit, nonempty manifest allow list; omission is accepted only when every installed mapping is read-only. Installed MCP providers may accept a model_visible subset of their authorized allow names, including mappings whose host model_visible flag is false. Omitted, it defaults to the authorized names the host already marked visible. Visibility controls discovery and model context only, never authority. Limit names are the :manifest_narrowable rows in PtcRunner.Kernel.LimitCatalog; version 1 accepts values no greater than the host-supplied installed ceilings. Omitted values use the normal runtime defaults, capped by a lower host ceiling. Installed-only rows remain host-owned. Event policy is normal or private with optional run and trace IDs. Labels use the closed name, model, provider, and flat tags safe-metadata profile. Identifier fields become SHA-256 fingerprints and tags use finite enumerated values, so arbitrary text and secrets are never copied into traces. Schema-validation timeouts and heap exhaustion are reported as unavailable work rather than as manifest violations.

The loader resolves paths relative to the canonical manifest directory and rejects absolute paths, traversal, devices, non-regular files, and symlink escape. Loading performs no workflow execution.

Summary

Types

t()

Functions

load(path, installed_limits \\ Limits.installed_defaults())

Loads and validates one manifest and all referenced source/input files.

load_memory(manifest_name, documents, installed_limits \\ Limits.installed_defaults())

Loads one manifest from an in-memory portable logical-name/bytes map.

schema()

Returns the generated JSON Schema 2020-12 structural manifest contract.

Types

t()

@type t() :: %PtcRunner.Kernel.Manifest{
  contract_sources: %{input: binary() | nil, result: binary() | nil},
  contracts: %{
    input: PtcRunner.Kernel.ValueContract.t() | nil,
    result: PtcRunner.Kernel.ValueContract.t() | nil
  },
  document: map(),
  entry: binary(),
  events: %{
    policy: :normal | :private,
    run_id: binary() | nil,
    trace_id: binary() | nil
  },
  input: map() | nil,
  input_declaration: map(),
  installed_limits: PtcRunner.Kernel.Limits.t(),
  labels: map(),
  limits: PtcRunner.Kernel.Limits.t(),
  missions: %{
    required(binary()) => %{
      components: [PtcRunner.Kernel.Component.t()],
      kinds: %{required(binary()) => :local | :library},
      data: map(),
      provider_occurrences: [non_neg_integer()]
    }
  },
  providers: %{workflow: [map()], mission: [map()]},
  workflow_component_kinds: %{required(binary()) => :local | :library},
  workflow_components: [PtcRunner.Kernel.Component.t()]
}

Functions

load(path, installed_limits \\ Limits.installed_defaults())

@spec load(binary(), PtcRunner.Kernel.Limits.t()) :: {:ok, t()} | {:error, term()}

Loads and validates one manifest and all referenced source/input files.

load_memory(manifest_name, documents, installed_limits \\ Limits.installed_defaults())

@spec load_memory(
  binary(),
  %{required(binary()) => binary()},
  PtcRunner.Kernel.Limits.t()
) ::
  {:ok, t()} | {:error, term()}

Loads one manifest from an in-memory portable logical-name/bytes map.

Every supplied document must belong to the exact referenced closure; unused entries are rejected.

schema()

@spec schema() :: map()

Returns the generated JSON Schema 2020-12 structural manifest contract.