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.