Skip to main content

OMI Studio 1.0 Refactoring and PR Plan

Research-project contract reconciliation — 2026-11-15​

Extend A02/A04/A06/B06 and ADR-008/022/036 work: pin the canonical project envelope/schema/golden, generate native-CSP-safe validation, and test independent JSON consumption plus legacy migration and metadata retention. First implement project cache ownership and explicit open/add operations; only then add direct-transfer/provider conflict adapters and reviewed public projection with separate capability evidence. No Stable promotion or existing release-gate waiver.

Status: proposed coordinated repair pending companion merges/CI; deployment and provider acceptance remain separate. No manuscript/container generation change or database migration.

Contract, compatibility and current implementation.

Text-box and research provenance — 2026-11-13​

A02–A06/B06: reconcile canonical Draft schema, pin bytes/checksums, generate profile validation and verify legacy/future recovery plus DOCX/JSON/container round-trips. C11/ADR-022/023: use reviewed snapshot contribution with atomic provenance/history and privacy filtering. Keep the existing OMI-SPEC-320 exact-candidate gate mandatory; coordinate OMI and Studio changes before rollout.

Status: proposed coordinated repair; merge/CI and deployment acceptance remain separate. No database migration, container-generation change or new review authority.

Profile, decision and acceptance scope.

Privacy/API boundary repair — 2026-11-08​

Apply A09/A10 to the new privacy/account-copy surface: introduce additive v1 and shared legacy mounts, derive OpenAPI/client types from strict Zod DTOs, standardize read errors/correlation, and inject a repository port between application export scope and identity Prisma. Preserve session admission, explicit selection, collection caps, optional-role migration compatibility and the partial-export disclosure.

Required checks: npm run test:privacy, server/frontend builds, optional-role authentication/projection regression and privacy browser tests. The existing CI privacy step includes DTO/OpenAPI parity, alias quota/isolation/error coverage and native-origin checks; it does not create a weaker parallel release path. Keep exact-candidate and manual operator acceptance gates. Deploy API → web/native clients; compatibility paths stay until a reviewed removal policy. No new migration or authoring lock is needed.

Companion source and this reconciliation remain proposed until merged and verified. Do not replace missing operator facts with invented data or call the partial account overview a complete rights export.

Studio ADR-034; Studio PR #886.

PKP support and release evidence — 2026-11-07​

OJS 3.5.0-4/-5/-6 are in the Stable acceptance scope; OMP 3.5.0-4/-5/-6 remain Preview. All six named E02 jobs/archives are mandatory regression evidence. Add ojs-3.5.0-6 to the current v1 receipt (14 manual gates); preserve historical 13-gate receipts without treating them as approval for the expanded scope.

Apply this evidence scope to C06–C09, D08 and E02–E05. Keep the original 54 units and dependency order. Current support decision.

Publication rendition boundary — 2026-11-04​

Keep the original 54 units. B01/B03/B07 cover application/session/history integration; B05/B06 still address the source ContentCodec, not removal of editable publication renditions. C03–C05 specify and test source-to-rendition mapping, immutable build inputs and loss reporting. C15/E03 cover exact-content assurance, privacy, explicit refresh/conflicts, recovery and performance. Documentation does not implement those behaviors or relax E02–E05.

Inspected source, decision and acceptance work.

Outbound security and acceptance checkpoint — 2026-11-02​

Retain the existing 54 A01–F03 units and dependencies. C12/C13 now characterize and harden the merged pinned transport rather than introduce a replacement. D-phase acceptance records the service-cgroup/shared-UID topology and separate PDF worker. E02 still requires exact-candidate workflow/artifact and owner/manual receipts; issue closure cannot replace them.

Current evidence authority: reviewed security/acceptance checkpoint. Its dated status supersedes older claims below that #765/#774 are open or that connection-time pinning has no implementation. Historical findings remain historical; closed issues do not supply missing RC receipts.

Historical checkpoint: 2026-11-01. Earlier checkpoints are historical where superseded. Proposed repairs require merge/CI; real acceptance remains separate.

Session, integration and release evidence reconciliation — 2026-11-01​

Reviewable repairs: Studio #813 · Studio #814 · Studio #815 · Studio #816 · Studio #817. During the repair, Studio #812 merged the E02 collector. #817 reuses that existing latest-attempt/same-SHA/job/archive gate (including OMI-SPEC-320 conformance), adds candidate-only build/review and binds actual publication bytes/manual receipt; it does not introduce a competing workflow inventory.

These bounded repairs supplement the existing 54-unit A–F plan without renumbering it. Preserve the editor, Yjs, immutable checkpoints and renderers.

Repair / phaseGoal / expected filesDependencyBlocking regressionBreaking / technical risk
R01 / DOpaque Office sandbox in EuroOfficeIsolatedFrame.tsx, server embed host and CSPExisting owner-scoped Office launchReal host/browser parent/storage/API denial and handshake; Windows/Android provider save/reopenAPI/native must roll out as a matching pair; medium technical / high unpatched security risk
R02 / BdocumentSessionManager.ts, Zustand session adapter, App.tsx, recovery; per-ID native locationsExisting store/history; independent from R01Two pending manuscripts, batched open, selection, checkpoint, recovery; actual mocked native A/B writesNo portable change; medium
R03 / CShared extension router, extensionRegistryService + repository, client v1 URLsExisting manifest schemav1/legacy validation, 401 and per-owner parityAdditive endpoint; low–medium
R04 / A+CManifest serialization profile; preserve exact historic snapshots; shared golden and spec implementation noteExisting 320/330 reader and v1 digest evidenceActual Studio reader + independent ZIP/CRC/SHA processing, historical digest preservation and unknown profile denialExperimental additive profile; medium; never silently migrate historical evidence
R05 / DProduction socket requirement; dedicated worker local executor and rollout guideExisting systemd socket implementationMissing/false opt-out production failure; no dispatch fallback; real host resource/secret/network acceptancePDF unavailable until service configured; medium
R06 / Erc-evidence.mjs, workflow dispatch evidence/prior-build inputs, exact artifact reuseExisting strict issue gate, all real acceptanceMissing/foreign SHA/run/gate/hash denial; exact prior platform build jobs and CI/CodeQL/PKP/readiness resultsBeta flow retained; high promotion-safety importance / medium technical
R07 / AFive EN/HU baselines, Studio ADR-030 and non-normative 330 profileR01–R06 concrete code and fixturesEN/HU docs, 54-unit roadmap contract and cross-repo fixture equalityNo schema/DB/release bump; low

Roll back ownership/API adapters independently; keep user files/recovery and exact history. Office rollback must use a matched secure API/native pair. Never restore remote main-WebView code, global save paths, production PDF fallback or a release bypass. Actual physical/provider/host evidence remains an owner acceptance step, not fabricated automation output.

Current reconciliation: 2026-11-01 — evidence-based implementation review. Earlier dated checkpoints remain historical where superseded. Proposed repairs require merge and CI; local evidence is not deployment acceptance.

2026-11-01 implementation plan reconciliation​

The dated cross-repository audit now distinguishes implemented, partially verified, staged and externally blocked work. The 54 planned unit identifiers are checked by the documentation CI, while Studio PR #811 adds the first A10 semantic-model dependency boundary only. #810 is merged, providing a strict manual RC red-gate and SHA publication approval; it does not deliver the full E02 same-SHA cross-workflow aggregator. Host deployment evidence for #765/#774, Linux GTK/glib #271, portable ContentCodec/AST, native SecureStorage, independent normative conformance and RC physical-device sign-off remain explicitly open. The original tables below are the planning baseline, not a declaration of current completion.

Draft translation, exchange and authority checkpoint — 2026-10-31​

These dependency-ordered units supplement B06/B07/C01–C05/C11/E02. Keep existing model functions, renderers, Yjs and revision history.

Unit / phaseGoal and filesPrerequisiteTestsBreaking / technical risk
T01 — immediate securityPublic-note filtering before translation HTML units/readiness in translationExport.ts; new privacy fixture, release-security import.Existing public-note predicateBoth HTML modes; hidden/editor/workflow/origin notes; late visibility edits; stale/new public notes; private edits do not block; original unchangedIntentional removal of private output; low technical / high unpatched privacy risk
T02 — B applicationtranslationCommands.ts port; keep app/translationActions.ts facade.Existing translation model/checkpoint ledger; can be reviewed after T01Plain session and actual store, pending events, source basis, save/reopen/revert and invalid command atomicityNo API/schema change; medium refactor risk
T03 — C exchangeApplication-owned ExportExchangeSession; migrate standard export panel's report lifecycle.Existing report/byte inspection serviceWarning preservation, actual digest, no completion before inspection, failure, cancellation; existing format/sidecar tests and buildLocal report contract unchanged; medium refactor risk
T04 — A documentationFive EN/HU baselines and Studio ADR-029; reconcile existing ADR-028 and new core-review evidence.T01–T03 concrete reviewable implementationEN/HU documentation builds; code/fixture/version traceabilityNo compatibility change; low risk
T05 — B/C later contractIntroduce registry/ports before migrating remaining importer/exporter callers; editor-independent translation anchors via explicitly versioned codec mapping.T02/T03; A06/B06 and normative profile decisionsAdapter parity, byte/fidelity diagnostics, unknown fields, shifted text paths, cross-editor round trips; separate migration PRPotential profile compatibility change; high risk; no silent locator reinterpretation
T06 — E acceptanceExisting collaboration reauthorization/reconnect and privacy gates, external interoperability and exact-candidate evidence.T01–T04 and other RC prerequisitesReal transport downgrade/revocation/unavailable authority, offline denial, anonymous cross-surface fixtures, approved profile/independent evidenceHigh promotion risk if missing; beta/local self-assessment is not certification

T01–T03 can be delivered as one bounded repair with separate commits, or independently in this order. Roll back adapter extraction independently; never restore private HTML leakage. Private-note review cannot become a condition for public proof output or an editor lock. No schema/container/DB migration is required. The current session-local receipts, complete target semantics/streaming and uninstrumented export routes remain declared follow-up scope.

Security boundary reconciliation — 2026-10-30​

This is a small extension to B09–B11/C12 and D/E security evidence, not a new prerequisite to rewrite authentication or PDF processing. Existing Studio security changes through 540f67a are retained.

Unit / phaseGoal, modules and expected filesPrerequisiteEvidenceChange / rollback risk
S01 — A/B reconciliationCorrect verified-email and central-auth descriptions; add docs/server/security-contract-rollout.md; two server contract test files, package script and CI/readiness invocation.Merged bootstrap, Origin and PDF hardening through #775Existing release-security suite; real HTTP Origin/session/parser tests and mocked-repository provisioning tests; server compileLow; no runtime contract/DB change. Roll back docs/tests independently without removing security controls
S02 — A freeze checkpointReconcile five baseline documents in EN/HU, ADR-012/015/016/017/019; distinguish implemented environment filtering from deployment sandbox guarantees.S01 reviewed; implementation facts independently verified on mainDocumentation/MDX link build; trace contracts to code and test namesLow; document repair, no compatibility promise for all legacy endpoints
S03 — D worker/egress hardeningSeparate PDF worker identity/container; credential-free mounts, CPU/RAM/pid/temp limits, network deny; connection-time destination controls (#774/#765). Expected deployment manifests plus existing PDF/network adapters and ops docs; select packaging for actual supported installations.S01 policy and operator deployment inventoryHost canary: deny credential-file/private/metadata access, cap resource abuse; permit approved integrations; fonts/media/rendering recovery on supported platformsHigh; can disrupt fonts/network/renderer availability. Controlled canary and reviewed secure artifact rollback; never restore blanket network/environment access
S04 — D capacity acceptanceShared atomic admission/lifecycle only if multi-instance PDF import is supported; otherwise explicitly scope deployment limitation. Expected PDF admission/job repository port and deployment configuration.S01; supported deployment topology decisionSimultaneous multi-process quota, release/expiry/restart and ownership testsMedium; contract/adapter first, migrate separately; do not imply current process map is distributed
S05 — E02 RC evidenceAttach security unit/HTTP, private grant review/recovery, browser/native/PKP and deployed isolation/egress results to candidate commit and artifact digest.S01–S03; S04 when applicable; existing E02 prerequisitesMandatory negative and positive acceptance, no private manuscript or credential data in Git/CIHigh promotion risk if missing; block promotion while retaining authoring and explicit beta status

S01's HTTP/provisioning suite is npm run test:security-boundary-contracts, run after backend dependencies and Prisma generation in CI/readiness; npm run test:release-security remains the fast unit gate. Actual host/IdP/database tests are not replaced by mocks. None of S01/S02 requires database migrations. Existing-grant review changes operational authorization only under existing admin safeguards; it must not restrict authors' manuscript editing.

Freeze requires documented cookie compatibility, exact native/PKP exceptions, matching verified-email authority, PDF status/limit semantics and an agreed deployment evidence owner. RC additionally requires successful security evidence; updating a baseline alone cannot satisfy E02.

Baseline: Studio eca2cf45762116e1c00a89b3397840ed89109511 and the audited 2026-09-19 OMI/PKP commits
Goal: reach 1.0.0-rc.1 and then 1.0.0 through small, independently testable, reversible pull requests.

The identifiers A01–F03 define 54 planned PR units. They are planning identifiers, not existing GitHub pull-request numbers.

1. Execution principles​

  1. Contract or adapter first, call-site migration second, legacy removal last.
  2. Each PR has one primary architectural change. Mechanical moves and semantic changes should not be mixed.
  3. High-risk refactoring begins with characterization or golden fixtures.
  4. During format migration, use dual-read/new-write or shadow validation; never silently convert in place.
  5. Legacy route/store facades remain until all known consumers have moved.
  6. A rollout flag is not a compatibility strategy. Format, identity, and security changes require explicit forward and rollback behaviour.
  7. Test data is synthetic, public, or explicitly created for testing. Private manuscript titles, author data, filenames, content, and local paths do not enter Git or CI logs.

2. Dependency overview​

flowchart TB
A["A: contracts and freeze"] --> B["B: core boundaries"]
A --> C["C: interoperability"]
B --> C
B --> D["D: platform hardening"]
C --> E["E: release candidate"]
D --> E
E --> F["F: 1.0 release"]

Within a phase, PR identifiers are arranged in dependency order. The register later in this document identifies work that can proceed in parallel.

3. Phase A — Architecture freeze​

Exit condition: accepted compatibility policy; candidate normative schema/container/content contracts; agreed direction for /api/v1 and connector contracts; dependency-boundary lint; stable/preview/deferred support matrix.

PRGoalPrerequisiteRequired evidenceRisk
A01Freeze stable/preview/deferred 1.0 scope and the independent version axes.—documentation links and support-matrix completenesslow
A02Harden current OMI 0.3 Draft conformance and pin the later immutable stable schema/release artifact.A01current fixtures plus negative/future fixtures and schema checksummedium
A03Vendor the released schema into Studio and introduce OmiEnvelopeClassifier/validator in shadow mode.A02checksum-drift, valid/invalid/future classificationmedium
A04Introduce explicit open policy and future-schema quarantine/read-only handling.A03major/minor/invalid/oversize fixtures; no overwrite; raw recoveryhigh
A05Add pre-save/export validation and unknown-extension preservation.A03, A04open→save semantic equality; invalid save blocked; unknown payload preservedhigh
A06Freeze the required OMI-SPEC-100 portable-content AST candidate and add ContentCodec.A01legacy text/current PM JSON → AST → PM golden fixtures; unknown-node diagnosticshigh
A07Freeze an OMI-SPEC-330 container manifest/path/checksum/security candidate derived from the working parser.A02, A03cross-repo golden containers and hostile/corrupt package fixtureshigh
A08Define common diagnostics, fidelity, validation, and provenance base contracts.A01serialization, stable codes, redactionlow
A09Create additive /api/v1 transport foundations with error/idempotency/correlation contracts.A01contract tests and middleware orderingmedium
A10Enforce dependency direction and compatibility re-export patterns.A03, A06, A09forbidden core→UI/editor/Prisma/network import fixtureslow

Phase blockers: no owner for the OMI schema release process; insufficiently concrete OMI-SPEC-100 content grammar; unresolved SPEC-330/implementation differences; undefined stable platform/export scope.

Drift repair sequence recorded 2026-10-10​

These are independent, reviewable changes against the current Studio main; their PR numbers are evidence of proposed work, not completion:

  1. #654: block IDML hidden/restricted annotation disclosure and verify public notes survive. Privacy gate for any IDML preview.
  2. #657: characterize the existing DOCX source-font mark through the inline adapter. Follow A06/B06 for a spec-approved AST field/extension and lossless corpus; do not freeze the mark as wire format.
  3. #656: move native detection/storage access behind a platform adapter. Follow B10 and D01 for secure native token storage and account/cache partition by origin.
  4. #655: run readiness on every main commit, publish main images in beta and commit channels. Follow E02 with the exact-commit cross-workflow aggregator before RC/stable image promotion. Existing latest install configurations need explicit migration.

The four PRs do not depend on one another. Merge only after each focused CI suite is green; verify #654's privacy regression before exporting synthetic self-origin documents. The content codec, secure storage, and exact-commit aggregator remain release blockers even if all four land.

4. Phase B — Core refactoring​

Exit condition: create/open/save and primary editing/history flows are behind the application facade; Tiptap boundary is explicit; portable/persistence/UI ownership is separated; native credentials are not stored in localStorage.

PRGoalPrerequisiteRequired evidenceRisk
B01Introduce application ports and a StudioApplication facade without changing current model behaviour.A10fake repository/clock/ID-generator testsmedium
B02Move document create/open/save/close/recover behind the facade.A04, A05, B01create/open/save/reopen; invalid/future; dirty-close matrixhigh
B03Split Zustand ownership into document projection, UI state, editor session, and persistence projection.B01, B02current suite plus selector/action characterizationhigh
B04Consolidate automatic checkpoint timers into one document-scoped scheduler.B03fake-clock close/switch/reopen; no duplicate commitmedium
B05Route every Tiptap-content reader/writer through ContentCodec.A06, B01existing editor/export golden diffs and corrupt-node diagnosticshigh
B06Make new saves use the portable OMI AST; treat the pre-stable Tiptap-string form only as explicit import.A05, B05AST round-trip; experimental legacy import; future-major quarantinehigh
B07Add RevisionRepository using the current full-snapshot algorithm as the first adapter.B01, B06history/revert/integrity across adaptersmedium
B08Add crash-safe atomic save/recovery journal and opaque DocumentLocation.B02, B07fault injection at write stages; backup restore; digest conflicthigh
B09Formalize identity DB authority and the main-DB StudioPrincipal projection.A09migration rollback, idempotent ensure, drift/reconcile, auth flowshigh
B10Add platform SecureStorage and migrate native bearer tokens.B01upgrade migration, logout/revoke, absence from localStoragehigh
B11Separate account, auth identity, scholarly agent, contribution, and evidence mapping.B09no implicit email/ORCID merge; verified link/revokehigh
B12Replace string-offset proofing/tracked changes with stable-anchor/semantic-operation representation behind an adapter.B05, B06concurrent edits, Unicode/graphemes, accept/reject round triphigh
B13Remove or isolate orphaned alpha workspace state and empty domain placeholders.A10, B03, usage auditbuild/tests and no active referenceslow

B03, B05, B06, B08, and B09 deliberately remain separate rollback domains. Store ownership, file-format writing, persistence safety, and identity authority must not be changed in one PR.

5. Phase C — Interoperability hardening​

Exit condition: common importer, renderer, connector, and review contracts; OJS and OMP satisfy one connector suite; publication artifacts are reproducible and validated; schema/container conformance is mandatory.

PRGoalPrerequisiteRequired evidenceRisk
C01Introduce an Importer registry with source/probe/progress/abort/diagnostics/fidelity contracts.A08, B01, B06fake importer, ambiguity/probe, abort, redaction, no mutation before commitmedium
C02Wrap OMI/DOCX/PDF/HTML/table/image/music/reference importers and fix MIDI routing.C01per-format golden fixtures, .mid/.midi, quotas/cancel/hostile corpushigh
C03Introduce Renderer registry and separate ArtifactDeliveryPort.A08, B05, B06every exporter through wrapper; delivery fake; no picker in rendererhigh
C04Remove publication-profile module augmentation from the manuscript model and build immutable RenderingContext.C03embedded-profile dual read, profile version, context goldenhigh
C05Pin renderer/validator/font/resource versions and distinguish semantic from byte reproducibility.C04repeated-build hashes, font substitution, locale/timezone, signature cross-runtimehigh
C06Create common Publishing System Connector schemas for capability/launch/submission/review/writeback receipts.A08, A09shared JSON contract fixtures across Studio/OJS/OMPhigh
C07Adapt the OJS client and plugin to the common connector API while retaining compatibility routes.C06supported OJS Docker E2E; replay/scope/files/forms/recommendations/artifactshigh
C08Adapt the OMP client and plugin to the common API with monograph/chapter extensions.C06OMP Docker E2E; assigned-chapter confinement; rounds/stage fileshigh
C09Introduce durable outbox/idempotent saga for submission, revision, review, and artifact writeback.C07, C08, B09timeout/duplicate/retry/crash, receipt reconciliation, no false rollbackhigh
C10Extract publishing-system-neutral review domain and harden anonymous projection.B11, C06role transition matrix, identity-leak corpus, EXIF/SVG, cache/log redactionhigh
C11Introduce server-issued ExecutionGrant for integrations, AI, translation, and reference managers.B09, B11, A09denied scope, selection-only payload, confidential review, expiry/replay, audit digestshigh
C12Consolidate credential storage and wrap Zotero/Mendeley/ORCID/OIDC/provider secrets consistently.B09, C11dual-read migration, encryption/key rotation, revoke, no secret logshigh
C13Adapt cloud storage to one remote object-store contract with ETag/conflict receipts.B08, C11SSRF redirects, ETag conflict, checksums, refresh, large/resumable behaviourmedium
C14Promote only proven export formats to stable; expose other formats as preview capabilities.C03–C05JATS/HTML/DOCX/PDF gates; preview-format smoke; runtime capability UIlow
C15Harden native editorial acceptance and reviewed/unreviewed web artifacts without giving websites workflow authority; add DNS-verified publication-venue authority with separate domain-admin and editor roles. Files: web artifact service/UI, editorial decision and venue-authority services, identity/application Prisma migrations, /api/v1/publications/web, venue authority API, WordPress/generic adapter, docs.C03–C05, C09–C11exact-revision/content evidence, DNS challenge/revalidation, domain-admin delegation/last-admin protection, editor grant/revoke/concurrency, hidden/false/missing seal, privacy, scoped grants, idempotency, target-version changes, dual transport digests, both PostgreSQL migrations, receiver E2E, timeout/crash/retry/reconcile, accessibilityhigh

C15 is a Preview API/DB extension (ADR-021), not a stable-delivery promotion. Scope delivery to existing renderers/adapters. Keep source-state updates synchronous and bind evidence before computing the approved artifact hash. Split contract/characterization, native acceptance, outbox/delivery and receiver/recovery gates into separately reviewable commits or follow-up PRs. A feature flag may disable new delivery while preserving workflow records; do not drop decision/outbox tables during rollback. False assurance, reviewer leaks and data loss remain blockers even for Preview.

Phase blockers: unavailable test images for supported PKP versions; font licensing that prevents reproducible resource bundling; no selected JATS/profile requirement; no clear owner of the common connector DTO.

6. Phase D — Platform hardening​

Exit condition: every stable platform uses the same core/application suites; platform-port contracts pass; performance and accessibility budgets are agreed.

PRGoalPrerequisiteRequired evidenceRisk
D01Introduce complete platform port set: picker/filesystem/secure storage/auth handoff/updater/fonts/share/notifications.B08, B10, C03contract fakes, web/Tauri adapter tests, forbidden direct-import linthigh
D02Harden web file/session/recovery and PWA/browser fallbacks.D01Chrome/Firefox/WebKit open/edit/save/reopen, quota, denied permission, offlinemedium
D03Harden Windows/Linux/macOS Tauri artifacts and update flow.D01install, open-with, atomic save, update/rollback, signed artifacthigh
D04Harden Android SAF/auth/update/process-death behaviour.D01Android 10+ persisted permissions, large files, process death, updatehigh
D05Complete iOS/iPadOS preview adapters without stable promotion.D01simulator/device smoke, Files permission, background/resume, privacymedium
D06Set performance budgets and improve main-chunk/editor/renderer lazy loading.B03, B05, C0310k/120k/500k benchmarks, heap/editor count, bundle budgetmedium
D07Make critical accessibility journeys release-blocking.B03, D02keyboard-only create/edit/review/export, axe, screen-reader smoke, zoom/contrastmedium
D08Publish stable/preview platform capability manifest and runtime display.D02–D07artifact capability snapshot and documentation/runtime equalitylow

7. Phase E — Release Candidate​

Exit condition: 1.0.0-rc.1 artifacts produced from one commit; every mandatory gate green; no P0/P1 data-loss/security/anonymity blocker; acceptance report completed.

PRGoalPrerequisiteRequired evidenceRisk
E01Build common hostile-input/security corpus and fuzz harness.A04, A07, C02, C10ZIP bombs/traversal, XXE/entities, SVG/script, SSRF, malformed JSON, log redactionhigh
E02Create exact-commit RC aggregator workflow with no path filters.all A–D gatesfull matrix and artifact/SBOM/provenance hashesmedium
E03Run synthetic/public acceptance corpus and local-only private acceptance protocol.C14, D08, E01format/platform journeys; only content-free private metrics/results leave the devicemedium
E04Freeze API/schema/container/connector compatibility baseline and generate release documentation.E02, E03breaking-diff detector, documentation links, fixture checksumshigh
E05Build and test 1.0.0-rc.1 artifacts.E02–E04exact-tag mandatory gates, install/update/rollback, signatureshigh

RC soak and exit​

  • Use a predetermined soak period on every stable platform.
  • Any P0/P1 defect requires a new RC.
  • No waiver is permitted for data loss, credential leakage, anonymity breach, schema corruption, or signature mismatch.
  • P2 may remain only with an owner and documented workaround when it does not violate a stable contract.
  • Private acceptance manuscripts remain local. CI/Git receives only content-free metrics and synthetic minimal reproducers.

8. Phase F — 1.0 release​

PRGoalPrerequisiteRequired evidenceRisk
F01Promote the last unchanged RC commit to 1.0.0.signed RC exitartifact identity or justified reproducible rebuildlow
F02Publish support/deprecation/security-response channels and compatibility fixture package.F01public links/checksums/install smokelow
F03Open the 1.0.x hardening milestone for compatible changes only.F01issue-template policylow

1.0.0 must not contain a functional fix that was not in the final RC. Any code change requires another RC.

9. Dependency register​

PRDirect dependencyUseful parallelism
A01——
A02A01A08, A09
A03A02A06, A08, A09
A04A03A06, A07
A05A03, A04A07–A10
A06A01A02–A05, A08–A10
A07A02, A03A04–A06, A08–A10
A08A01A02–A07, A09–A10
A09A01A02–A08
A10A03, A06, A09—
B01A10—
B02A04, A05, B01B09
B03B01, B02B09, B10
B04B03B05, B09–B11
B05A06, B01B09–B11
B06A05, B05B09–B11
B07B01, B06B09–B11
B08B02, B07B09–B12
B09A09B02–B08
B10B01B03–B09
B11B09B03–B08, B10
B12B05, B06B07–B11
B13A10, B03B04–B12
C01A08, B01, B06C06
C02C01C03, C06
C03A08, B05, B06C01, C06
C04C03C01–C02, C06
C05C04C06–C08
C06A08, A09C01–C05
C07C06C08, C10
C08C06C07, C10
C09C07, C08, B09C10–C14
C10B11, C06C07–C09
C11B09, B11, A09C07–C10
C12B09, C11C09–C10, C13–C14
C13B08, C11C09–C12, C14
C14C03–C05C09–C13
C15C03–C05, C09–C11C12–C14
D01B08, B10, C03—
D02–D05D01one another
D06B03, B05, C03D02–D05, D07
D07B03, D02D03–D06
D08D02–D07—
E01A04, A07, C02, C10Phase D
E02all A–D gatesE01 and E03 preparation
E03C14, D08, E01E02
E04E02, E03—
E05E02–E04—
F01RC exit—
F02F01F03 preparation
F03F01—

10. Why the larger refactors are justified​

RefactorWhy a small patch is insufficientWhy a rewrite is unnecessary
Tiptap ↔ OMI content boundaryindependent consumers parse the same serialized representationkeep editor/extensions/parsers, place them behind one codec
Zustand/application splitglobal store ownership prevents platform-independent testing and mixes timers/persistence/UIcharacterize actions, then delegate incrementally; selectors remain
history repositoryfull snapshots scale poorly and history is duplicatedkeep revision IDs, semantics, revert, integrity; change storage behind port later
identity authoritytwo schemas contain overlapping user/session/identity conceptskeep working identity DB and bridge; add projection/reconciliation
common connector APIparallel OJS/OMP DTOs multiply with every new publishing systemkeep both clients/plugins as adapters
review projectionanonymity is a security boundary, not a UI preferencekeep server allowlist/sanitizer and strengthen it with contracts/corpus

11. Rollback strategy​

  • Schema/open: A03 shadow validation is independently reversible. After A04, the old parser is only an explicit legacy-import path. Newer saved formats are never silently downgraded.
  • Content AST: B05 keeps the wire representation unchanged while consumers move behind the codec. B06 changes the writer generation. Rollback treats new files as read-only/recovery input rather than overwriting them with an older writer.
  • Store: compatibility selectors/actions preserve UI while slices delegate to application services.
  • Database/identity: expand → migrate → contract. Additive/nullable fields first, dual-read and reconciliation second, destructive cleanup last. Every migration requires tested restore/down procedure.
  • Connector/outbox: adapters may be selected by controlled rollout, but queued outbox intent must never be lost. Rollback workers must understand both active payload generations during transition.
  • Platform: adapter selection occurs at composition roots. A legacy adapter remains only while it still satisfies the current security policy.

12. Milestones​

MilestoneIncludesExit artifact
1.0-architecture-freezeA01–A10accepted/deferred ADRs and pinned schema/container/content/API candidates
1.0-core-boundariesB01–B13application facade, portable content, persistence/history/identity boundaries
1.0-interoperabilityC01–C15common import/render/connector/review/web-assurance contracts and evidence
1.0-platform-hardeningD01–D08stable platform matrix and budgets
1.0-rc.1E01–E05signed exact-commit RC plus evidence manifest
1.0.0F01–F03unchanged promoted RC plus public compatibility/support policy

13. Minimum issue/PR template​

Each architecture migration PR should state:

  • contract/ADR reference;
  • dependency boundary before and after;
  • preserved current behaviour and intentional behaviour change;
  • affected stable/preview capability;
  • synthetic/public fixture reference;
  • rollback trigger and data-compatibility note;
  • test evidence plus performance/security impact;
  • documentation/specification mismatch closed or intentionally left open.

This decomposition is intentionally conservative. The 1.0 programme should optimize for reversible convergence on explicit contracts, not for the visual neatness of one large refactor.

2026-10-09 dependency update​

  1. Privacy containment — Studio PR #630. Remove implicit module workspace reads from the manuscript insertion panel; retain title/description insertion. Gate on a regression check and build. Roll back only if an explicit, reviewed alternative protects the confidentiality boundary.
  2. Module project contract (new PR, after containment). Inventory localStorage/IndexedDB keys and import/export consumers; characterize synthetic private-record and quota-failure fixtures. Define versioned project JSON distinct from OMI-SPEC-320. No old project data is silently rewritten.
  3. Workspace repository port (small PRs, after contract). Expose load/save/export and recoverable error states; migrate statistical IndexedDB and then other modules without changing manuscript semantics. Verify reload, quota/unavailable-storage, import validation, and native/browser delivery.
  4. Opt-in manuscript projection (after repository contract and ADR-022). Define typed allow-listed output and diagnostics, require a source record/citation or declared researcher-authored source, show the exact selected content and visible source and obtain explicit confirmation before a command inserts validated OMI blocks. Test missing-source rejection, source integrity, confidential transcript/participant fields excluded by default, plus undo/revision and export round-trip.
  5. Draft conformance to stable freeze (existing A02–A06 gates). Retain current 0.3 Draft validator and fixtures, pin source checksum, close requirement coverage and future-version behavior. Do not reintroduce experimental pre-stable migration work solely for compatibility.

The first item is an immediate security boundary correction. Items 2–4 are incremental follow-up PRs and must not be folded into a broad module rewrite.

Source attribution PR dependency (ADR-023)​

  • Visual imports: Studio PR #632 pairs each selected file/clipboard visual object with a reviewed visible source; test missing-source rejection and prefills. Independent of the module PR stack.
  • Bibliographic linkage: after ADR-001/004 schema decisions, add structured object→source links and renderer fidelity fixtures without recoding existing files silently.
  • Remaining ingress: characterize DOCX/PDF and HTML/JATS conversions, PKP intake, reference managers and asset transfer in separate PRs; decide source granularity per path before enforcing. Test metadata prefill, correction, anonymity, undo/round-trip and export formats. Keep OMI open semantics separate from external insertion.
  • Release gate: no universal-source claim until all supported external insertion paths have proven behavior and synthetic confidentiality fixtures. A successful visual-only PR is partial coverage.

Dependency update for external source rollout​

  • #632 (visual source pairing) and #635 (bibliographic review) are independent PRs.
  • #634 (DOCX/PDF source review) introduces a reusable document source notice; #636 (PKP source notice) depends on it and must pass OJS/OMP anonymity and real connector E2E.
  • #637 extends #631's researched, opt-in module projection to named safe fields; no automatic transcript or participant projection.
  • Follow-up: semantic OMI object/source link, renderer export fidelity, statistical IndexedDB adapter with privacy limits, and exact-commit gate evidence. Track in #633. Do not mark ADR-023 fully implemented from UI-only source text.

2026-10-11 merged-state reconciliation and remaining gates​

  1. Merged containment: retain #654–#657; their merged-commit checks passed. Do not reopen these fixes as absent implementation.
  2. Cross-format publication privacy — #662: depends on current main, modifies only a pure publication projection, eight renderer entry points and synthetic export fixtures. No portable schema/API change. Require existing unit/export, type/build and security checks. Rollback must preserve the privacy boundary rather than restore leaking output. Technical risk: medium; security impact: high.
  3. B10/D01 secure storage and origin isolation: separate platform PRs after a platform credential contract; characterize sign-out, origin change, restart, denied keystore, migration and cache ownership. Do not relabel localStorage as secure storage.
  4. E02 RC evidence aggregation: separate PR after gate inventory; require same-commit completed successful readiness, PKP, platform/installer and security evidence, artifact digests and receiver/recovery acceptance. Missing/skipped/stale evidence fails closed. Do not block ordinary beta publication by pretending it is RC promotion.
  5. A06/B05/B06 ContentCodec: keep existing source-font adapter while introducing characterization and a wire-preserving codec contract; only a later, explicitly reviewed writer-generation PR changes portable AST.

#662 and this documentation checkpoint are proposed until merged. Native secure storage, cache isolation, PDF binary acceptance and E02 remain release blockers, not completed work.

2026-10-12 current implementation checkpoint​

This checkpoint supersedes earlier dated implementation-state descriptions; it does not retrospectively change their audit evidence or declare architecture freeze. Studio main was verified at 6242dbae4e6e7be3f9bff9470f64647554f363d8; OMI at bc932272d0cbe18b8e45f758fbdb0d6076344bbf.

  • Studio now writes/validates OMI-SPEC-320@0.3.0 Draft with schema and omi.version, and retains the separately versioned container/history layers. Do not add a redundant schemaVersion field or promise pre-stable 0.2 migration. Stable compatibility obligations still begin with the first frozen stable generation.
  • OMI-SPEC-225@0.1.0 defines sourceAttributions: independently identified prov:wasDerivedFrom links to bibliographic records with explicit machine-inferred / author-declared / author-confirmed status. These are distinct from citation occurrences, technical import provenance, rights and authorship evidence. The model exists; universal ingress/export coverage does not.
  • Studio PR #674 proposes atomic source-relationship cleanup on block-subtree deletion, retaining unrelated relationships, bibliography records and prior revision snapshots. It also proposes explicit HTML/JATS source-attribution-not-preserved warnings. Until merged and verified, these are repairs under review, not main guarantees. The warnings disclose loss; they do not establish a lossless mapping or generate a citation/licence claim.
  • Mandatory regression evidence for this repair is actual insertion → checkpoint → subtree deletion → checkpoint → OMI save/reopen → historical revert, plus HTML/JATS per-relationship loss diagnostics and non-mutation. Fixtures must be synthetic/public. Broader deletion/merge paths, additional exporters, anonymous projection and OMI-container source-graph round trips remain separately assessed gates.
  • Preserve the working editor, snapshot history and renderers. Portable AST/ContentCodec, immutable schema provenance, unknown-field/future-version handling, secure native storage and exact-commit RC evidence remain prerequisites; 0.3 adoption is not 1.0 readiness.

Immediate dependency-aware repair sequence​

  1. R01 / Phase B — source graph lifecycle: #674; visual application action, source relationships, historical snapshots and lifecycle regression. Depends on merged #670 model; no schema change. Rollback is the repair commit; risk medium.
  2. R02 / Phase C — explicit HTML/JATS loss: #674 also contains the small shared diagnostic and renderer version increments. Depends on #670; tests cover per-relation warnings, clean documents and no portable-state mutation. Mapping is intentionally deferred; risk low.
  3. R03 / Phase A reconciliation — these five baseline documents: reference #674 as proposed until it merges; update current format to 0.3 Draft and close only the implemented portion of ADR-023. Documentation-only rollback; risk low.
  4. R04 / before RC: extend dependency lifecycle to other deletion/merge paths; add container and anonymous-projection source-graph cases and per-exporter mapping/loss gates. Preserve existing A02–A08/B05–B07/C03–C05/E02 prerequisites rather than reopening beta compatibility migrations.

R01/R02 are one reviewable targeted repair PR with separately tested concerns, not a broad architectural rewrite. No schema/API freeze or RC milestone is completed by their merge alone.

2026-10-13 — ODT Preview trust and fidelity checkpoint​

The earlier #674 source-lifecycle repair is merged at 5825c15a1bc3860a3371eaa1c20111bfe4b74ea5; its prior proposal checkpoint is historical.

ODT import/export entered Studio main in #675 (commit 5417e19cb26550508b66c780107eea87382b5f2f). It adds an interoperability format, not a new OMI schema, account authority or durable working-state format. ODT is Preview, pending independent ODF/office fidelity and real-document acceptance; it must not be promoted merely because the ZIP can be opened.

Studio #678 proposes targeted containment of two reproduced gaps. The import reader had trusted declared ZIP sizes and fully materialized DEFLATE output before checking it. The exporter omitted sourceAttributions without loss reporting. Treat #678 as a proposal until merge and verification, not a main guarantee.

The proposed boundary retains the 200 MiB input-package limit and enforces 25 MiB per expanded part, 100 MiB aggregate expanded data, and 4096 entries. Actual streamed bytes trigger cancellation before complete output materialization. Local/central headers, bounds, CRC32 and duplicate/unsafe/overlapping entries are checked; encryption, symlinks, ZIP64 and multidisk are explicitly unsupported. Successful repeated reads share the cached budget. CRC is integrity checking, not authenticity.

ODT uses the shared source-attribution-not-preserved diagnostic per unsupported relationship, alongside existing visible delivery warnings. A source label is not a semantic derivation link; no citation, licence or authorship claim is fabricated. Portable OMI retains the authoritative graph/history.

AreaDecision / release gate
ADR-008 / ADR-017 — importHARDEN the existing ODT adapter with real output-byte limits and ZIP integrity. Forged STORE/DEFLATE lengths, aggregate/entry quotas, CRC/header corruption, duplicate paths, truncation and ordinary data-descriptor compatibility are mandatory synthetic regression cases. Preview does not waive security gates.
ADR-008 / ADR-009 / ADR-023 — exportReport loss of every unsupported source relationship, with stable code and object target; preserve original portable state and keep diagnostic messages content-free. A later target mapping needs independent export/reimport proof.
ADR-019 — capabilityODT remains Preview with documented supported subset and losses. ODF schema/independent office acceptance and real-document fidelity gate Stable promotion.
PR planMerge/review #678 as the bounded incremental repair after #675; retain the working import projection and delivery paths. Then prove independent ODF validity and cross-office fidelity before any Stable claim. No beta-format migration or renderer rewrite is justified.

This checkpoint supplements the earlier format matrix and source-graph gates. The original schema/API/ContentCodec/native security/exact-commit RC prerequisites remain in force.

Architecture repair checkpoint — 2026-10-15: workspace mode and passkeys​

ADR-001/002/005: simple writing is a Studio workspace preference keyed by manuscript ID, persisted locally outside portable manuscript state and revision snapshots. New documents do not write editorMode; the Studio vendored 0.3 schema must match the OMI source artifact. Existing unknown fields remain preserved under the general round-trip policy; this repair does not silently delete an imported extension or reinterpret it as authorization. Moving a file to another installation does not transfer local writing-mode preferences. The simple visual editor remains available.

ADR-012/015/016/017: passkeys authenticate the existing local account; they do not establish scholarly identity or publication evidence. /api/v1/auth/passkeys is the client contract. /api/auth/passkeys remains a compatibility facade over the same handlers and rate limits. HTTP routes own transport/status/cookies, the passkey service owns WebAuthn use cases, and the repository adapter owns identity-database access. Challenges remain expiring and single-use; verification still binds RP, web origin, user handle and user verification. Credential material never enters OMI.

Support is web-origin only: platform-authenticator availability is checked behind a capability adapter. Tauri origins do not advertise this flow. Native promotion requires a verified browser/native handoff and contract tests; do not widen accepted origins to make native UI appear supported. PostgreSQL migration, real authenticator registration/login/revocation, negative origin/RP/signature cases and native handoff evidence remain release requirements, not claims established by mocked route tests.

Validation for the repair includes per-document workspace isolation, unchanged portable bytes/history, schema parity, native-origin capability rejection and v1/legacy route equivalence with replay rejection. This checkpoint records a proposed repair pending merge and CI, not a completed 1.0 freeze.

Dependency-aware external-integration repair — 2026-10-18​

  1. C16a — persistence safety (high technical risk): add EuroOffice receipt/recovery storage, session base revision and RecognitionExecution ledger in an additive migration; expire old unbound editor sessions. Drain active editors before deployment. Test migration on synthetic pre-change tables, row-lock/CAS races, duplicate receipts and user-deletion cleanup with PostgreSQL.
  2. C16b — service and parser boundaries (medium): retain the working editor configuration and recognition client; extract EuroOffice HTTP use cases into service/repository modules. Enforce streamed DOCX/ZIP/XML quotas before storing. Preserve force saves for recovery and commit only final saves against their original revision. Requires C16a; hostile-input and owner-only recovery tests block merge.
  3. C16c — contract adapters and paid intents (medium): introduce v1 mounts before moving clients, keep legacy facades, share platform transport; reserve paid recognition intent before provider POST and preserve unknown outcomes. Requires C16a/b; accepted retry, digest/model conflict, expired grant, cross-account status and native-origin-switch tests block merge.
  4. C16d — acceptance and promotion (high): real EuroOffice repeated force-save/close/reopen/crash tests, real Transkribus interrupted submission/reconciliation, owner recovery and Android/web transport acceptance. Requires C16a–c. Keep Preview until demonstrated; do not claim exactly-once upstream billing.

These can be reviewed as separate commits within a coordinated repair PR because the schema and service switch must ship together. Before application rollback disable EuroOffice and paid Transkribus execution and drain editors: old code neither writes bound-session fields nor honors the intent ledger. Retain recovery/ledger tables; do not drop captured saves or unknown paid intents. Re-enable only a schema-aware safe API. No OMI/schema migration is required. Full RC aggregation remains E02.

2026-10-21 — Federated discovery repair checkpoint (ADR-026)​

The new server directory is an operational discovery authority, separate from account, manuscript, review and publication authorities. DNS proves domain control only. Heartbeat online denotes a recent authenticated heartbeat, not service health, compatibility, capacity or trustworthiness. Browser selection opens the chosen origin; native selection retains the existing origin/token boundary. Discovery never proxies application traffic or transfers accounts/documents automatically.

The repair introduces /api/v1/server-registry; the old /api/server-registry is a shared-handler facade. The route delegates to application service, repository and GitHub audit adapters. Registration needs a private claimant capability distinct from public DNS data, expires in 24 hours, and uses database CAS for PENDING → VERIFYING → ACTIVE. Unknown audit outcomes stay quarantined without automatic issue resubmission. ACTIVE credentials survive the additive migration; old PENDING entries must re-register. Rotation/revocation/heartbeat updates compare current state and token atomically.

This is a proposed repair checkpoint, not a completed 1.0 freeze. Mandatory evidence includes synthetic negative/dual-mount tests, actual PostgreSQL migration/concurrency/lifecycle tests, plus controlled external DNS/GitHub acceptance and operational recovery. Deploy migration → API → clients/CLI/website; keep discovery Preview until acceptance evidence exists. Origin-scoped account/cache ownership and native SecureStorage remain separate open work.

PRGoal / filesDependencyTestsPhase / risk
C17aAdd registry proof/expiry migration, conditional repository and service; shared v1/legacy routes; CLI/client updateA09, existing registrynegative proof, replay, concurrency, PostgreSQL migration/lifecycleC / high
C17bADR-026 and five baseline documents; website v1 read and heartbeat wordingC17a API deployed before websiteEN/HU docs and site builds; operator acceptanceC / medium
C17cControlled DNS/GitHub acceptance and quarantine/lost-response recovery rehearsalC17a–brecorded synthetic instance, revoke, audit timeout and outageE blocker before Stable / medium

2026-10-22 — Document import origin clarification (ADR-023)​

This checkpoint supersedes the requirement to anchor whole-manuscript own-work declarations to imported content. OMI-SPEC-225@0.2.0 permits own-work imports without bibliographic attribution. An explicit own-work choice for DOCX, ODT or PDF stores the version-1 https://openmanuscript.org/extensions/manuscript-import-origin/1 document extension: sourceFormat, importedAt, and assertion: author-declared:self-authored-outside-omi. It is self-attestation, separate from a citation and verified authorship. No filename, path, URL, account identity, section ID, block ID or anchor is stored. Other import paths retain their existing per-object policy.

Every document part remains editable, replaceable, movable and deletable. The declaration is document metadata and creates no content relationship; replacing all imported content does not produce dangling anchors. It records a historical import declaration, not authorship of later edits. Working OMI, history snapshots and core-snapshot interchange preserve it via the existing namespaced extension contract, without a schema-version change. Public publication projections omit the extension without mutating the working document; anonymous server review projections remain allow-listed and exclude it.

Validation for the repair: DOCX/ODT/PDF own-work intake, deletion/replacement of imported content and titles, save/reopen, history-free core-snapshot round-trip, revision snapshot retention, public export omission and anonymous review filtering. Keep the existing editor, import parsers and revision engine. No database migration or legacy-marker conversion is required. Deployment status remains proposed until the coordinated Studio repair is merged and CI passes.

2026-10-25 — Publisher profile import repair (ADR-009)​

External file, URL and catalog profiles must pass a shared nested contract validator before activation. Validate required rule groups, enums, finite bounded layout values, citation style identifiers, protection shape, attached style structure and JSON complexity; reject prototype keys. Invalid input must not enter storage or change the active profile. The import boundary records SHA-256 over the exact received bytes for all three paths; catalog imports additionally compare the independently supplied catalog digest. A digest identifies content, not publisher identity. Imported protection metadata remains an unverified read-only declaration, never an authorization credential.

Generic scholarly and humanities profiles with independent note/bibliography defaults advance to 0.2.0. Retain explicit 0.1.0 definitions; resolve known versions exactly and reject unavailable versions instead of silently selecting newer behavior. Existing publication-build manifests already hash the resolved profile; retain that digest independently from local download provenance. Changes to render-affecting profile defaults require a new profile version. No application release bump or OMI-schema migration is needed for this repair.

Release evidence: negative nested-input fixtures, checksum mismatch and malformed UTF-8 rejection, deterministic byte hashes, old/new profile resolution, existing publication-build and renderer regression suites. The validator remains an application contract for the alpha profile model, not a newly frozen normative OMI schema. Further limits for streamed network reads and independently authenticated publisher signatures remain hardening work; checksum comparison alone does not establish trust. This checkpoint is proposed until the coordinated Studio PR is merged and CI passes.