Skip to main content

OMI Studio 1.0 ADR Register

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

ADR-036 (accepted target) refines ADR-022 with portable project ownership and future direct storage. The bounded inline-JSON repair aligns the actual envelope, preserves unsupported data and original prototype input, and separates project opening from graph import. Local cache success is never provider confirmation. Revisit for new resource types, archive members, direct-provider transfer, concurrent updates or public projections; retain ADR-008 loss/migration and ADR-019 evidence requirements.

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​

ADR-035 refines ADR-001/002/004/008/018/019/022/023: canonical Draft byte provenance, separately versioned experimental text-box content, retained legacy/future payloads with explicit supported edits, and reviewed graph contribution with external-source or own-work assertions. Reject divergent schemas, relabelled editor JSON, implicit graph publication and general author-editing locks. Revisit on profile/codec vocabulary, source synchronization or authority-bearing evidence changes.

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​

ADR-034 refines ADR-012/015/016/017/019: additive v1 privacy/account-copy contracts, shared legacy facades/quota, strict Zod-generated OpenAPI and client types, application/repository separation, standard errors/correlation and selected-origin native transport. The identity database stays account/authentication authority. Operator controller facts neither certify compliance nor grant identity/editorial/review authority; the overview remains explicitly partial.

Reject a breaking URL rename, separate legacy policies, complete-user serialization and a full-rights-export claim. Keep mandatory privacy/API evidence under existing exact-candidate release gates. Revisit on export-scope/schema expansion, shared/review data disclosure, new identity authority or legacy removal. Status: proposed repair pending companion merge/CI and separate deployment acceptance.

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.

Refines ADR-010 and ADR-019; Studio ADR-033 records this proposed reconciliation, consequences and revisit conditions. Current support decision.

Publication rendition boundary — 2026-11-04​

ADR-032 clarifies ADR-004/005/007/008/009/018/019/021: the canonical source and a separately editable publication rendition can coexist. Record source revision and rendition/build lineage internally; name/ORCID is visible author credit, not a revision identifier, signature or review grant. Modified publication content cannot inherit assurance solely from a source reference. Missing mapping/evidence must not be addressed by locking author editing.

Inspected source, decision and acceptance work.

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

Refine ADR-012/014/016/017 with the two-layer outbound policy and compatibility restrictions; refine ADR-019 with separate issue, source-test, operator and exact-candidate receipt states. Alternatives, consequences and revisit conditions are recorded in the linked checkpoint and Studio ADR-031. No new private-address exemption or stable support promise is approved.

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.

The following refinements are recorded in Studio ADR-030, pending companion merge and CI.

ADR / questionDecisionAlternatives / reasonConsequence / revisit condition
014/016/017 — remote Office authority?Opaque sandbox at element and HTTP policy, no API self connection; exact window/channel + null originAPI-origin allow-same-origin rejected; separate cookieless host valid but not required infrastructureMatched rollout and real browser/native acceptance; revisit provider need for storage, never weaken API-origin isolation
004/005/006/007 — tab/session owner?Application manager, active-store projection, pending/selection recovery; per-ID native save bindingReact manuscript list/global path rejected; no state-library rewriteRetain checkpoint-on-switch; revisit editor focus/undo and validated scoped-handle restoration; no portable session fields
014/015/020 — registry API version?Additive v1 plus shared legacy router/service/repository; declaration is not grantPayload version alone insufficient; no general executable runtimeOwner/parity tests; revisit public DTO or lifecycle expansion with explicit version policy
007/018 — may previews rewrite historical evidence?Preserve exact historical snapshots; explicit current-document serialization profile + shared goldenSilent v1 canonicalization change or destructive history rewrite rejectedLarger historical parts bounded by quotas; future normalization requires separately versioned evidence-preserving conversion
016/017 — production PDF fallback?Required socket, dedicated worker local executorSame-user API execution rejected in productionMissing worker disables PDF only; real systemd/ACL/network/limits gate. Revisit supported deployment topology
019 — what permits RC publication?Exact prior build SHA/file hashes + trusted workflow results + complete owner/manual receipt + strict issue gateGreen markers/issue closure/rebuilt different bytes insufficientNo missing-evidence promotion; attestation is not independent certification. Revisit gate scope and workflow/artifact contract changes

No OMI schema/container generation, database migration or general manuscript editing restriction is introduced. The previous claim of pending-change loss on tab switching was not established: that path already checkpointed. The global save-location defect and historical v1 digest change were verified by concrete regressions.

Current reconciliation: 2026-10-31, below. Earlier checkpoints remain historical where superseded. Proposed repairs require merge and CI; local evidence is not deployment acceptance.

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

This refines existing ADRs after Studio f41dadf, retaining the original dependency direction. The coordinated repair is proposed until reviewed/merged; Studio ADR-029 records concrete implementation boundaries.

ADR / questionDecisionAlternative and reasonConsequence / revisit
ADR-011/017/023: may reviewed translation disclose private notes?No. Public-note predicate before output unit collection/readiness, both HTML modes, current visibility. Keep private manuscript/history/translation data.Dump all reviewed alignments or delete source notes: rejected for privacy/data loss.Mandatory negative export gate; private units do not block public proof. Revisit explicit new audiences; anonymous review remains separate server projection.
ADR-004/005/007: who owns translation commands and anchors?Session-port application commands, Zustand/auth composition facade, existing checkpoints. Current profile/path locators are experimental.New store/history product or freezing editor JSON paths as semantic anchors: unnecessary/unsafe.Plain-session and store/reopen/revert tests; unknown profiles opaque. Revisit canonical 170, ContentCodec or versioned locator conversion.
ADR-008/009: who owns exchange-report execution?Application ExportExchangeSession owns warning/inspection/delivery-state/failure lifecycle; UI selects/composes existing renderers and delivery.React as report authority or wholesale renderer rewrite: rejected.Complete registry/streaming/remaining callers still open. Revisit new formats, audience or target validation.
ADR-007/011/012/017: collaboration authority?Current accepted DB membership + ACTIVE account; each message and 15 s idle recheck, 5 s deadline; read-only downgrade, fail-closed expiry/revocation/unavailability.Portable authorship/admin label/client boolean as grant: rejected.Single-node whole-manuscript profile; no implied editorial/segment grant; reconnect cannot bypass denial. Revisit federated/multi-node authority, translator scopes and revocation SLA.
ADR-001/008/019: do the new reports establish conformance?Keep validation, exchange, self-assessment, bounded core-review and publication-build artifacts separate. Incomplete/unapproved coverage remains indeterminate.Envelope validity, copied validator or a passing local suite as independent/Stable proof: rejected.Exact versions/subjects/freshness/exclusions and existing RC gates; newly revised core Drafts do not alter producer declarations. Revisit approved canonical profiles and independent evidence.

No schema/container/API-v1 rename or DB migration is implied. Normal manuscript editing stays available, including deletion and replacement of imported content.

Security boundary reconciliation — 2026-10-30​

These refinements apply to ADR-012/015/016/017/019 and supersede less specific historical checkpoints. Facts are verified against Studio 540f67a. The coordinated repair is a documentation/test proposal until merged; it does not claim host controls have been deployed.

ADR / questionDecisionAlternatives and reasonConsequences / review trigger
ADR-012: what authorizes administrator bootstrap?ACTIVE allow-listed local account plus linked OIDC/SAML boolean-verified matching email. Explicit central operator candidates also require ACTIVE verified federation. Older grants need private review; authentication evidence is separate from scholarly/review authority.Reject email-only bootstrap, any-SSO linkage and username-derived verification: they do not prove the allow-listed address. Avoid a replacement identity model.Trusted IdP reauthentication, second-owner recovery and audit; never fabricate claims. Revisit on issuer/claim policy, account-email change or a designed break-glass mechanism.
ADR-015: what protects legacy/v1 cookie writes?Global exact-Origin policy for unsafe cookie requests, structured 403/no-store. Rate/session gates before applicable large parsers. Additive v1 strategy remains unchanged.CORS alone, path-wide integration exemptions and weakening checks for older clients are rejected.Update script/native client contracts and test both surfaces; no mass route rename. Revisit new cookie clients, form routes or additional v1 mounts.
ADR-016: what does the native marker mean?Marker plus nonempty bearer bypasses only Origin; downstream validates bearer first and cannot fall back to cookie on invalid bearer. Native runtime remains a platform adapter concern.Marker as authentication or implicit trust in Tauri Origin is rejected.HTTP positive/negative regression; secure storage/origin-scoped caches remain open. Revisit transport/auth-handoff changes.
ADR-017: how are PKP and PDF boundaries enforced?Exact POST review-launch exceptions retain session, HMAC/nonce/expiry/scope verification. PDF quota 1/2 active, 12/100 retained per user/process; 429/503 and retry header. Environment allowlist minimizes inherited secrets but is not an OS sandbox.Blanket connector exception, unbounded jobs, full env inheritance or calling process-local quotas global are rejected.Keep working code; require worker filesystem/resource/network isolation and connection-time egress acceptance (#774/#765), distributed quota before multi-instance support. Revisit topology, renderer or connector protocol changes.
ADR-019: what evidence blocks promotion?Fast unit security gate plus server HTTP/bootstrap contract suite; real deployment/IdP/PKP/native evidence and exact-candidate aggregation still mandatory. Preview does not waive security.Helper/static tests alone, mocked database as integration proof or green env-filter tests as sandbox proof are rejected.S01–S05 in PR plan, with controlled rollout/recovery. Revisit capability promotion, new subprocess or evidence-aggregation changes.

Security rollout and recovery specifies errors/exceptions and operational limits. No OMI/container version or DB migration changes. All manuscript parts remain editable; service admission and publication authorization do not become document-editing restrictions.

Date: 2026-09-19

Interpretation: these are proposed decisions. Moving an ADR from Proposed to Accepted is part of the Phase A architecture freeze. Inclusion in this register does not retrospectively approve a decision without project review.

Status summary​

ADRDecisionProposed freeze status
ADR-001OMI file-format source of truthAccepted
ADR-002Schema and version fieldsAccepted
ADR-003Compatibility and migration policyAccepted
ADR-004Tiptap ↔ OMI content boundaryAccepted, conditional on AST-profile freeze
ADR-005Application-state ownershipAccepted
ADR-006Persistence authority and document sessionAccepted
ADR-007Revision/history modelAccepted
ADR-008Importer/exporter contractAccepted
ADR-009Publication pipelineAccepted
ADR-010Publishing System Connector APIAccepted
ADR-011Peer-review domain and anonymityAccepted
ADR-012Identity boundariesAccepted
ADR-013Storage abstractionAccepted
ADR-014Integration capability and permission modelAccepted
ADR-015Backend API versioningAccepted
ADR-016Cross-platform adapter boundaryAccepted
ADR-017Security trust boundariesAccepted
ADR-018OMI container, provenance, and signaturesAccepted, conditional on OMI-SPEC-330 fixtures
ADR-019Stable/preview capability policyAccepted
ADR-020General executable plugin runtimeDeferred
ADR-021Website publication assurance and editorial authorityProposed; delivery remains Preview
ADR-022Research module project and manuscript contribution boundaryProposed; partial implementation in Studio PRs #630/#631
ADR-023External object source attribution at Studio import boundaryProposed; staged import coverage in Studio PRs #632/#634–#637
ADR-032Editable publication rendition and source lineageProposed clarification; lineage/fidelity implementation pending
ADR-034Privacy API and partial account overviewProposed repair; companion merge/CI and deployment acceptance pending

| ADR-026 | Federated server discovery authority | Proposed repair / Preview |

ADR-001 — OMI file-format source of truth​

Question. Which artifact is the normative wire-format authority: TypeScript interfaces, JSON Schema, or prose specification?

Decision. The released OMI JSON Schema in the omi repository is the normative machine-executable wire contract. The prose specification defines semantics and invariants that JSON Schema cannot express. Studio currently vendors and validates against the OMI-SPEC-320@0.3.0 Draft schema, with a shared fixture corpus. Before a stable 1.0 promise, pin an immutable released schema by checksum and derive wire types/codecs from it; richer domain types may remain separate.

Alternatives considered. TypeScript-first schema generation; manually synchronized TypeScript and schema; making Studio the format authority.

Rationale. Interoperability spans languages and the PKP plugins. TypeScript is not language-neutral. The original 2026-09-19 audit found parallel hand-maintained definitions and an empty vendored 0.2 artifact. Studio has since adopted the 0.2 Draft schema and validator. That implementation change closes the original artifact gap but does not promote the Draft to a stable normative release.

Consequences. Schema releases and checksums become required. Generated artifacts are not hand-edited. Domain-invariant validation remains a separate layer. Any schema change triggers compatibility review.

Revisit when. JSON Schema cannot stably describe the wire shape, or all supported languages can demonstrably generate the same schema from another shared IDL.


ADR-002 — Schema and version fields​

Question. Should a new schemaVersion field be added beside top-level schema and omi.version?

Decision. No. omi.version is the OMI file-format version; schema is the exact schema URI. Readers verify that they are consistent. Container version, generator/application version, and manuscript revision remain independent version axes in their own layers.

Alternatives considered. Add schemaVersion; use only the schema URI; use only omi.version.

Rationale. A third equivalent field is redundant and creates another drift source. The URI gives exact schema identity while omi.version gives a negotiable semantic format generation.

Consequences. A mismatch is a fatal diagnostic. Code should use distinct typed concepts for file-format version, container version, application version, and revision ID.

Revisit when. Schema URIs cease to be immutable or a single format version is intentionally allowed to refer to incompatible normative schemas.


ADR-003 — Compatibility and migration policy​

Question. What backward/forward compatibility should Studio promise, and should early beta formats receive a permanent migration framework?

Decision. Compatibility obligations begin with the first frozen stable OMI generation. Pre-stable files receive an explicit best-effort importer or rejection path, not an indefinite compatibility promise. Later breaking stable changes require exact from → to migrations, fixtures, loss reports, and writes to a new target artifact. Newer major versions are quarantined/read-only; newer minor versions are editable only under an explicit forward-compatibility policy.

Alternatives considered. Permanent migration for every experimental format; silent best-effort open/save; supporting only the latest version.

Rationale. There is no evidence of production document stock that justifies a large pre-stable migration framework. Silent downgrade, however, creates unacceptable data-loss risk.

Consequences. UI distinguishes import, migration, read-only recovery, and normal open. Migration never runs implicitly at save time. Stable formats receive a published support policy.

Revisit when. Significant production pre-stable documents are discovered, or the number of stable generations justifies an explicit migration graph.


ADR-004 — Tiptap ↔ OMI content boundary​

Question. Can Tiptap/ProseMirror JSON be the portable OMI content model?

Decision. No. OMI-SPEC-100 and the file schema define the portable content AST. Tiptap remains the editor runtime. A versioned, loss-reporting ContentCodec converts between OMI AST and ProseMirror documents. During migration, the codec may read the existing serialized Tiptap JSON.

Alternatives considered. Standardize ProseMirror JSON as OMI; replace Tiptap with an editor built directly on a custom AST; let every exporter continue parsing editor JSON directly.

Rationale. The ProseMirror schema depends on editor/plugin configuration and already leaks into many independent consumers. Tiptap itself is working and well tested, so replacing it would not address the actual architectural problem.

Consequences. Every rich-text consumer uses the codec API. Unknown node/mark diagnostics and golden round-trip fixtures are mandatory. Selection and editor undo are runtime state, not portable state.

Implementation checkpoint (2026-10-10). The DOCX importer records the Word source typeface in an omiSourceFont Tiptap mark; extractOmiInlineRuns translates it into a presentation hint consumed by IDML. The existing IDML fixture and Studio PR #657 characterize this interim route. It is not a frozen OMI-SPEC-100 field or proof of portable cross-editor round-trip. Keep the hint behind the adapter, report unsupported marks, and require a versioned AST mapping and save/reopen golden corpus before B06/schema freeze; do not delete a working font-fidelity path during that migration.

Revisit when. The ProseMirror ecosystem provides a durable language-neutral wire standard that losslessly expresses all required OMI semantics.


ADR-005 — Application-state ownership​

Question. Should manuscript state/use cases be owned by Zustand actions, React components, or an application service?

Decision. A platform-independent application core executes commands/use cases and owns the document session. Zustand becomes UI/session projection plus compatibility facade. React sends intent and reads view models. Editor runtime has its own session ownership.

Alternatives considered. Keep the large Zustand store as authority; rewrite into another state library; use component-local state.

Rationale. The issue is mixed responsibility and lifetime, not Zustand as a technology. Replacing one state library with another would preserve the underlying coupling.

Consequences. Commands carry optimistic revision preconditions where needed. UI mutations migrate incrementally. Existing pure model functions remain reusable.

Revisit when. UI-projection cost or future concurrency requirements provide evidence for a different runtime model.


ADR-006 — Persistence authority and document session​

Question. Which copy is authoritative among native file, recovery cache, server snapshot, cloud copy, and open UI state?

Decision. A DocumentSession explicitly tracks source/location plus last-saved revision/digest. The user-saved OMI file/container is the portable document artifact. IndexedDB recovery, cloud byte storage, and server workflow snapshots are explicitly named replicas/snapshots. Native locations are opaque handles, not domain path strings.

Alternatives considered. Last-write-wins across every store; server is always authoritative; Zustand state is implicit authority.

Rationale. Studio supports offline/native and external workflow use cases. There is no universal single store. Hidden authority creates data loss and conflict ambiguity.

Consequences. Save preconditions, conflict receipts, atomic replace, and recovery journal are required. Cloud providers do not edit manuscript semantics.

Revisit when. A future collaboration service introduces explicit multi-writer authority and a CRDT/transaction model.


ADR-007 — Revision/history model​

Question. How do editor undo, working changes, and durable revision history relate, and how should history be stored?

Decision. Editor undo is session-local. Working changes are application semantic commands. A revision is an immutable linear commit; revert creates a new commit. Current revision semantics remain but move behind RevisionRepository. The first adapter may continue full snapshots; content-addressed or delta storage is introduced only after measurement.

Alternatives considered. Treat PM undo as history; immediately move to CRDT/event sourcing; remove revisions and rely on file backups.

Rationale. The current revision model is strong and tested. The problem is ownership and storage scaling, not semantic correctness.

Consequences. Storage algorithm remains internal. An export profile determines which history is portable. Branching/collaborative history is not part of the base stable 1.0 contract.

Revisit when. Concurrent multi-user editing becomes a stable requirement or benchmarks prove full snapshots unacceptable.


ADR-008 — Importer/exporter contract​

Question. How should heterogeneous import and export formats share one architecture?

Decision. Use registry-based Importer and Renderer contracts with shared descriptors/capabilities, diagnostics, fidelity/loss, provenance, progress/abort, and streaming source/artifact models. Platform-specific delivery is a separate ArtifactDeliveryPort.

Alternatives considered. Independent UI/service per format; one giant switch; require every renderer to be a CLI process.

Rationale. Existing importers/exporters can remain as adapters, but inconsistent diagnostics and delivery currently couple them too closely to UI/store state.

Consequences. Stable/preview format capabilities are runtime-queryable. Renderers cannot open file pickers. Large-file/random-access requirements are declared.

Revisit when. Streaming or process-isolation requirements prove that separate contract families are needed; shared result/evidence concepts should still remain.


ADR-009 — Publication pipeline​

Question. What is the final reproducible publication-build sequence?

Decision. Validated committed OMI revision → immutable rendering context → versioned publication profile/resources → pinned renderer → target validators → artifact set → build manifest/hash/signature → delivery/transfer. Pre- and post-validation are mandatory.

Alternatives considered. Export directly from live store; embed profile/CSS in manuscript domain; validate only after upload.

Rationale. Existing build manifests and artifact hashing are strong foundations, but rendering live/raw editor state and presentation-model augmentation leave reproducibility gaps.

Consequences. Semantic reproducibility and byte reproducibility are separate claims. Renderer, font/resource, and validator versions are recorded. Invalid stable artifacts cannot be transferred by stable connectors.

Revisit when. A live/interactive publication class cannot meaningfully be expressed as a deterministic build; it should then receive a separate artifact class/ADR.


ADR-010 — Publishing System Connector API​

Question. Should OJS and OMP remain separate integration architectures?

Decision. A shared Publishing System Connector API handles capability discovery, signed launch, submission/metadata/contributors/files, review assignment/form/recommendation, revision/attachment/artifact upload, and workflow return. OJS/OMP remain profile adapters with extensions. The external publishing system remains authoritative for its own workflow state.

Alternatives considered. Two completely independent clients; lowest common denominator with no extensions; force the OJS object model onto OMP.

Rationale. Both plugins already implement common omi-integration/1 concepts. A common contract reduces drift without denying genuine journal/monograph differences.

Consequences. Shared schemas and fixture suites are required. Writeback uses idempotent outbox semantics. Future journal/press/repository integrations implement the same port.

Revisit when. At least two additional systems demonstrate that the abstraction is still overly PKP-specific.


ADR-011 — Peer-review domain and anonymity​

Question. Is peer review merely part of the publishing connector, and where is double-anonymous protection enforced?

Decision. Review is an independent publishing-system-neutral domain: assignment, round, projection, workspace, attachment, form, recommendation, visibility, and writeback. Anonymous projection is a server-side security boundary derived from a committed source revision; never a client-side hide operation.

Alternatives considered. Use OJS/OMP DTOs directly; send the full manuscript and hide fields in the client; maintain a manual anonymized copy.

Rationale. The existing server allowlist and PKP reviewer scopes are strong starting points. An anonymity failure is high consequence and requires an explicit domain plus adversarial leak corpus.

Consequences. Asset metadata, filenames, EXIF/SVG, and provenance are included in projection policy. Use assignment-scoped identifiers and no-store caching. Confidential AI/integration access is possible only through a server-issued grant.

Revisit when. Open review or post-publication review requires a different visibility policy; the projection boundary itself remains.


ADR-012 — Identity boundaries​

Question. How do account, auth provider identity, scholarly agent, institution, contribution, and publication evidence relate?

Decision. Treat them as six distinct concepts/relationships. The identity database is authoritative for account/authentication/membership/admin. The main database holds a StudioPrincipal projection for workflow foreign keys. Scholarly agent and contribution belong to the portable OMI manuscript. Account↔agent linking requires explicit verified evidence; email or ORCID equality is not an automatic merge. Authorization is a separate policy.

Alternatives considered. One universal User model; ORCID as the primary user ID; two independent authoritative user databases.

Rationale. Publication attribution is portable and historical while an account is revocable operational identity. Duplicate authority across the current Prisma schemas creates drift risk.

Consequences. Principal projection needs reconciliation/outbox behaviour. Signatures/evidence use a separate store. Linking/revoking an auth provider does not silently rewrite manuscript authorship.

Revisit when. Consolidating to one transactional database is demonstrably simpler without collapsing domain concepts.


ADR-013 — Storage abstraction​

Question. How should native files, browser files, Android SAF, Apple Files, synchronized folders, and cloud storage share one model?

Decision. Use two port families: DocumentStorage/DocumentLocation for user-managed documents, and RemoteObjectStore for backup/sync byte objects. Platform adapters own pickers, permissions, and bookmarks. Providers never interpret manuscript semantics.

Alternatives considered. A unique save use case per provider; force every file through server upload; use a path string as the universal identifier.

Rationale. Platform permission models differ, but open/read/writeAtomic/conflict semantics are shared. A string path cannot represent browser, SAF, or security-scoped handles.

Consequences. Opaque handles stay in session/persistence layers. ETag/digest conflicts are explicit. Downloaded cloud copies pass through the same validators.

Revisit when. True multi-device synchronization requires merge semantics; that would be a separate Sync Service domain rather than a larger storage provider.


ADR-014 — Integration capability and permission model​

Question. What manuscript data may Zotero, Mendeley, DeepL, AI, storage, OJS/OMP, ORCID, or OIDC connectors receive?

Decision. Default deny, using server-issued ExecutionGrant: actor, provider/connection, document/revision, purpose, data-access scope, capability, confidential scope, expiry, single-use/idempotency. The server minimizes the payload. AI/translation output is a suggestion by default, not a direct mutation.

Alternatives considered. Full-manuscript access after user consent; automatically accept scopes requested by provider manifests; client-side allow flags.

Rationale. Manuscript and peer-review data can be sensitive. A client-supplied confidential flag is not authority, and providers need different minimum scopes.

Consequences. A scope taxonomy and audit-retention policy are required. Credentials live in a separate encrypted repository. Review-confidential grants derive from server-side assignments.

Revisit when. A fully on-device provider justifies a simpler local grant profile; scope and audit still apply.


ADR-015 — Backend API versioning​

Question. Should all current routes be renamed into /api/v1 at once?

Decision. Introduce additive /api/v1 with shared Zod/OpenAPI schemas, error envelopes, idempotency, optimistic concurrency, and correlation policy. Legacy routes remain compatibility facades calling the same application handlers, with deprecation telemetry. No one-shot mass rename.

Alternatives considered. In-place route rename; header-only versioning; freeze all current routes forever.

Rationale. Existing clients work today; mass rename adds unnecessary migration risk. A v1 namespace gives clear support and contract-diff semantics.

Consequences. Two route surfaces coexist temporarily. Business logic moves from routes into application services. External PKP protocols may maintain their own explicit profile/version.

Revisit when. Studio becomes an entirely atomically deployed client/server product; even then, external connector DTOs remain versioned.


ADR-016 — Cross-platform adapter boundary​

Question. How should one core support web, Windows/Linux/macOS, Android, and iOS/iPadOS?

Decision. Application ports cover file picker/storage, secure storage, auth handoff, updater/installer, system fonts/resources, capability detection, share/open-with, and notifications. Concrete web/Tauri/Android/Apple adapters are selected only at composition roots.

Alternatives considered. Platform checks throughout services; separate forks per platform; constrain all capability to the web lowest common denominator.

Rationale. Current Tauri/mobile code is useful but direct imports and user-agent detection leak into shared areas. Ports preserve one core while allowing honest platform capability differences.

Consequences. Every adapter receives a contract suite. Stable/preview classification is declared per artifact. iOS can remain preview without a core fork.

Implementation checkpoint (2026-10-10). Native endpoint selection currently reads/writes localStorage and clears the native token on server switch. Studio PR #656 moves runtime detection and storage access behind a platform adapter and tests fail-closed token invalidation. This is an incremental boundary, not B10 completion: secure storage, per-origin account/cache isolation and auth handoff still need contract tests before native 1.0 promotion.

Revisit when. A platform lifecycle genuinely requires different use-case semantics; extend application policy before considering domain forks.


ADR-017 — Security trust boundaries​

Question. Where is data treated as untrusted, and which controls block unsafe data from the domain?

Decision. Establish explicit boundaries before imported JSON/container/DOCX/PDF/HTML/XML/assets, OAuth/OIDC credentials, connectors, confidential review data, AI providers, plugins, and publication artifacts. Each boundary combines quotas, safe parsing, validation, authorization, and content-free auditing according to its risk.

Alternatives considered. UI-only validation; trust local files; one generic sanitizer for every format.

Rationale. The current implementation already contains strong but scattered controls such as ZIP limits, LIBXML_NONET, SSRF helpers, and signed launches. They should be organized as threat boundaries rather than replaced.

Consequences. Hostile synthetic corpus, fuzzing, and negative-auth matrices become release gates. Diagnostics/logs do not contain manuscript content or local paths. A security fix may override compatibility promises under a documented emergency policy.

Publication projection checkpoint (2026-10-10). IDML previously appended all manuscript annotations to a visible notes section, including renderingHint: hidden self-origin declarations and editor_only notes. Studio PR #654 projects only public notes and suppresses private inline markers. This privacy defect blocks preview publication too; require synthetic negative fixtures for every public renderer and anonymous projection.

Revisit when. A new input, protocol, provider, or trust assumption is introduced.


ADR-018 — OMI container, provenance, and signatures​

Question. Is the container merely ZIP transport, or the authority for manuscript/history/assets/profile/output/signatures?

Decision. The container is a separately versioned packaging layer with manifest, canonical paths, checksums, and optional profile/history/output/evidence entries. Manuscript JSON remains the portable semantic core. Signatures cover manifest and exact artifact digests; they are not ad hoc top-level manuscript fields or localStorage state.

Alternatives considered. One large JSON with base64 assets; couple container and schema version; inject signatures into the manuscript object.

Rationale. The current container parser is secure and implementation already supports much of the needed package behaviour. A separate packaging layer preserves JSON interoperability while allowing large assets/history/evidence to be externalized.

Consequences. OMI-SPEC-330 needs a manifest schema and cross-repository golden fixtures. Container validation is two-stage: package integrity then manuscript semantics. Key lifecycle is separate from document semantics.

Revisit when. Streaming/content-addressed remote packaging exceeds ZIP limits; a new container major can then evolve without changing OMI JSON.


ADR-019 — Stable/preview capability policy​

Question. Must every implemented or visible feature be guaranteed as stable in 1.0?

Decision. No. A stable/preview/experimental/deferred capability manifest defines support per platform and format. Existing code or a smoke test is not a stable support promise. Preview failure is not generally release-blocking, except for privacy, data-loss, and security defects.

Alternatives considered. Every visible feature is stable; remove all preview features; one global platform status.

Rationale. Evidence maturity differs substantially between JATS/HTML/DOCX and some DTP/EPUB/iOS areas. Working code should not be deleted merely because it has not yet earned a stable guarantee.

Consequences. Runtime UI, documentation, and release metadata are generated from or checked against the same capability manifest. Promotion requires a defined evidence gate. Demotion of stable capability within 1.x requires exceptional cause.

Image/readiness checkpoint (2026-10-10). The main deploy currently publishes latest and a commit image after build/collaboration checks, while readiness is path-filtered. Studio PR #655 runs readiness on every main commit and labels main images beta plus commit-addressed tags. An immutable tag alone does not earn RC approval. E02 still requires exact-commit aggregation of readiness, PKP, security and Stable-platform installer evidence before any 1.0/RC image promotion; existing latest installations need an explicit channel/pin migration.

Revisit when. Every release is planned and whenever a capability completes its promotion corpus.

PKP scope refinement (2026-11-07). The explicitly declared OJS/OMP -4/-5/-6 E02 regression jobs/archives are mandatory even for Preview OMP. OJS -6 adds a separate manual gate, bringing the v1 receipt to 14. This exception does not promote OMP or waive security, privacy or data-loss gates.


ADR-020 — General executable plugin runtime​

Question. Should 1.0 include a general plugin system that executes third-party code?

Decision. Deferred. 1.0 supports built-in reviewed connector adapters and a declarative manifest/capability registry. Arbitrary plugin code execution, sandboxing, signing marketplace, and plugin permission UX are a separate post-1.0 programme.

Alternatives considered. In-process JavaScript plugins; remote HTTP plugins with full-manuscript access; permanently hard-code every integration.

Rationale. The current registry is not an execution sandbox. A safe plugin runtime is a new trust boundary and product area, not a small stabilization task.

Consequences. 1.0 documentation must not claim arbitrary plugin execution. New integrations are added as reviewed adapters with scoped grants. Registry payloads cannot activate executable code.

Revisit when. There are at least three concrete third-party plugin use cases, a threat model, a viable sandbox, signing/distribution policy, and a dedicated maintenance owner.

ADR-021 — Website publication assurance and editorial authority​

Question. How may a website artifact say that it is peer reviewed when a journal or press does not use OJS or OMP, without making a website connector or a client-side switch the authority?

Decision. Publication intent and review assurance are separate. Every Studio website artifact carries a visible, accessible and machine-readable assurance of either not-peer-reviewed or peer-reviewed. The circular mark is language-independent and uses the fixed wording OMI · PEER REVIEW · VERIFIED or OMI · PEER REVIEW · NOT VERIFIED; the adjacent explanation remains localized. VERIFIED refers to Studio-recorded workflow evidence, not an OMI endorsement of content or scholarly quality. The reviewed value requires a completed Studio-native scientific review round and a separate server-side editor acceptance decision bound to the exact committed revision and manuscript-state digest. Review completion alone is not acceptance. When OJS/OMP owns the workflow it remains authoritative; externally bound assignments cannot create a Studio-native decision. The website/WordPress adapter is only an ArtifactDeliveryPort. The assurance notice is part of the rendered bytes before the publication-build hash is calculated, and a server-issued execution grant binds the selected target-configuration version and revalidates the evidence before delivery. A declared WordPress transport projection may extract the article and relocate embedded media, but its exact outgoing digest is receipted separately from the approved standalone-artifact digest. Public evidence contains decision ID, evidence digest, round and time, never reviewer identity, confidential feedback or recommendations. The seal attests workflow evidence, not the truth of the article.

For a journal or press without OJS/OMP, publication-venue authority may additionally be verified by a one-time DNS TXT challenge under the venue's domain. DNS TXT data is public by design: the value is not a secret credential and does not identify an editor. The proof comes from an authenticated Studio account being able to publish a fresh, server-issued challenge at the required DNS name before expiry. The challenge is bound server-side to that account and may be consumed only once; reading the public TXT value cannot grant another account authority. DNS control is therefore an organizational authority proof, not peer-review evidence. Successful DNS verification grants the claimant a DOMAIN_ADMIN role. An active domain administrator may delegate additional DOMAIN_ADMIN, EDITOR or EDITOR_IN_CHIEF memberships to existing Studio accounts without creating another DNS TXT record. Delegated administrators receive the same venue-administration authority; the server forbids revocation of the last active domain administrator. Only editor roles, combined with manuscript-workspace editor access and a completed native scientific review round, may create a publisher-verified acceptance. The decision is also bound to the assurance-neutral publication-content digest and stores an immutable snapshot of venue, domain, DNS verification identity/time and editor role. Later DNS checks establish continued public domain assertion, not possession of a secret. Later DNS or membership changes do not rewrite historical decision provenance.

Alternatives. A user-selected “reviewed” boolean; infer review from a completed assignment; require OJS/OMP for every reviewed publication; let WordPress or the receiving website set the status; embed reviewer names or reports in the artifact.

Reason. Independent journals and presses need the Studio review workflow and web delivery without adopting PKP software. A default-deny assurance boundary preserves that capability without weakening anonymity, external workflow authority, provenance or the distinction between editorial acceptance and reviewer recommendation.

Consequences. Editing creates a new revision and invalidates use of the prior decision for a new reviewed artifact. Unreviewed scholarly and public-interest publishing remains valid but is never ambiguous. The idempotency identity includes assurance evidence and target configuration version. Website delivery stays Preview until outbox recovery, tamper, accessibility, receiver-contract and privacy tests pass. A false reviewed seal, missing unreviewed notice, undeclared or unreceipted transport transformation, or reviewer leak is release-blocking even while the feature is Preview.

Review when. A standard review-taxonomy or external evidence format is selected, a non-PKP publishing-system adapter supplies authoritative editorial decisions, or post-publication/open review requires additional public assurance states.

Parameters to quantify before freeze​

These are not new ADRs; they are concrete values required by the decisions above.

ParameterDecision inputDeadline
first stable OMI file-format versionOMI-SPEC-100/150/160/320 readinessend of Phase A
forward-minor policyunknown-field round-trip evidenceA05
container size/entry/depth limitscurrent parser plus platform-memory benchmarksA07/E01
history snapshot/delta threshold120k/500k-word benchmarksB07/D06
stable exporter listfixture/fidelity/validator evidenceC14
website assurance and receiver contracttamper, transport-digest, recovery, privacy and accessibility evidenceC15
exact supported OJS/OMP versionsDocker E2E matrixC07/C08
token/session TTL and credential rotationsecurity reviewB10/C12
performance and bundle budgetscurrent baseline plus representative devicesD06
RC soak length and blocker SLArelease ownershipbefore E05

ADR-022 — Research module project and manuscript contribution boundary​

Question. May a discipline module's browser-stored project record be copied into portable manuscript content when the researcher selects “Insert module section”?

Decision. No. The action inserts a localized module title and description only. Project JSON and IndexedDB records are separate research workspace state; they are neither OMI-SPEC-320 documents nor implicit manuscript content. A later contribution is allowed when it is a typed, versioned, allow-listed projection with a mandatory source record/citation or a clearly identified researcher-authored source, provenance/loss diagnostics, explicit exact-content preview and confirmation, confidentiality-aware authorization, OMI validation, and a revision-aware application command. The source must be carried as structured portable citation/provenance where the OMI profile supports it and rendered visibly with the inserted excerpt; a label alone is insufficient. Confidential interview and participant fields are excluded by default. Storage failure and backup/recovery state must be visible to the user.

Alternatives considered. Recursive flattening of arbitrary records; inserting full project JSON as a blob; prohibiting all future contribution; immediate migration of every module into OMI.

Rationale. The existing recursive flattening could disclose private research material and discard structure without a deliberate editorial decision. Modules have different record schemas and retention requirements; a shared portable manuscript format is not their project database.

Consequences. Studio PR #630 contains the immediate transfer. Merged Studio PR #631 adds opt-in, source-visible excerpts for four module types. Studio PR #637 extends the same allow-listed projection to legal, reproducibility, spatial, archaeology, experimental, and non-confidential social research records. These remain partial implementations: source text is not a semantic OMI citation, and statistical IndexedDB records are outside this projection. Versioned module repositories and opt-in projections are separate incremental PRs. Existing module exports retain their own scope and compatibility policy. Synthetic confidential-data, missing-source, source-integrity, storage-failure, validation and round-trip tests gate a later projection. Source metadata must not disclose reviewer or participant identity in an anonymous projection.

Revisit when. A reviewed module projection contract and privacy fixtures prove exact-content consent, authorization, retention and reversible manuscript insertion.


ADR-023 — External object source attribution at the Studio import boundary​

Question. When an image, table, chart, equation, score, research excerpt or other scholarly object originates outside the current OMI manuscript, where is source attribution required?

Decision. Studio requires a nonempty, user-visible source before adding external scholarly material to an editable manuscript. Prefill it from trustworthy available input metadata (file name, archive part, declared URL, module record source, or publishing-system file metadata), then let the researcher review/correct the exact value before insertion. Preserve machine import provenance separately. For multiple objects, apply the rule per object, with a visible source adjacent to each. Studio-authored blank objects are exempt. Opening a valid OMI file preserves its own identity, citation and history; the rule does not retroactively reject or silently rewrite it. A source label alone does not authorize disclosure of confidential data.

Author-created outside OMI. A researcher may explicitly attest that imported material is their own work created earlier in another editor. In that case Studio omits the visible source notice, but persists a portable, hidden semantic origin declaration anchored to the imported content. This is a self-attestation, not verified authorship or a bibliographic citation. The declaration must survive OMI save/reopen and revision history; public renderers must omit the notice, and anonymous projections must not leak account, path, or filename metadata. Third-party material still requires a reviewed visible source. The option is scoped to the exact imported manuscript or object, never a blanket preference or a claim that all content in a mixed batch is self-authored.

Alternatives considered. Optional attribution; blindly accepting filenames as citations; changing the OMI-SPEC-320 schema to require a new field on every block; appending one source to an entire mixed batch.

Rationale. Existing visual import provenance already knows file names/parts but is not always visible in artifacts; clipboard and module inputs may lack a source. An application-level confirmation gate can improve attribution without breaking canonical OMI compatibility. Filename is a hint rather than verified bibliographic evidence.

Consequences. Studio PR #632 handles file/clipboard visual objects. Studio PR #631 handles four module excerpt types. Studio PR #634 adds a reviewed visible source to DOCX/PDF whole-document conversion; dependent PR #636 adds editable OJS/OMP launch-import notices. PR #635 previews imported bibliography records whose citations carry the actual source, while PR #637 covers additional allow-listed module excerpts. HTML visual inputs are addressed by #632; there is no general standalone JATS manuscript importer to claim. The audited asset attachment call site is the visual insertion path, while existing package restore is a distinct trusted-document operation. Studio PR #638 implements the self-authored option for DOCX/PDF whole-document conversion. Dependent Studio PR #639 adds a per-object visual choice and one revision batch for object plus hidden declaration. OJS/OMP mixed intake still requires a separately reviewed ownership path. Each open PR is conditional on review/merge. The remaining cross-format obligation is a stable semantic OMI source-object link, export/reimport fidelity, and a synthetic round-trip/anonymization corpus. Visible source text is currently not a semantic OMI citation; source-object linkage and exporter fidelity remain 1.0 gates. Do not claim universal enforcement until these paths are covered.

Revisit when. The OMI specification defines a stable structured object-provenance/citation link and independent import/export fixtures prove it, or a source is legally unsafe to expose in an anonymized review projection.

IDML drift (2026-10-10). The hidden self-authored declaration was visible in the IDML notes appendix. Studio PR #654 is the targeted repair. Do not consider ADR-023 satisfied until its privacy regression runs on the merged commit and remaining public formats are audited with synthetic fixtures.


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

  • ADR-004: #657 is merged adapter characterization. No new stable portable AST or ContentCodec decision is implied.
  • ADR-016/017: #656 is merged origin-selection containment. SecureStorage and origin-scoped account/cache ownership remain unsatisfied; token invalidation does not constitute keystore protection.
  • ADR-017/023: #654 is merged IDML privacy containment. #662 extends a shared non-mutating publication view to HTML/JATS/DOCX/EPUB/LaTeX/MIF/SLA/XTG. Public output excludes non-note, hidden and workflow-visible annotations and their known inline anchors; portable state retains them. This is a renderer boundary and does not modify the OMI wire schema. Revisit when structured source-object linkage or anonymous/print projection changes.
  • ADR-019: #655 is merged continuous readiness/beta-channel repair. Stable/RC compatibility promotion still requires E02 exact-commit/digest evidence; mutable commit-addressed tags alone prove no artifact immutability.

Alternatives rejected for annotation privacy: deleting private data from portable state; UI-only hiding; eight independent ad hoc rules. The shared view preserves current renderers and makes the public decision testable. Its scope is annotation disclosure, not a general-purpose anonymous manuscript projection or proof that every metadata field is safe.

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.

ADR reconciliation​

ADRCurrent decision / consequence
ADR-001OMI remains the wire authority; 0.3 Draft replaces 0.2 as the observed Studio candidate. Schema provenance/checksum and generated-contract gates remain before stable freeze.
ADR-002Existing schema URI plus omi.version remain sufficient; application, container and revision versions remain independent.
ADR-003No new pre-stable migration obligation. Explicit refusal is permitted for experimental 0.2 files; unsupported future stable generations still require the agreed quarantine policy.
ADR-007Current-state object deletion must update dependent source links in the same revision batch. Historical snapshots retain the old graph; historical revert restores it. No silent rewriting of old revisions.
ADR-008/009Unsupported source relationships require explicit fidelity diagnostics. HTML/JATS warnings are proposed in #674; validForExport is not a claim of losslessness. Revisit when target mappings and reimport fixtures exist.
ADR-023Structured source linkage is now partially implemented under OMI-SPEC-225 and 0.3 Draft. Adjacent source text is a presentation choice, not the semantic link, rights or verified authorship. Remaining ingress/lifecycle/export/privacy evidence blocks universal enforcement claims.

These updates reconcile implementation evidence and consequences; they do not promote the Draft schema, ADR-023 or the architecture to frozen/stable status.

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.

ADR-024 — Ordinary DOCX callback authority and recovery​

Status: Proposed; implementation repair pending merge and acceptance.

Question. How can repeated external editor saves avoid stale overwrite without breaking force-save sessions?

Decision. Studio owns the canonical DOCX head. Bind each session to its starting revision. Preserve status-6 force saves and conflicting status-2 callbacks as immutable owner-downloadable recovery snapshots; only a final status-2 callback may advance the head under row lock/CAS. Back up the prior head and receipt the callback in the same transaction. Deduplicate by document/editor key/status/callback URL digest; never persist that source URL. Validate streamed size and ZIP/OPC/XML integrity before storage. Use service/repository ports and additive v1 routes with legacy facades.

Alternatives. Unconditional last-arrival wins; consume the capability after every force save; require an undocumented provider sequence counter; discard conflicts.

Rationale. Repeated force saves are normal. Arrival order is not trustworthy edit order, and provider serverVersion describes its software version, not a monotonic save sequence. Recovery must not silently overwrite newer canonical data.

Consequences. New recovery tables/owner downloads, database growth and an explicit retention policy; no silent pruning in this repair. Final close remains authoritative; crash force saves are recovered by download. Deployment drains active editors and expires legacy sessions. PostgreSQL concurrency/migration and real-provider lifecycle evidence are mandatory before promotion.

Revisit when. The provider supplies a verified monotonic save sequence or a durable collaborative session contract that safely supports force-save head promotion; recovery retention/storage quotas require a separately reviewed policy.

ADR-025 — Paid recognition intent and grant binding​

Status: Proposed; implementation repair pending merge and acceptance.

Question. How is a paid external recognition submission authorized and recovered after an ambiguous network result?

Decision. The service validates an expiring server module grant, then persists a unique account/workspace request identity bound to connection, provider origin, image digest, model, purpose and uploaded-image scope before its single paid POST. ACCEPTED stores process ID; unknown/in-flight outcomes do not authorize resubmission under the same key. Accepted retries read the prior job and mismatched payloads conflict. Status lookup is account/workspace scoped. Client request identity is saved before sending. No source images, credentials or recognized text belong in this ledger. This scope does not authorize automatic confidential manuscript/review export.

Alternatives. Consent checkbox only; retry every timeout; keep intent only in browser memory; promise external exactly-once billing.

Rationale. A timeout does not prove the provider rejected a billable request. Database uniqueness prevents competing local submits, but cannot atomically commit a remote provider transaction.

Consequences. Additive persistence and v1 status contract, retained unknown outcomes, explicit provider-side reconciliation. Generic retries never spend more credits. Existing stateless job handles remain account bound; the paid ledger is not an OMI history or publication-identity record.

Revisit when. The provider exposes a verified idempotency/reconciliation API or confidential research export is requested; then extend the authorization/data-minimization contract before enabling it.

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.

ADR-026 — Federated server discovery authority​

Status: Proposed repair; Preview pending CI and operator acceptance.

Question: How can independent Studio instances advertise availability without inheriting account, editorial or manuscript authority?

Decision: Keep opt-in metadata discovery separate from all application traffic. Registry DB owns registration/token/liveness state; GitHub issues are audit evidence, not an authoritative catalogue of current membership. Require private expiring claimant capability plus public DNS proof, atomic single-owner activation, hashed credentials and CAS rotation/revocation. Unknown GitHub outcomes are quarantined for reconciliation. Use v1 contracts with shared legacy facades and service/repository/adaptor separation.

Alternatives: Public DNS alone (cannot authenticate the recipient); GitHub as live database (unnecessary coupling); automatic retries after uncertain issue creation (duplicates); proxy/load balancer (outside discovery scope).

Reason: Prevent public proof replay and token races while preserving decentralized Studio operation.

Consequences: An additive DB migration invalidates old pending registrations only. Operators retain the private registration token for verification. Lost activation responses and uncertain audit results require controlled reconciliation and fresh registration. Heartbeat is not health/compatibility certification. Tests must cover real database races and credential scope; external acceptance is still required.

Review trigger: Dedicated registry hosting, independent moderation, DNS revalidation policy, durable audit outbox/reconciliation tooling, compatibility certification, or any automatic server/account/document movement.

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.

2026-11-08 — Automatic daily server discovery (ADR-026 update)​

Public production Studio APIs now announce their existing canonical HTTPS origin automatically at startup and daily. The registry verifies a fresh nonce at the origin's fixed public identity endpoint using socket-pinned public DNS, no redirects, bounded response size and timeout, then persists metadata obtained from that endpoint. No per-instance DNS, token or registration command is required. The central registry maintains its own entry locally without HTTP self-calls. Explicit revocations and uncertain manual audits remain blocked; the earlier DNS/private-proof workflow above is retained for manual compatibility.

The website reads a separate daily public endpoint and refreshes while open without editing, rebuilding or deploying the website. Entries expire from the next daily listing after 48 hours without a verified signal; last-seen and generation times are visible. This is discovery metadata, not account authority or a real-time service-health guarantee. See automatic server directory and the Studio operator guide for rollout.