Skip to content

chore(architecture): prepare migration to PuzlWerk shared core/viewer #29

Open

Description

@wstein

Viewer ownership decision — 2026-11-05 (supersedes the 2026-10-31 unresolved gate): The planned shared TypeScript scene/viewer is @puzlwerk/viewer in PuzlWerk, separate from its ReScript core; it handles camera/POV, scene, rendering and interpolation without owning physical cube state or application logic. The CubeScene proposal is not an approved API, and animation timing/easing ownership remains open. See the canonical Cubistry #21 decision and current PuzlWerk boundary. This does not authorize migration: keep CubeAssembler's scanner, renderer and 2×2–7×7 behavior intact; M2 needs completed M1 acceptance and separate human approval, with compatibility, license and regression review. Existing authorized fixes are unaffected. No parallel shared engine or new solver work.

Stand 30.10.2026 (ersetzt ältere Statusabschnitte): Die bereits genehmigten, begrenzten 3×3-Bild-/Kalender-PRs CubeLab #27, PuzlWerk #21 und Cubistry #70 wurden am 29.10. gemergt; frühere „Draft“-Angaben sind überholt. Cubistry #23 und PuzlWerk #5 sind seit 28.10. geschlossen. Die vollständige 2×2-MVP-Abnahme Cubistry #18/#21 ist noch offen. Dies ist keine implizite Freigabe für die vollständige CubeAssembler-Migration: M2 bleibt nach der 2×2-MVP-Abnahme, mit eigener Freigabe, API-/Lizenzprüfung, Regressionstests und Funktionsschutz; CubeLab-Migration bleibt M3. Kein paralleler neuer Shared Core, keine neue Solver-Engine und keine Rust-Verschiebung. Architekturquelle: Cubistry #21.

Architecture source of truth: wstein/cubistry#21.

PuzlWerk exists (display brand PuzlWerk; technical scope @puzlwerk/*). ReScript cube core/mechanics/sticker model/codecs and a TypeScript viewer remain the shared target architecture; existence does not imply released packages or a migrated CubeAssembler consumer. M1 is the Cubistry 2×2 counter; M2 is CubeAssembler migration after M1.

Acceptance:

  • Document current cube mechanics, orientation, codecs and view3d ownership; map reusable modules to future PuzlWerk packages.
  • Preserve photo scanning, capture and assembly workflow in CubeAssembler, and preserve 2×2–7×7 behavior/test coverage.
  • AGENTS.md must direct agents to the upstream decision before extending shareable cube core/mechanics/viewer functionality; prevent a permanent parallel implementation.
  • Allow urgent fixes in existing code, with follow-up extraction tracking; no premature imports from a nonexistent package.
  • Make migration via small reviewed PRs, no automatic merge or destructive deletion.

Verbindliche MVP-Abgrenzung (27.10.2026)

  • M1 zuerst: Cubistry 2×2-Counter mit bestehendem 2×2-Solver, ladbaren Sticker-Assets und minimal nötigem ReScript-Core/Mechanik plus TypeScript-Viewer. Kein neuer Solver, keine allgemeine Constraint-Suche und keine vorgezogenen 3×3-Arbeiten.
  • PuzlWerk bleibt zuständig für neue gemeinsame Würfelmechanik/Sticker-/Viewer-Funktionalität. Bestehende App-Codes bleiben bis zu ihrer freigegebenen Migration funktionsfähig; nur nötige Bugfixes dort.
  • Dieses Repo ist nachgelagerter Consumer: Keine Migration vor M1-Abnahme. CubeAssembler = M2, CubeLab = M3. Relevante Änderungen am Schnittstellenvertrag mit Cubistry chore(deps-dev): bump @biomejs/biome from 2.5.14 to 2.5.15 #21 synchronisieren.
  • Nach M1 können 3×3-Orientierungs-/Constraint-Anforderungen untersucht werden; keine Implementierung vor Entscheidung. 6×6/7×7 offen halten.

Status reconciliation — 2026-10-28

  • Cubistry's 2×2 pilot PRs #20 and #22 are merged, as is the reused solver package in PuzlWerk #13; consumer integration remains open in Cubistry #23. Merged code is not by itself proof of every MVP DoD checkbox.
  • This issue's older CubeAssembler M2 / CubeLab M3 sequencing and newer AGENTS.md references to a gated 3×3 Supercube step differ. See the current reconciliation notice in Cubistry #21; do not assume that the new sequence silently authorizes CubeAssembler migration or a 3×3 implementation. Independent human approval remains required.
  • No code, solver, application or dependency migration is authorized by this tracking update.

Architecture status update — 2026-10-29 (supersedes the 2026-10-28 status paragraph)

  • Cubistry #23 and PuzlWerk #5 are closed as of 2026-10-28; shared 2×2-solver consumption is no longer the outstanding Phase B described in the old status. Cubistry #18 and the full five-item #21 DoD still require consolidated MVP acceptance; do not equate closed solver issues with acceptance of every MVP criterion.
  • A separate, user-approved bounded 3×3 calendar pilot is in Draft PRs (CubeLab #27, PuzlWerk #21, Cubistry #70). It does not authorize a CubeAssembler migration or settle its relative priority over M2/M3. The "superseding" sequence currently asserted in AGENTS.md needs reconciliation against the current canonical Cubistry #21.
  • Keep migration work gated on explicit approval, tested compatibility and functionality preservation. No shared-core duplication, code moves, merges or Rust changes authorized by this note.

Activity

  1. wstein commented on Oct 27, 2026

    @wstein
    OwnerAuthor

    Status · 27.10.2026

    Architektur abgestimmt; Implementierung/Migration nicht freigegeben oder abgeschlossen. Verbindliche Quelle: Cubistry #21. M1: 2×2-Counter mit vorhandenem Solver, minimalem ReScript-Core/Mechanik, TypeScript-Viewer und ladbaren, orientierungsbewussten Stickern. Keine neue Solver-Engine und kein vorgezogener 3×3-Pilot. M2: CubeAssembler-Migration erst nach MVP-Abnahme. M3: CubeLab danach, mit gesondertem Kompatibilitäts-/Lizenzreview. Bestehende App-Funktionalität erhalten und gemeinsame Logik nicht parallel ausbauen. Dokumentations-PRs für CubeAssembler, CubeLab und Cubacle sind offen und noch nicht gemergt. Ein täglicher Architekturabgleich ist eingerichtet; er ersetzt keine Implementierungsfreigabe.

  2. changed the title [-]chore(architecture): prepare migration to PuzWerk shared core/viewer[/-] [+]chore(architecture): prepare migration to PuzlWerk shared core/viewer[/+] on Oct 28, 2026
  3. wstein commented on Nov 4, 2026

    @wstein
    OwnerAuthor

    Architecture audit — 2026-11-04: Orbit64 V2 consolidation debt (documentation only)

    Verified current state: CubeAssembler PR #40 (state-token codec, merged 2026-10-31), #42 (color facelets, merged 2026-11-01) and #43 (picture facelets, merged 2026-11-01) added dedicated ReScript Orbit64 V2 code in src/cube/notation/. CubeLab #38–#40 merged parallel ReScript ports in src/State/. The existing Cubistry #21 target assigns shared notation/codecs to PuzlWerk's ReScript core, without long-lived duplicate shared engines.

    Decision/constraint: These merged, independently verified format ports are existing code, not evidence that the full M2/M3 migration has been approved, nor automatic proof that the copies should be deleted. Treat coexistence as tracked consolidation/interop debt: map the APIs, versions, frames, lossless picture-sticker semantics, provenance/licenses and cross-repo parity tests in M2 only after 2×2-counter M1 acceptance and separate owner approval. Decide shared implementation vs. bounded compatibility adapters there; preserve current CubeAssembler scanning, behavior and working tests. No more uncoordinated permanent shared-codec fork; do not move code as a side effect of this note.

    The open docs PR #41 already addresses unresolved viewer ownership; do not duplicate or bypass its review. The viewer conflict remains subject to owner decision. No code edit, Rust change, or merge in this audit.

  4. wstein commented on Nov 5, 2026

    @wstein
    OwnerAuthor

    Update 2026-11-05: the owner decided who owns the shared viewer; the notes above that describe the ownership as undecided are superseded.

    • The shared viewer is the separate package @puzlwerk/viewer in the PuzlWerk monorepo. It owns scene (camera/POV, light) and rendering without application knowledge. The CubeScene model (Cubistry #111) is proposed as its contract and is still open.
    • Direction: the viewer depends on the core; applications depend on the viewer.
    • Cubistry owns presentation, animation timing, themes, print, counters and calendar. CubeAssembler owns scan, camera and validation. CubeLab keeps its native WebGL viewport until its migration (M3) is approved separately. Cubacle stays a solver and does not depend on the viewer.
    • This is a target architecture, not a migration approval: each migration (CubeAssembler M2, Cubistry, CubeLab M3) needs its own owner approval.
    • Open: whether the orientation (rotation) of the whole cube belongs to the viewer or to Cubistry presentation (see Cubistry #111 and docs/SMART_ROTATION.md).

    Recorded in: cubistry#208, puzlwerk#24, cubacle#26, cube-assembler#44, cubelab#41.

  5. wstein commented on Nov 5, 2026

    @wstein
    OwnerAuthor

    Update 2026-11-05 (owner decision, supersedes the open rotation question in the comment above):

    • Puzzle orientation (semantic state: whole-cube rotations, fixed frame, center orientation) belongs to the application/core. It is delivered in the CubeScene contract as plain transformation data (for example a quaternion per group). #111 stays a proposal.
    • View orientation (camera, orbit, POV) and interpolation between supplied states belong to the viewer (@puzlwerk/viewer). The viewer knows no move notation and no application logic.
    • Still open: who owns the timing and easing of an animation. Proposal: the application supplies start and target, the viewer interpolates. Not decided.
    • Target architecture, not a migration approval. WASM stays undecided (#190).

    Recorded in cubistry#210. The CLI rendering of Cubacle (text, SVG icons, Kitty) stays in Cubacle (cubacle#29).

  6. wstein commented on Nov 17, 2026

    @wstein
    OwnerAuthor

    Owner decision, 2026-11-17 (multiple choice with the coordinator):

    1. Start WI1 (inventory and gap list of src/client/view3d/ against @puzlwerk/viewer, read-only) and feat(viewer): restore CubeAssembler source-mesh rendering in the native scene puzlwerk#87 in parallel.
    2. CubeAssembler is to be relicensed to AGPL-3.0-or-later, as a separate small PR first. The reviewer checks contributors and the EUPL-1.2 compatibility of the vendored Core.
    3. Viewer integration: direct use of @puzlwerk/viewer and the PuzlWerk core-viewer-bridge package. No app-owned adapter layer, no old/new switch. Missing translation goes into the shared package.
    4. M2 gate: a full-migration spike branch (draft PR) is approved. Merge and switch-over are decided by the owner after acceptance. This is not a full CubeAssembler M2 approval and it does not waive Counter M1 for the merge decision.

    Not authorized by this decision: changes on the default branch, a dependency or gitlink change before the spike PR is reviewed, deleting view3d/ before acceptance.

  7. wstein commented on Nov 18, 2026

    @wstein
    OwnerAuthor

    Architecture status reconciliation — 2026-11-18 (documentation only)

    The previous pre-M1 consumer gate now has a changed, verified implementation status; the binding order in Cubistry #21 has not changed.

    • CubeAssembler #60 (capture photo provenance) merged 2026-11-17 17:14 UTC and #61 (capture recovery using pinned private PuzlWerk ReScript Core) merged 17:23 UTC. The earlier architecture notes on #60 and #61 required a separately documented pre-M1 owner exception and physical/production-distribution acceptance before Ready/merge. The PR descriptions still state physical-owner acceptance is open; the verified repo discussions do not establish that those gates were resolved at merge. Technical review CLEAR/green CI are not equivalent to those approvals. Preserve the merged behavior; do not infer retroactive M1 acceptance or M2 authorization.
    • #63 relicensed the application to AGPL-3.0-or-later and merged 18:53 UTC, after fix(capture): preserve photo identity through cube review #60/feat(capture): recover rejected scans through shared Core review #61. Pages deployment on merges and the earlier MIT/EUPL combination create a historical distribution/license-provenance question, not a concluded legal violation; confirm with the owner/license reviewer rather than assuming that later relicensing resolves all earlier publication questions.
    • #62 merged the read-only inventory. The owner's 2026-11-17 decision explicitly permits only an M2 spike in a Draft branch, not the full migration merge or switch-over; M1 remains a merge gate. Draft #64 is the viewer comparison spike; Draft #65 documents third-party licenses. Neither is approved for merge merely because technical reviews are CLEAR.

    Owner decisions still required/documentation to locate: whether #60/#61's pre-M1 application consumption and physical/distribution gates were approved at merge, and when (if ever) to accept the viewer spike and authorize cut-over. M1 is still the existing-solver 2×2 Counter with shared ReScript core, TypeScript viewer and loadable/oriented sticker assets; then M2, then CubeLab M3. No code, status, branch or merge action was taken by this reconciliation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions