Source-inspection reference

This page says where each kind of source can be retrieved, and which surface owns the details.

An application's own attached prelude is not a separate retrieval mechanism: local and shipped components use the same active component shape. Direct Lisp evaluation without a Kernel environment has no component graph, so (components) returns [] and (component id) returns nil. Active inspection exposes direct component IDs for recursive lookup. Completed-run inspection follows recorded typed relationships. Neither path reconstructs dependencies from host log text.

Where to retrieve source

Lifetime	Surface	Exact bytes?	Channel	Limits
Installed contracts	`ptc docs`, `(doc)`, `(export-meta)`	No; contracts and docstrings	Print or data	Print budget for `doc`
One attached defining form	`(source ref)`	The reachable defining form	Print	Print budget; no registry or filesystem fallback
Active workflow or mission graph	`(components)`, `(component id)`	Yes; interned effective source	Data	`terminal_result_bytes`; per-environment catalog
Credential-free preparation	`ptc repl --inspect-only`	Same catalog as a live session	REPL	No providers, input, traces, or private-session authority
Admitted nested-loop programs	`agent.core/run-outcome` with `retain_programs`	Yes, after admission	Outcome data	Count 1–128 and a 2,000,000-byte newest-whole-entry ring
Completed recorded run	`analysis/read` on private inspection	Yes; recorded programs and prelude sources	Private inspection	Private artifact authorization

Public traces carry identities, hashes, dependency projections, and outcomes. They do not carry source. Host logs and telemetry are not export surfaces.

Active components

(components) returns attached IDs in frozen dependency order for the selected workflow or mission environment. (component id) returns nil when the ID is absent, otherwise:

Key	Meaning
`:id`	Exact component ID
`:dependencies`	Direct edges only
`:namespaces`	Declared namespaces
`:source-hash`	Qualified `sha256:` of the exact source bytes
`:source`	Complete effective source, including private helpers and an active override

:origin is omitted. There is no shipped-library or filesystem fallback for an unattached ID. A workflow evaluation cannot read a mission component, and a mission cannot read the workflow graph. Returning a component map or its :source is charged to the ordinary evaluation result limit; bind the value and slice :source when it is large.

The catalog is not prelude metadata and is never copied into result stamps, traces, telemetry, or host logs. Only an explicit component call moves attached source into ordinary workflow data. Component files must not contain credentials.

ptc repl --inspect-only compiles the selected project or manifest environment and attaches that catalog without an environment file, input, provider, or capability. When a project declares a host, project mode reads that document only for non-secret installed limit ceilings; credentials remain unresolved and providers remain inactive. Pure attached functions may run; Kernel, provider, and capability routes fail closed. See the REPL reference.

Admitted programs

retain_programs exists only on agent.core/run-outcome. Omitted or nil keeps the historical outcome shape. When set, every returned outcome includes :programs and :programs-omitted. Entries keep :turn, :mission, exact :source, and a bounded :execution summary for programs admitted to subordinate evaluation. Protocol errors and source refused before admission are excluded. See the agent library reference.

Export and candidate files

ptc materialize has two exclusive modes. --source-out writes interned installed bytes for later editing. --source/--out then hashes those edited bytes into {candidate.clj, descriptor.json}. Candidate mode keeps the existing 1 MiB replacement bound; a larger installed component can still be inspected or exported. See the component reference.

Completed runs

Private inspection retains exact generated programs, component sources, turns, and typed relationships. ptc transcript is one private conversation, not a general source export. See the debug-navigation reference.