feat: initial Symphonia implementation foundation

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.gitignore
+.pytest_cache
+__pycache__
+*.py[cod]
+*.sqlite3
+*.db
+docs
+specs
+tests

.github/workflows/verify.yml

@@ -0,0 +1,73 @@
+name: Verify
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Check specification consistency
+        run: PYTHONPATH=. python tools/validate_specs.py
+      - name: Check patch whitespace
+        env:
+          PATCH_BASE: ${{ github.event.pull_request.base.sha || github.event.before }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          if [[ "$PATCH_BASE" =~ ^0+$ ]]; then
+            DEFAULT_REF="refs/remotes/origin/$DEFAULT_BRANCH"
+            if git show-ref --verify --quiet "$DEFAULT_REF"; then
+              if PATCH_BASE="$(git merge-base HEAD "$DEFAULT_REF")"; then
+                git diff --check "${PATCH_BASE}...HEAD"
+                exit 0
+              fi
+            fi
+            EMPTY_TREE="$(git hash-object -t tree /dev/null)"
+            git diff --check "$EMPTY_TREE" HEAD
+          else
+            git diff --check "${PATCH_BASE}...HEAD"
+          fi
+      - name: Run offline test suite
+        run: PYTHONPATH=src:. python -m unittest discover -s tests -v
+
+  ui-lit-spike:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs/development/ui-lit-spike
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: docs/development/ui-lit-spike/package-lock.json
+      - name: Install pinned spike dependencies
+        run: npm ci --ignore-scripts
+      - name: Check types
+        run: npm run check
+      - name: Check presentation boundary
+        run: npm run check-boundary
+      - name: Run pure fallback tests
+        run: npm test
+      - name: Build isolated UI spike
+        run: npm run build
+      - name: Inspect relative assets
+        run: npm run verify-output

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.coverage
+coverage.xml
+dist/
+build/
+node_modules/
+.venv/
+*.sqlite3
+*.db
+.repowise/
+graphify-out/

AGENTS.md

@@ -0,0 +1,14 @@
+## Product specifications and SDDs
+
+When creating, revising, reviewing, or implementing product behavior:
+
+1. Read [`specs/README.md`](specs/README.md) and the applicable SDD in full.
+2. Consult [`specs/catalog.json`](specs/catalog.json) for capability status, blockers, and evidence.
+3. Start new SDDs from [`specs/_template.md`](specs/_template.md). Adapt sections proportionally, but mark non-applicable concerns explicitly instead of deleting them silently.
+4. Keep global product/domain/architecture requirements in `docs/`; SDDs assemble those requirements into one vertical, implementation-driving capability contract. Resolve conflicts rather than choosing one document silently.
+5. Do not implement a capability whose SDD is not `Ready for implementation`, and do not begin production implementation without explicit owner approval even when the SDD is ready.
+6. Update the SDD, catalog evidence, tests, user/operator documentation, and relevant ADRs together when an observable or architectural contract changes.
+7. Include concrete user flows, states, failure/recovery behavior, security boundaries, a numeric test budget, acceptance scenarios, and requirement traceability.
+8. Treat provider documentation and community implementations as dated evidence, not permanent guarantees. Keep official API research separate from community implementation evidence.
+
+Until a repository-native specification validator is selected, every SDD change must at minimum pass the manual checks listed in `specs/README.md`.

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app/src \
+    SYMPHONIA_HOST=0.0.0.0 \
+    SYMPHONIA_PORT=8099 \
+    SYMPHONIA_DATABASE=/data/symphonia.sqlite3
+
+WORKDIR /app
+COPY src /app/src
+
+RUN addgroup --system symphonia \
+    && adduser --system --ingroup symphonia symphonia \
+    && mkdir -p /data \
+    && chown -R symphonia:symphonia /app /data
+
+USER symphonia
+VOLUME ["/data"]
+EXPOSE 8099
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD ["python", "-c", "import http.client,json,os,sys; host=os.getenv('SYMPHONIA_HOST','127.0.0.1').strip(); host={'0.0.0.0':'127.0.0.1','::':'::1'}.get(host,host); port=int(os.getenv('SYMPHONIA_PORT','8099')); base=os.getenv('SYMPHONIA_INGRESS_PATH','/').rstrip('/'); connection=http.client.HTTPConnection(host,port,timeout=2); connection.request('GET',f'{base}/ready'); response=connection.getresponse(); payload=json.loads(response.read()); sys.exit(response.status != 200 or payload.get('service') != 'symphonia' or payload.get('status') != 'ready')"]
+
+ENTRYPOINT ["python", "-m", "symphonia"]

Makefile

@@ -0,0 +1,14 @@
+.PHONY: verify specs test spike-storage
+
+specs:
+	PYTHONPATH=. python3 tools/validate_specs.py
+
+test:
+	PYTHONPATH=src:. python3 -m unittest discover -s tests -v
+
+spike-storage:
+	PYTHONPATH=src:. python3 tools/storage_recovery_spike.py --operations 1000
+
+verify: specs
+	git diff --check
+	$(MAKE) test

README.md

@@ -1,2 +1,69 @@
-# symphonia
-HomeAssistant App/Service to manage and enjoy your music
+# Symphonia
+
+Symphonia is a self-hosted, provider-independent music library hub, distributed primarily as a Supervisor-managed Home Assistant App. It is intended to help a person understand, move, and eventually synchronize their music across services such as Spotify and YouTube without treating any one provider as the source of the domain model.
+
+> Your music library belongs to you. Providers are places where representations of that music happen to exist.
+
+Symphonia is a library-management and interoperability project, not a new music player. Playback, recommendations, social features, transcoding, and multi-room audio are outside the initial scope. Its domain and application core remain independent of Home Assistant so the service can also run and be tested standalone; the deployment and integration pattern follows `vypdev/homeassistant-gateway`.
+
+## Project status
+
+**Implementation foundation stage. Provider adapters, durable import/copy execution, and an experimental Home Assistant App metadata scaffold exist; no published App image, complete UI, or OAuth flow is available yet.**
+
+The current work combines a reviewable source of truth with the first owner-approved, dependency-free domain/persistence slice. Official provider feasibility still needs validation: Google's public YouTube Data API can manage YouTube video playlists, but the research performed for this specification did not identify an official API exposing the complete YouTube Music library model.
+
+### Current adapter boundaries
+
+- Spotify: official playlist reads plus confirmed playlist creation and entry append operations, subject to connection capabilities and provider policy.
+- YouTube Data API: official video-playlist reads only; this is deliberately not represented as YouTube Music.
+- Apple Music: experimental official library-playlist reads using separate developer and Music User Token inputs; writes and OAuth wiring remain out of scope until their feasibility gates are closed.
+
+All adapters expose normalized identities and preserve unavailable/duplicate occurrences. Provider credentials are injected behind ports and are not accepted through App options, logs, or ordinary operation payloads.
+
+## Documentation
+
+Start with the [documentation map](docs/README.md). The horizontal specifications define shared product and architecture rules; the [SDD standard](specs/README.md) and [capability catalog](specs/CATALOG.md) turn those rules into reviewable vertical implementation contracts.
+
+| Area | Source of truth |
+| --- | --- |
+| Capability readiness and implementation contracts | [SDD catalog](specs/CATALOG.md) |
+| SDD lifecycle, template, and readiness gate | [SDD standard](specs/README.md) |
+| Vision, scope, journeys, requirements | [Product specification](docs/product/product-specification.md) |
+| Home Assistant-native UI and component contract | [UI specification](docs/product/home-assistant-ui-specification.md) and [UI foundation SDD](specs/home-assistant-native-ui.md) |
+| Non-production Home Assistant-adjacent UI review | [Synthetic UI fixture](docs/development/ui-spike/README.md) |
+| Non-production Lit/TypeScript/Vite feasibility | [Isolated build spike](docs/development/ui-lit-spike/README.md) |
+| Vocabulary, entities, identity, playlists | [Domain model](docs/domain/domain-model.md) |
+| System boundaries and operational qualities | [Architecture](docs/architecture/system-architecture.md) |
+| Provider contract and capability semantics | [Provider specification](docs/providers/provider-specification.md) |
+| Current official-provider evidence | [Provider research](docs/providers/provider-research.md) |
+| Existing Home Assistant music projects and design lessons | [Ecosystem review](docs/providers/home-assistant-ecosystem-review.md) |
+| Engineering and testing workflow | [Development specification](docs/development/development-specification.md) |
+| Decisions already accepted | [Architecture decisions](docs/decisions/README.md) |
+| Risks and unresolved choices | [Open questions](docs/open-questions.md) |
+
+## Product shape
+
+The intended first useful workflow is:
+
+1. A local user connects provider accounts.
+2. Symphonia imports provider playlists and track representations without losing provenance.
+3. It resolves provider tracks to provider-independent recordings, surfacing uncertainty rather than hiding it.
+4. The user reviews unresolved items and records durable manual decisions.
+5. The user previews and executes a one-time playlist copy.
+6. The operation history explains every match, omission, provider write, retry, and failure.
+
+Persistent synchronization follows only after copy semantics and official provider feasibility are understood.
+
+## Contributing during specification
+
+Use requirement identifiers in issues, SDDs, tests, and future commits. Material implementation work starts from the applicable cataloged SDD and its numeric verification budget. A change to accepted behavior must update the relevant horizontal specification and, when it changes an architectural decision, add or supersede an ADR. Do not infer a decision from an open question, and do not start production implementation until the SDD is ready and the owner explicitly approves it.
+
+Before opening a change, run `make verify`. It checks the SDD/catalog links and
+traceability, patch whitespace, and the offline test suite without provider
+accounts, Home Assistant, or network access.
+
+The two current evidence spikes can be run independently: `make spike-storage`
+exercises restart/lease recovery and SQLite backup validation, while the
+[OAuth callback spike](docs/development/oauth-callback-spike.md) documents the
+direct App-owned callback boundary. Both are research evidence, not published
+production endpoints.

addon/README.md

@@ -0,0 +1,16 @@
+# Symphonia Home Assistant App metadata
+
+This directory is an experimental Supervisor App metadata scaffold. It follows
+the App/service boundary used by `vypdev/homeassistant-gateway`:
+
+- management traffic is Ingress-only (`8099` is not mapped as a direct port);
+- only `/data` is persistent;
+- the App requests no Home Assistant or Supervisor API access; and
+- the service image runs the repository root `Dockerfile` as a non-root user.
+
+The metadata is not a published release yet. The image reference, supported
+architecture matrix, OAuth callback contract, Home Assistant-native UI,
+backup/restore behavior and release signing still require their SDD gates
+before stable publication. The future UI is governed by the
+[Home Assistant-native UI foundation](../specs/home-assistant-native-ui.md); the
+metadata scaffold does not imply that UI has been implemented.

addon/config.yaml

@@ -0,0 +1,23 @@
+name: Symphonia
+version: "0.1.0"
+slug: symphonia
+description: Provider-independent music library hub and playlist migration service
+url: https://github.com/vypdev/symphonia
+image: ghcr.io/vypdev/symphonia
+arch:
+  - amd64
+  - aarch64
+startup: application
+boot: auto
+stage: experimental
+init: false
+ingress: true
+ingress_port: 8099
+panel_icon: mdi:music-box-multiple
+panel_title: Symphonia
+map:
+  - data:rw
+options:
+  log_level: info
+schema:
+  log_level: list(debug|info|warning|error)

docs/README.md

@@ -0,0 +1,67 @@
+# Documentation map
+
+**Status:** baseline for review
+**Last reviewed:** 2026-09-20
+
+This documentation is the horizontal implementation contract for Symphonia. It deliberately separates product intent, domain rules, architecture, provider facts, accepted decisions, and unresolved choices. The vertical, capability-level contracts live in the [SDD catalog](../specs/CATALOG.md) and select from these shared rules without overriding them.
+
+## Sources of truth
+
+| Document | Owns | Does not own |
+| --- | --- | --- |
+| [SDD standard and catalog](../specs/README.md) | Capability boundaries, readiness, end-to-end design, numeric test budgets, acceptance and evidence | Shared product policy or silent overrides of horizontal specifications |
+| [Product specification](product/product-specification.md) | Outcomes, scope, journeys, product requirements | Entity design or technology choices |
+| [Home Assistant-native UI specification](product/home-assistant-ui-specification.md) | Cross-cutting UI direction, component families, host context, accessibility, responsive and visual compatibility requirements | Feature-specific content/state or frontend framework selection |
+| [Domain model](domain/domain-model.md) | Ubiquitous language, invariants, identity, copy and sync semantics | Provider API facts |
+| [System architecture](architecture/system-architecture.md) | Boundaries, execution model, security and operations | Final implementation stack |
+| [Provider specification](providers/provider-specification.md) | Provider port, capabilities, normalized errors | Claims about a specific API |
+| [Provider research](providers/provider-research.md) | Dated, sourced facts about provider APIs | Product policy or permanent architecture |
+| [Home Assistant music ecosystem review](providers/home-assistant-ecosystem-review.md) | Reusable patterns and cautions from existing HA music projects | Dependency selection or provider guarantees |
+| [Development specification](development/development-specification.md) | Specification workflow, testing and delivery gates | Product scope |
+| [Local quality audit](development/quality-audit.md) | Reproducible offline RepoWise/Graphify review and current architecture/test debt | A release or SDD readiness claim |
+| [ADRs](decisions/README.md) | Decisions that have actually been accepted | Proposals and guesses |
+| [Open questions](open-questions.md) | Decisions needed, assumptions, risk register, next design work | Accepted requirements |
+
+## Normative language
+
+`MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, and `MAY` are normative. Lowercase uses are explanatory. Each requirement has a stable identifier:
+
+| Prefix | Area |
+| --- | --- |
+| `SYM-PROD` | Product and user experience |
+| `SYM-UI` | Home Assistant-native UI and component compatibility |
+| `SYM-ACC` | Local and provider accounts |
+| `SYM-LIB` | Unified library |
+| `SYM-MATCH` | Identity resolution |
+| `SYM-PL` | Playlist copy |
+| `SYM-SYNC` | Persistent synchronization |
+| `SYM-PROV` | Provider abstraction |
+| `SYM-ARCH` | Architecture and persistence |
+| `SYM-JOB` | Background execution |
+| `SYM-SEC` | Security and credentials |
+| `SYM-OBS` | Observability |
+| `SYM-HA` | Home Assistant |
+| `SYM-TEST` | Testing |
+| `SYM-DEP` | Deployment |
+
+Requirement identifiers are never reused. Removed requirements remain in history and should be marked superseded rather than silently renumbered.
+
+## Status model
+
+- **Accepted**: an explicit product constraint or recorded ADR; implementation may rely on it.
+- **Proposed**: a reviewable direction; implementation must not treat it as settled.
+- **Open**: a choice or fact still requiring evidence or owner input.
+- **Research snapshot**: a dated external fact that must be revalidated before implementation.
+
+The current baseline is documentation for review, not approval to implement. The repository must remain free of production application code until the owner explicitly approves implementation.
+
+## Change workflow
+
+1. Link a change to one or more requirement identifiers.
+2. Select or create the capability SDD from the [catalog](../specs/CATALOG.md); use the [mandatory template](../specs/_template.md).
+3. Update product/domain specifications before or with the SDD when shared behavior changes.
+4. Record a durable, consequential decision as an ADR; do not use ADRs for routine coding choices.
+5. Keep provider facts in dated research and link to official sources.
+6. Move answered questions into requirements or ADRs and leave a pointer to the resolution.
+7. Do not implement until the SDD passes its readiness gate and the owner explicitly approves implementation.
+8. Add acceptance tests traceable to the affected requirements and update catalog evidence with the implementation.