Workspace Analysis v1

September 20, 2026 · View on GitHub

Status: versioned bounded reference; the completion matrix owns product status.

Audience: workspace tool authors and compiler contributors.

Workspace Analysis v1 defines deterministic, read-only Context, Impact, and Review artifacts over one authenticated Workspace Semantic Graph v1. The three artifacts operate only on the six admitted cross-file edge families and retain typed module, declaration, and capability namespaces. A module bridge node is never selectable and is never conflated with a declaration that has the same string spelling.

Public API

The closed public enums are:

pub enum WorkspaceAnalysisTargetKind { Declaration, Capability }
pub enum WorkspaceAnalysisDirection { Forward, Reverse, Both }

Options are immutable Copy + Debug + Eq + PartialEq values with no public field getters:

WorkspaceContextOptions::new(direction, depth, max_bytes, max_nodes)
WorkspaceImpactOptions::new(depth, max_bytes, max_nodes)

Context defaults to Both, depth 4, 1,048,576 bytes, and 1,024 nodes. Impact defaults to depth 16, 1,048,576 bytes, and 1,024 nodes.

pub fn context(
    root: &Path,
    entry_module: &str,
    target_kind: WorkspaceAnalysisTargetKind,
    target: &str,
    options: WorkspaceContextOptions,
) -> Result<String, Vec<Diagnostic>>;

pub fn impact(
    root: &Path,
    entry_module: &str,
    target_kind: WorkspaceAnalysisTargetKind,
    target: &str,
    options: WorkspaceImpactOptions,
) -> Result<String, Vec<Diagnostic>>;

pub fn review(
    root: &Path,
    entry_module: &str,
    target_kind: WorkspaceAnalysisTargetKind,
    target: &str,
) -> Result<String, Vec<Diagnostic>>;

The API strings are compact JSON without a terminal LF. The CLIs add exactly one LF:

semaprax workspace-context <root> <entry-module> <declaration|capability> <target> [--direction forward|reverse|both] [--depth N] [--max-bytes N] [--max-nodes N]
semaprax workspace-impact <root> <entry-module> <declaration|capability> <target> [--depth N] [--max-bytes N] [--max-nodes N]
semaprax workspace-review <root> <entry-module> <declaration|capability> <target>

Unknown, duplicate, missing-value, or noncanonical numeric options exit 2 and write no stdout. Domain diagnostics exit 1.

Selection and traversal

Targets are 1–4,096 UTF-8 bytes and contain no NUL. A declaration target must be explicit or automatic, must be in the authenticated entry provider closure, and cannot be compiler-owned. A capability target must occur as an effect_requirement or capability_authority target. Missing or out-of-closure targets are SPX-G177; compiler-owned declaration targets use the same code with the dedicated unsupported message.

The exact edge-family order is:

function_import,type_import,call,type_reference,effect_requirement,
capability_authority

Typed endpoints are:

Family	Source	Target
`function_import`	module	declaration
`type_import`	module	declaration
`call`	declaration	declaration
`type_reference`	declaration	declaration
`effect_requirement`	declaration	capability
`capability_authority`	module	capability

The implementation independently rebuilds and exact-compares these endpoints, paths, namespaces, and adjacency indexes before BFS. Context uses minimum-depth forward, reverse, or bidirectional BFS. reached_by is an array in canonical root,forward,reverse enum order. Only the root carries root; tied forward and reverse paths may emit both direction values. Context emits each authenticated compatible edge once by Workspace edge index when both endpoints are emitted.

Impact is reverse-only potential structural dependency closure. It emits only minimum-path dependency edges. Affected roles are target, consumer, module_consumer, and dependency; reasons are unique contributing edge families in the frozen family order. These are not behavioral-change claims.

Nodes are selected and emitted in (minimum_depth,node_key) order. Node-key order is module, then declaration ordered by declaration kind and ID, then capability. When bounded, the frontier contains only the first omitted known depth and is globally node-key sorted. omitted_known_nodes and deferred_known_nodes count unique typed nodes, not edges.

Schemas and common wire

The schemas and digest domains are:

Artifact	Schema	Digest domain
Context	`semaprax.workspace-semantic-context.v1`	`semaprax.workspace-semantic-context.artifact-digest.v1\0`
Impact	`semaprax.workspace-semantic-impact.v1`	`semaprax.workspace-semantic-impact.artifact-digest.v1\0`
Review	`semaprax.workspace-semantic-review.v1`	`semaprax.workspace-semantic-review.artifact-digest.v1\0`

Every artifact is compact canonical UTF-8 JSON without a terminal LF. Its artifact_digest is lowercase sha256: plus 64 hex digits over domain || u64_le(payload.len) || payload, where payload is the exact top object with only artifact_digest omitted and final fixed-point output usage already present.

Context top-level order is:

schema,workspace_manifest_schema,workspace_revision,workspace_graph_digest,
artifact_digest,entry,target,query,limits,budget,truncation,frontier,nodes,
edges,nonclaims

Impact replaces the final node/edge fields with affected,dependency_edges. Review top-level order is:

schema,workspace_manifest_schema,workspace_revision,workspace_graph_digest,
artifact_digest,entry,target,context,impact,sections,limits,budget,nonclaims

Nested key order is:

entry:      module,path
target:     kind,id,declaration_kind,identity_origin,path,module
query:      direction,depth,max_bytes,max_nodes,edge_kinds
truncation: truncated,reasons,omitted_known_nodes,deferred_known_nodes
frontier:   kind,id,minimum_depth,reached_by
node:       kind,declaration_kind,identity_origin,id,path,module,
            minimum_depth,reached_by
affected:   kind,declaration_kind,identity_origin,id,path,module,
            minimum_depth,impact_role,reasons
edge:       caller_path,caller,target_path,target,kind,site,expression,
            ast_path,alias,ordinal

Truncation reasons are max_depth, max_nodes, and max_bytes. Context and Impact may return complete bounded prefixes with explicit truncation facts. Review uses fixed maximum children and rejects any child truncation, omitted or deferred node, or frontier as SPX-G180: Workspace Semantic Review requires complete Context and Impact evidence.

Review embeds the exact complete Context and Impact JSON objects from the same typed analysis; it does not parse child JSON as authority. sections is an object ordered behavior, api_identity, security_authority, memory_ownership, target_artifact, migration, unsafe. Each value is an array containing exactly one finding with keys code,disposition,statement,evidence. Evidence references use keys artifact,relation,index, point only to context/edges, impact/affected, or impact/dependency_edges, and sort Context before Impact, affected before dependency edges, then by index.

The exact findings are:

Section/code	Evidence present	Evidence empty
behavior / `workspace_behavior_dependencies`	`review_required`: `Authenticated workspace call dependencies require review.`	`informational`: `No authenticated workspace call dependencies are present in the selected closure.`
api_identity / `workspace_api_identity_dependencies`	`review_required`: `Authenticated workspace API identity dependencies require review.`	`informational`: `No authenticated workspace API identity dependencies are present in the selected closure.`
security_authority / `workspace_security_authority_dependencies`	`review_required`: `Authenticated workspace security-authority dependencies require review.`	`informational`: `No authenticated workspace security-authority dependencies are present in the selected closure.`
migration / `workspace_migration_dependencies`	`review_required`: `Authenticated workspace consumer dependencies require migration review.`	`informational`: `No authenticated workspace consumer dependencies are present in the selected impact closure.`

The three fixed unsupported findings are workspace_memory_ownership_not_analyzed / not_analyzed / Workspace memory-ownership effects are not analyzed by this version., workspace_target_artifact_not_analyzed / not_analyzed / Workspace target-artifact effects are not analyzed by this version., and workspace_unsafe_not_analyzed / not_analyzed / Workspace unsafe-code effects are not analyzed by this version.. Each has empty evidence.

Behavior evidence selects Context edges and Impact dependency edges whose kind is call. API evidence selects those whose kind is function_import, type_import, or type_reference. Security evidence selects effect_requirement or capability_authority. Migration selects every non-root Impact affected entry. The only allowed artifact/relation pairs are context/edges, impact/affected, and impact/dependency_edges; references are unique and sort by artifact, relation, then numeric index. Review is dependency review, not approval, policy, a security audit, or general semantic review.

Limits and usage

All routes embed the exact Workspace Semantic Graph limits and budget objects under limits.workspace and budget.workspace.

Corrective byte compatibility: the embedded limits.workspace.max_builder_bytes is 67,108,864, exactly matching the Workspace Semantic Graph v1 SPX-G171 limit. Earlier Analysis v1 bytes that embedded 16,777,216 were defective and are not canonical. The corrected embedded object changes Context, Impact, and Review artifact digests without changing either schema or any enforced ceiling.

Context and Impact analysis limits, in exact order, are:

max_target_bytes=4096
max_traversal_depth=1024
max_traversal_nodes=8208
max_analysis_builder_bytes=16777216
max_output_bytes=16777216

Public max_bytes must be 4,096–16,777,216, max_nodes must be 1–8,208, and depth must be 0–1,024. Review adds max_context_bytes=16777216,max_impact_bytes=16777216 before max_output_bytes=33554432 and uses one cumulative 16 MiB analysis-builder budget across the shared graph build and both child analyses. Embedded child artifacts remain byte-identical to their standalone canonical forms.

Context/Impact analysis budget order is:

used_target_bytes,used_traversal_depth,used_traversal_nodes,
used_analysis_builder_bytes,used_output_bytes

Review inserts used_context_bytes,used_impact_bytes before output. Rendering uses hard output sinks and reserve-first envelope accounting. Option grammar is SPX-G176; target absence/compiler rejection is SPX-G177; limits are artifact-specific SPX-G178; typed replay/digest disagreement is artifact-specific SPX-G179; incomplete Review evidence is SPX-G180.

For Review, used_traversal_depth is the maximum emitted child depth, used_traversal_nodes is the maximum child node count, used_analysis_builder_bytes is the cumulative shared analysis debit, and used_context_bytes and used_impact_bytes are the exact canonical child lengths.

Ordered nonclaims

Context begins with:

no_patch_candidate_change_or_semantic_delta
no_impact_or_review_claim
only_six_workspace_graph_edge_families
no_embedding_search_ranking_or_answer_quality

Impact begins with:

potential_structural_dependency_impact_not_patch_candidate_or_behavioral_delta
no_source_consumer_span_or_authored_operation_provenance
only_reverse_closure_over_six_workspace_graph_edge_families
no_repair_review_ranking_or_commit_authority

Review begins with:

dependency_review_not_patch_change_or_general_semantic_review
not_human_approval_policy_or_security_audit
context_and_impact_are_current_state_read_only_projections
memory_ownership_target_artifact_and_unsafe_sections_are_not_analyzed

Each then appends the same exact ordered eleven strings:

no_generic_cross_file_composition
automatic_target_identity_is_revision_scoped_not_persistent_patch_address
no_cross_file_resource_interface_ownership_borrowing_or_lifetime_composition
no_reexport_wildcard_implicit_or_ambiguous_imports
no_target_codegen_artifact_project_test_or_execution
no_exclusive_lock_stage_publish_apply_or_commit_authority
not_proof_signature_provenance_approval_or_reusable_authorization
no_raw_working_tree_git_editor_or_unmanaged_file_analysis
no_incremental_cache_persistence_or_repository_index
no_recovery_rollback_cleanup_gc_or_durability_guarantee
no_external_consumer_compatibility

Authority and evidence status

Each operation validates scalar grammar before locking, holds one shared semantic-workspace authority through the retained graph build, traversal, canonical render, final held-object/inventory check, and checked unlock, and returns only owned JSON. Raw analysis and authority cannot escape. There is no write, stage, publish, apply, backend, runtime, parser, or verifier authority.

Local traversal, wire, digest, cap, mutation, API/CLI, and preservation gates are present. The frozen whole-document raw SHA-256 KATs are:

Artifact	SHA-256 wire value
Context forward	`sha256:95f5907e20d43a1edf6b560b257d2bbf6730b9ca80cb9a518949abd157e35c46`
Context reverse	`sha256:e804a4449365f25b5ca89ef7aee80cb3138a87c8ebd8fb0c4b42b8bb8000719d`
Context both	`sha256:056a3901e1f0424bc1334ddbebd64b90b9d518acad045c19f85648356ded82ae`
Context capability reverse	`sha256:9c79f1dcd1ad6f02cc967da4f88c32db36f32cd33df31e77350c5a36efa5b397`
Impact declaration	`sha256:b567e08854b592697dcde50ecbd43953cea46694805a1b4fecc38096cd9819c1`
Impact capability	`sha256:b595f0d93e3108f04b7d1eb2731a3048db64415ca69282635ca40abc9f165793`
Review	`sha256:7b2e5047397e6167c6e2622c725d771b8047b83bab82046c4ed262ef11f32769`

Exact-head release evidence is HOSTED GREEN for v0.4.0; this document makes no status promotion.