C02.md

C02: passive sorting-source workflow

Introduced in 0.1.0.dev2; the commands and fields remain supported in 0.1.0. See INSTALL.md for current installation qualification. Examples below run from the repository root, or after exporting installed examples into an examples directory with structdet-code examples --output ./examples.

First run

Inspect the supplied example without writing anything:

python3 -m structdet_code inspect --study examples/static/study.json --format markdown
python3 -m structdet_code validate --study examples/static/study.json
python3 -m unittest discover -s tests -v

Prepare a new collection from the seven original project-owned example sources:

python3 -m structdet_code prepare --sources examples/minimal/sources --output /tmp/structdet-code-my-first-study --study-id my-first-study --data-role fixture
python3 -m structdet_code inspect --study /tmp/structdet-code-my-first-study/study.json --format markdown

Choose a new output directory if that path already exists. Preparation copies the selected source bytes and creates study.json plus an unfilled review.json. No model or candidate program runs. No test result, model identity, independent origin or successful generation is invented. snapshot marks a supplied standalone observation with unknown history. File ordering determines stable collection IDs, not chronology. Identical bytes at different selected paths remain separate slots, without a claim that they came from independent generations.

For your own collection, replace --sources and omit --data-role fixture. The default role is descriptive. Select one condition at a time; compatible cross-condition comparison is C03. By default only top-level .py files are selected. For explicit nested inputs:

python3 -m structdet_code prepare --sources /absolute/path/to/collection --include batch-a/one.py --include batch-b/two.py --output /absolute/path/to/new-study

Reading the result

The static example has seven project-owned files. Six are admitted: four insertion, one merge and one selection. The opaque sorted delegation stays unresolved. Coverage is 6/7. Admitted support is 3; SCI and Gini-Simpson are both 1/2, conditional on those six assignments. No test receipts are attached to this newly prepared study. All seven validity states are not_assessed; valid-classified SCI is undefined. The older examples/minimal study retains its actual C01 receipts.

Each source analysis has a digest, parsing state, bounded syntax observations, line spans, and a rule or review reason. Syntax observations can include inactive code; they do not independently establish reachability or mechanism membership. Public reports omit source bodies, filenames, identifier strings, reviewer notes, prompts and free-form logs. The private source bundle retains relative paths so a reviewer can open the artifact's file and locate the displayed lines.

Exact recognition scope

sorting-whole-module-alpha-ast/1 compares the entire parsed module with a project-owned reference examined against the task descriptors. It requires exact operative structure, not a similarity threshold or votes among feature counts. Constants and their types, operators, branches, calls, attributes, statement order and equality between binding names are retained. Comments, formatting, leading module/function docstrings and consistent bijective non-reserved identifier renaming can vary. sort_values and builtins retain their names.

The rule does not unify separate lexical scopes, prove general equivalence, discard dead code, reorder helpers or infer arbitrary control/data-flow equivalence. Even values[:] replacing list(values) can require review. Assumptions are the declared plain-list/plain-integer domain, ordinary Python builtins, the complete standalone module and no external rebinding or instrumentation. A source match does not prove a supplied execution used those conditions.

Rule	Mechanism evidence
sort-adj-sweep/1	Repeated adjacent compare/swap sweeps
sort-ins-shift-copy/1	Ordered-prefix insertion by predecessor shifts
sort-ins-shift-alias/1	Same insertion mechanism while reusing input, an interface defect
sort-sel-extract/1	Full remaining-pool scan and next-minimum extraction
sort-merge-halves/1	Recursively ordered halves and advancing-head merge
sort-pivot-three-way/1	Pivot-relative partitions and recursive strict partitions
sort-heap-max-extract/1	Binary max-heap restoration and repeated root extraction
sort-count-full-key/1	Full-key frequency accumulation and ordered reconstruction
sort-radix-lsd16/1	Stable, successive base-16 digit grouping

Reference source strings are in structdet_code/rules.py; the product parses them without execution. Changing operative references or normalization semantics requires new rule/scope identities. These nine narrow rules do not exhaust the eight families.

An import, opaque call, hybrid, extra branch, decorator, altered binding or uncovered implementation receives no partial reference match. The parser does not automatically prove that unmatched code is a hybrid; a review can record that reason with evidence. Unknowns remain outside hard counts, without an extra unknown mechanism class.

Review and apply

Open the copied source and corresponding review.json entry. Leave unchanged entries with decision: null. The suggested class is a hint, not a review decision. Do not alter source/study/task bindings or current-assignment IDs.

For a genuine supplied human review, fill the editable fields along these lines:

{
  "decision": "accepted",
  "basis": "human_review",
  "class_id": "SORT-INS",
  "reason": null,
  "reviewer_ref": "actual-reviewer-reference",
  "evidence": [
    {"start_line": 3, "end_line": 9, "note": "Describe the actual operative structure here."}
  ],
  "note": "Optional review context"
}

This shows only the editable portion, not a completed review. Use actual in-range lines and a real reviewer reference. The software cannot authenticate that reviewer or their judgment. Host-AI output uses basis: model_assisted, decision: proposed, a candidate class and a reason such as not_reviewed; it stays outside admitted counts.

Use unresolved or conflicted with class_id: null and a specific reason: insufficient_evidence, unsupported_syntax, opaque_dependency, unresolved_reachability, hybrid, schema_gap, review_disagreement, not_reviewed. Under static_or_reviewed, an accepted human label contradicting an exact rule is refused. Preserve it as conflicted pending resolution; no majority vote resolves it.

After filling the template, write a new manifest in the same study directory:

python3 -m structdet_code apply-review --study /tmp/structdet-code-my-first-study/study.json --review /tmp/structdet-code-my-first-study/review.json --output /tmp/structdet-code-my-first-study/reviewed.json
python3 -m structdet_code inspect --study /tmp/structdet-code-my-first-study/reviewed.json --format markdown

The import binds to exact source/study/task bytes and current assignment IDs. It appends review revisions, preserves old records and explicitly updates selected assignments for reviewed artifacts. Code ordinals, sources, population size and test receipts stay unchanged. Reviews do not create model generations. Blank templates, stale bindings, invalid anchors and attempted overwrites are errors. For a later review round, create a fresh template first:

python3 -m structdet_code review-template --study /tmp/structdet-code-my-first-study/reviewed.json --output /tmp/structdet-code-my-first-study/next-review.json

reviewed_import studies also support review import. C01 fixture-only studies keep their stipulated-evidence policy and are not silently converted. New preparations use study schema 0.2; original C01 schema 0.1 stays readable with its original rules.

Resource and execution boundaries

Intake retains the C01 256 KiB/source, 1 MiB/JSON, 4 MiB total-read and 128-source limits. Default discovery scans at most 4096 directory entries; explicit includes can address larger directories. Symlinks, traversal, nonregular/missing files fail. Automatic parsing separately limits sources to 64 KiB, 4096 lexical tokens, 4096 AST nodes and depth 64. Invalid syntax and parser resource refusal are explicit unresolved states. Up to 32 syntax findings per source are shown, with an omitted count; recognized rules have up to eight evidence spans. These bounds do not constitute a sandbox or authorize executing untrusted code.

Tests execute only nine reviewed project-owned reference strings, using 126 finite cases each. Imported programs are never executed by any command. No repository hooks, user-selected validators, live models or external services are invoked.

The designed 37-case classification corpus has 27 assignments, 0 false assignments and 10 abstentions, including four known mechanisms beyond the exact rule subset. Coverage is 27/37; conditional accuracy is 27/27 on this fixture corpus. References and presentation variants are included. This verifies software behavior, not independent holdout performance or arbitrary-code generalization.

Implementation references: Python 3.12 AST documentation and tokenizer documentation. Parser success alone does not prove source validity or task conformance.