ARCADIA-Studio/harness/ordinary-source8-design-20260925/ADOPTION-MAP.md

# Public source8 adoption map — read-only proposal

Source `edf096cd33350865ecfc3c65ec266a6c0d3c4000`; parent reports final 11 new
passes, full 276/16 and strict Clippy, with evidence audit pending. This map does
not activate anything or change #7/user requirements. PROJECT_GOAL.md:64–71,83,96
requires full graphical/text parity, understandable versionable text, calculations,
API editing and text-only model development. Private rename acceptance is a useful
foundation, not satisfaction of those requirements. No Gitea issue reread/write
was attempted under the existing publication blocker; parent owns #7 coordination.

## Current concrete seams (repository-relative source paths)

- `crates/oa-core/src/language.rs:8` gates the whole analysis_source module with
  cfg(test). Parser mixed state/hooks at1218+ are independently cfg(test), too;
  removing only the top-level gate is insufficient. Keep fixture constructors
  and tests gated when promoting the actual production path.
- `language::{parse,parse_limited,parse_with_report_limited}` at343–355 reaches
  parse_document and old Parser::document. Parser::unit at1551 rejects8 on the
  ordinary public path (accepts3–7); ordinary conversion at1862 rejects analysis
  records. Merely permitting header8 cannot parse/lower typed declarations.
- `language/analysis_source/mixed::{parse,parse_impl}` already constructs a whole
  bundle witness; `mixed/project::resolve` admits complete Project and maps
  diagnostics. Current mixed syntax requires explicit ordinary/typed/parameter
  IDs. Its borrowed input lifetime is fine for a read that moves out an admitted
  Project/warnings and drops syntax before returning; AcceptedRename is not needed
  to authenticate an arbitrary initial read, nor should it gain a tuple constructor.
- `source_project::{inspect_includes,compile_bundle}` at207/287 uses parse_unit
  and compile_once, stabilizes missing IDs, reparses actual changed bytes, then
  upgrades older source. Its public CompiledSourceProject at111 owns bundle,
  DecodeResult, SourceIndex and diagnostics. SourceIndex at94+ covers declaration
  headers/bodies, lexical owners, fields/includes/project sites, not the complete
  typed/scoped occurrence authority of the private index.
- `language::{format,format_declarations}` at505/522 emits schema8 but does not
  iterate definitions; analysis elements still pass through ordinary payload
  writing. Private `analysis_source/write::Writer::{definition,analysis_element,
  typed_declarations}` at427/518/626 already writes typed fragments with limits,
  but no complete public composition calls it. This is a real separate writer
  integration obligation, not something a parser dispatch switch repairs.
- `source_project::{update_bundle,update_bundle_with_identity_map}` at619/640
  recompiles current bytes and compares model/index/bundle to reject stale public
  structs, handles structural/identity intent, then recompiles output and compares
  the entire target at876+. Its category/ownership/field editing is broader than
  alias-only RenamePlan and must not silently route unsupported edits to renaming.
- `mixed/.../rename/emission/acceptance::AcceptedRename` now owns actual verified
  bytes/model/warnings/exact policy/final storage. It has immutable access only,
  no SourceIndex or borrowable admitted syntax. Changed emission rejects any
  carried syntax, so it is deliberately not a repeated-owned-edit capability.
- `oa-server/src/store.rs::PreparedProject` at114–168 compiles formatted models,
  updates source with prepared identity maps, and compares generated model. It
  requires CompiledSourceProject, not AcceptedRename. Desktop `document.rs:121`
  compiles initial bundles; apply_compiled at323 rechecks bytes/model/index before
  history commit. Its saved receipt and undo/redo preserve exact source snapshots.
  source_workspace.rs:365 also requires public complete bundle compilation.
- `persistence.rs::save_checked_profile_with_source` at961 emits final bytes,
  calls public decode under byte policy, checks whole Project/no migration before
  any temp file, then performs expected-byte conflict check and persist. Its
  source path uses language::format, so public reader AND complete writer are
  necessary for useful checked save. Private rename verify must not replace that
  final-byte/storage transaction check or bypass source/JSON version dispatch.

## Candidate comparison and smallest useful next outcome

**A — public read/admission first (recommended).** Promote a narrow real mixed
read route into the existing public single-source decode dispatch, preserving
3–7 migration and unsupported-version behavior. Map actual source8 diagnostics,
return schema8/no migration, move the actual admitted model, and preserve exact
caller limits. Existing source8 read failures become specific acceptance targets.
This can deliver useful import/validation/API decode without inventing another
owned rename constructor. It does not alone claim editing, formatting or save.

The next coherent slice after that is complete typed+ordinary canonical writing
and its public actual-output decode/equality round trip, reusing the typed Writer
and existing ordinary writer instead of a new serializer. This directly enables
checked-save acceptance with the existing pre-temp-file containment. Public API
shape needs a decision: current format returns String and cannot report bounded
writer refusal; a checked internal/public formatting result can serve save while
compatibility of the existing convenience formatter is explicitly maintained.
Do not hide writer refusal behind an empty/lossy document or an unconditional panic.

Bundle/editor adoption then needs one deliberate source8 CompiledSourceProject
projection (or a narrowly selected successor type) for actual returned bytes,
including typed declarations/fields and qualified parameter ownership. No fake
empty SourceIndex or lowering of typed records through old ordinary conversion.
Preserve missing-ID stabilization, include discovery, field diagnostics and
identity-map semantics through explicitly selected integration, not ad hoc adapters.

**B — repeated-owned rename/adoption first.** Requires borrowing/reindexing the
accepted bundle while its O+warnings remain live, defining another consumed
emission transition that does not drop externally owned carry, handling no-op,
and coherent document/history installation. It also needs public dispatch/index
bridges before existing callers can consume it. It proves a second private rename
but leaves public read/writer/checked-save gaps. Choose it first only for a real
consumer explicitly needing repeated immutable-source rename; no such consumer
is exposed by the current caller graph. This is avoidable as a prerequisite to A.

## Decisions and finite acceptance

1. Decide initial public source8 identity policy: reject missing IDs explicitly,
   or integrate the existing stabilization promise with actual-byte reparse.
   Private explicit-ID admission cannot silently redefine compile_bundle's public
   behavior. Qualified parameter IDs/scopes require special attention.
2. Decide source8 caller resource policy and the read result/diagnostic adapter;
   reuse named logical-domain bounds without claiming process-memory containment.
   Avoid rescanning all text just to dispatch; share the established header/token
   decision where possible without feeding already charged work twice.
3. Gate public reader with full mixed OA/SA/included-file cases, historical UUID,
   scoped/global aliases, exact numeric values and invalid/overbudget sources.
   Preserve legacy migration reports, warnings/source spans and input immutability.
   Sixteen currently expected public failures are obligations to inspect and
   intentionally resolve by behavior, never rename away or simply update baselines.
4. Gate writer/save with entire Project equality for every typed root and ordinary
   carrier, all-file/UTF8/CRLF ownership where applicable, malformed/lossy output
   refusal before temp creation, conflict preservation and actual saved receipts.
   Keep allocation/diagnostic limits and old failure records visible.
5. Alias-only public editing can reuse sealed mixed plan/emit/verify once caller
   adaptation is selected. Reject other changes precisely until structural source8
   editing and identity-map transfers are implemented; do not claim UI/API parity.
   Existing command/history atomicity, stale index rejection, whole-result equality,
   warning-to-byte identity and detached invalid drafts remain mandatory.

No extra universal allocator framework, second serde/numeric parser, generic
legacy Index adapter, repeated-owned rename loop or extra fixture-only checkpoint
is intrinsically required before public read integration. Real missing work is
production gating, dispatch/identity policy, public result/index projection and
complete writer/update composition; these cannot be skipped by exposing private
AcceptedRename alone.

`persistence/json_codec.rs:22` keeps DEPTH_128_VALIDATED=false pending its explicit
Windows/Linux debug/release codec and ordinary-lifecycle gates. Private128KiB
success and current acceptance runs do not flip that switch, prove native-stack
bounds, rerun the old full-pipeline setup limitation or waive the public checked-
save depth regression. Preserve the historical source-header failure and the
unreached JSON iteration until their intended complete public path is tested.

## Supplement: ordinary current-schema compatibility first

Independent code assessment, then compared with ADOPTION-CRITIQUE.md: I agree
this is a smaller useful next outcome than my earlier recommendation of public
mixed read first. The earlier map did not separate the already-supported ordinary
language from typed source8 syntax sharply enough. The public ordinary writer
already labels every current model8; the public ordinary parser's header list
alone prevents its existing ordinary constructors from receiving those documents.
Restoring that specific path is a compatibility repair, not a mixed analysis adapter.

Concrete safety basis: Parser::unit at language.rs:1541 selects private mixed8
separately from ordinary3–7. construct_declarations rejects every Kind::is_analysis
at1862. Short typed declaration words are absent from ordinary declaration_kind
at236; definitions have no ordinary constructor. finish_declarations at2107
migrates only4..=7, while its existing following branch checks model limits and
returns migration=None for current8. Thus there is no need to route schema8 through
migrate_v7 or remove the deliberate analysis-record rejection. Public parse and
compile still apply full existing model validation, include traversal and limits.
Source migration already writes the current version then recompiles; ordinary8
acceptance fixes that coherence too, including actual returned-byte indexing.

Counterarguments/conditions: this must not be advertised as complete source8 or
as fixing public formatter omission of definitions. A Project containing analysis
definitions still cannot be losslessly exported by language::format; checked-save
must continue comparing the whole intended Project and refusing lossy output
before filesystem staging. Explicit rejection of both long analysis-record words
and short typed definitions/records must be exercised, not assumed from one token
example. Include fragments use the same public ordinary grammar, so rejection and
no-partial-result behavior must hold in non-entry files too. No mixed cfg gates,
private ownership APIs, public index shape or user requirements need changing.
The historical report's 'whitelist-only patch is insufficient' remains true for
*complete analysis/source8 preservation*; this deliberately smaller compatibility
milestone must explicitly leave that obligation open, rather than rewrite it.

Finite candidate acceptance: direct current ordinary format→parse and modular
format→compile→compile whole-model/bytes/index checks, no migration on8; existing
3–7 migration reports and actual upgraded8 bytes; omitted-ID stabilization and
nested lexical ownership; ordinary OA/SA, diagrams/history/artifacts/traces,
Unicode/CRLF/comment retention; full malformed/future-version refusal. Run all16
currently header-blocked library cases and their intended transaction/nesting
assertions to completion, without assuming all will now pass. Add negative
analysis-bearing read/import and genuine generated-lossy checked-save controls.
Exercise real non-test CLI check/rename-preview plus existing source project,
identity-map, migration, source_files disk transactions and desktop/server build
seams proportionately. Existing validation/stale/model-equality guards stay intact.

This also exposes previously hidden persistence work. The exact historical
review_regressions::checked_save_returns_exact_bytes_and_accepts_unchanged_external_content
loop runs .arcadia before .oa.json: once ordinary8 save/reopen succeeds, its repeated
save and ordinary JSON iteration finally execute. Conflict siblings and
language::coordinate_bits_and_permitted_strings_survive_text_and_storage likewise
exercise real later branches. Any new failure is new evidence, not permission to
loosen equality/limits or call the earlier failure solved without completing them.
These are ordinary-model JSON checks, **not depth128 qualification**. The private
JSON depth driver and production_save_always_reopens_with_its_reader_profile have
separate paths; DEPTH_128_VALIDATED remains false and its Windows/Linux debug/release
requirements remain unchanged. Ordinary8 compatibility may remove one prerequisite
blocker but cannot manufacture the still-missing platform/depth evidence.

Revised ordering recommendation: select bounded ordinary8 compatibility first;
then choose an explicit mixed check/lint or mixed read milestone with identity and
loader-discovery policy; complete typed writing and structural/adoption interfaces
remain required thereafter. Repeated-owned rename is still not a prerequisite.
No implementation, test execution or contract change is authorized by this map.