uptd

pan-canon · pan-canon · commit 7f326fd20bd2 · 2026-01-12T17:38:31.000+03:00
diff --git a/README.md b/README.md
@@ -1,25 +1,89 @@
-╭────────────────────────╮  ╭────────╮  ╭──────────╮
-│ [Proto](../InterDeadProto) │  │  Core  │  │ [IT](../InterDeadIT) │
-╰────────────────────────╯  ╰════════╯  ╰──────────╯
+<pre>
+╔═════════════════════════════════════════════════════════════════════╗
+║                     INTERDEAD :: REPOSITORIES                       ║
+╠═════════════════════════════════════════════════════════════════════╣
+║ ○ <a href="https://github.com/Zhovten-Games/InterDeadReferenceLibrary">InterDead Reference Library (public)</a>                              ║
+║   Public reference library: documents and notes that are safe       ║
+║   to share outside the private workspace.                           ║
+║                                                                     ║
+║ ○ <a href="https://github.com/Zhovten-Games/InterDeadIT">InterDeadIT (website / entry point)</a>                               ║
+║   The website: the public entry point into the InterDead meta-verse.║
+║   Hosts the “About” and related public-facing materials.            ║
+║                                                                     ║
+║ > InterDeadCore (identity + EFBD core)                              ║
+║   Core modules used by the website: identity/auth and EFBD logic.   ║
+║   Published as packages and consumed by InterDeadIT.                ║
+║                                                                     ║
+║ ○ <a href="https://github.com/Zhovten-Games/PsyFramework">PsyFramework</a> (research / tooling)                                 ║
+║   Research and tooling repo referenced by the project; supporting   ║
+║   framework work that may be mentioned from public docs.            ║
+╠═════════════════════════════════════════════════════════════════════╣
+║                            INTERDEADIT                              ║
+║═════════════════════════════════════════════════════════════════════║
+║ InterDeadCore is the monorepo for shared InterDead domain packages. ║
+║ It keeps identity and EFBD scoring logic decoupled from             ║
+║ presentation, follows hexagonal architecture boundaries, and        ║
+║ ships reusable building blocks for downstream runtimes. Each        ║
+║ package is versioned independently, while the repository maintains  ║
+║ shared data contracts and operational notes so adapters remain      ║
+║ consistent across deployments. This layout differs from InterDeadIT,║
+║ which hosts a single website surface while consuming these packages ║
+║ as dependencies.                                                    ║
+║═════════════════════════════════╦═══════════════════════════════════║
+║    ECHO OF AN UNFADING MEMORY   ║   INTERDEAD WIKI (ALL LANGUAGES)  ║
+╠═════════════════════════════════╬═══════════════════════════════════╣
+║ <a href="https://interdead.phantom-draft.com/about/">READ (EN)</a>                       ║ <a href="https://interdead.fandom.com/wiki/InterDead_Wiki">READ (EN)</a>                         ║
+╠═════════════════════════════════╬═══════════════════════════════════╣
+║ <a href="https://interdead.phantom-draft.com/ru/about/">READ (RU)</a>                       ║ <a href="https://interdead.fandom.com/ru/wiki/Interdead_%D0%92%D0%B8%D0%BA%D0%B8">READ (RU)</a>                         ║
+╠═════════════════════════════════╬═══════════════════════════════════╣
+║ <a href="https://interdead.phantom-draft.com/uk/about/">READ (UK)</a>                       ║ <a href="https://interdead.fandom.com/uk/wiki/Main_Page">READ (UK)</a>                         ║
+╠═════════════════════════════════╬═══════════════════════════════════╣
+║ <a href="https://interdead.phantom-draft.com/ja/about/">READ (JA)</a>                       ║ <a href="https://interdead.fandom.com/ja/wiki/InterDead_Wiki">READ (JA)</a>                         ║
+║═════════════════════════════════╩═══════════════════════════════════║
+║                            CONTACT                                  ║
+╠═════════════════════════════════════════════════════════════════════╣
+║ <a href="https://www.linkedin.com/company/zhovten-games/">Zhovten Games — LinkedIn</a>                                            ║
+╚═════════════════════════════════════════════════════════════════════╝
+</pre>
 
-## Introduction
+Packages:
+- `@interdead/identity-core`: Discord-authenticated identity kernel with pluggable storage.
+- `@interdead/efbd-scale`: EFBD scoring domain for adaptive horror design.
 
-InterDeadCore is the monorepo that harmonizes the shared services of the metaverse once the prototype branched into independent packages. It keeps domain kernels decoupled from presentation, follows the hexagonal architecture, and ships reusable building blocks for identity, EFBD scoring, and auxiliary tooling.
+## Stack
 
-## Installation
+- TypeScript domain packages
+- Cloudflare Workers + D1 + KV (host-provided bindings)
+- Hexagonal architecture with ports-and-adapters
 
-Each package is versioned and published independently. Refer to the package-level README files for installation commands:
-- `efbd-scale`: D1/KV-aware EFBD scoring domain for adaptive horror design.
-- `identity-core`: Discord-authenticated identity kernel with pluggable storage.
+## Local dev
 
-## Usage Examples
+- Install dependencies per package: `npm install` inside `identity-core/` and `efbd-scale/`.
+- Run tests per package: `npm test` (and `npm run typecheck` where available).
 
-See the package READMEs for runnable snippets. A typical host registers the identity core and EFBD scale adapters in its IoC container, then wires presentation controllers in the site repo (`InterDeadIT`).
+## Deployment (high-level)
 
-## Additional Notes
+- Packages are released independently from the monorepo.
+- Downstream repositories (such as InterDeadIT) explicitly upgrade package versions.
+- See release details in the documentation index below.
 
-- The Fear Inversion Matrix reference is now kept in `wiki/fear_inversion_matrix.md` for easier cross-linking across packages.
-- Aligns with the narrative and deployment orchestrated by the landing site (`InterDeadIT`) and the prototype lore (`InterDeadProto`).
-- Contributions should preserve the ports-and-adapters layering to keep packages swappable across runtimes.
-- Release flow: bump a package with `npm version patch`, create and push a tag matching the package name (for example `identity-core-v0.1.6` or `efbd-scale-v0.1.3`), and ask downstream repos to upgrade explicitly (e.g., `npm install @interdead/identity-core@0.1.6`).
-- Shared D1 schema: the `profiles` table should exist with `profile_id TEXT PRIMARY KEY`, `data TEXT NOT NULL` (JSON identity aggregate plus auxiliary fields like `completedGames`), `last_cleanup_at TEXT`, `last_cleanup_timezone TEXT`, and `delete_count INTEGER DEFAULT 0`.
+## Conventions
+
+- Keep adapters thin and let domain services own the business logic.
+- Use object-oriented aggregates and shared base errors to keep responsibilities separated.
+- Preserve ports-and-adapters layering so packages remain swappable across runtimes.
+
+## Engineering standards
+
+Engineering standards: Canonical project-wide engineering ideals and development standards are maintained in the InterDead Reference Library (public): https://github.com/Zhovten-Games/InterDeadReferenceLibrary/tree/main/standards/development. This repository follows that canon; local notes here must not override or fork the shared standards.
+
+## Docs index
+
+Start here: [docs/index.md](docs/index.md)
+
+Key references:
+
+- [Architecture overview](docs/architecture/overview.md)
+- [Ports and events](docs/architecture/ports-and-events.md)
+- [Data contracts](docs/data/schemas.md)
+- [Release flow](docs/release/versioning-and-tags.md)
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,22 @@
+# InterDeadCore Documentation
+
+InterDeadCore is a monorepo of domain packages. This documentation expands on the short README and keeps architecture, data contracts, and release operations in a single place so downstream repos can adopt the core without copying infrastructure assumptions.
+
+## Architecture
+- [Overview](architecture/overview.md)
+- [Ports and events](architecture/ports-and-events.md)
+
+## Packages
+- [EFBD scale](packages/efbd-scale.md)
+- [Identity core](packages/identity-core.md)
+
+## Data contracts
+- [D1 schemas](data/schemas.md)
+- [KV conventions](data/kv-conventions.md)
+
+## Release
+- [Versioning and tags](release/versioning-and-tags.md)
+- [Downstream upgrades](release/downstream-upgrades.md)
+
+## Operations
+- [Cloudflare bindings](operations/cloudflare-bindings.md)
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
@@ -0,0 +1,25 @@
+# Architecture overview
+
+InterDeadCore contains the domain kernels that are shared across the InterDead ecosystem. Unlike InterDeadIT, which is a single website repository, Core is a monorepo where each package ships independently while still sharing the same architectural boundaries and data contracts.
+
+## Principles
+
+- **Hexagonal architecture**: domain services live at the center and communicate through ports that are implemented by adapters in host runtimes.
+- **Object-oriented modeling**: aggregates encapsulate state, inheritance is reserved for shared domain behavior, and explicit interfaces define what adapters must provide.
+- **Separation of tasks**: identity, EFBD scoring, and orchestration are kept in separate packages, each with its own service layer and persistence adapters.
+
+## What Core owns
+
+- Domain logic and services for identity and EFBD scoring.
+- Ports and event contracts consumed by host applications.
+- Canonical data shapes for D1 and KV storage.
+
+## What Core does not own
+
+- UI controllers, templates, or localized content.
+- Deployment pipelines for the public website.
+- Downstream orchestration code outside the core packages.
+
+## Reference artifacts
+
+The Fear Inversion Matrix is stored in the repository wiki at [`wiki/fear_inversion_matrix.md`](../../wiki/fear_inversion_matrix.md). Treat it as a reference asset that informs EFBD scoring and trigger definitions rather than an executable specification.
diff --git a/docs/architecture/ports-and-events.md b/docs/architecture/ports-and-events.md
@@ -0,0 +1,22 @@
+# Ports and events
+
+InterDeadCore exposes ports instead of framework-specific implementations. Host applications (such as InterDeadIT) provide adapters that satisfy these contracts.
+
+## Identity core ports
+
+- **OAuth provider port**: exchanges authorization codes for identities (Discord adapter by default).
+- **Profile repository port**: persists `ProfileMetadata` aggregates in D1 or another storage layer.
+- **Session store port**: stores login/session state in KV, memory, or a host-managed store.
+- **Event bus port**: notifies downstream adapters when identity events are emitted.
+
+## EFBD scale ports
+
+- **Scale repository port**: saves and queries axis scores for each profile.
+- **Trigger log repository port**: records triggers for replay and analytics.
+- **Clock port**: normalizes timestamps for trigger ingestion.
+- **Logger port**: receives operational telemetry from services.
+
+## Shared event expectations
+
+- Identity completion should emit a profile-ready event so EFBD adapters can initialize scoring.
+- Trigger ingestion should emit an axis-updated event for UI surfaces or telemetry.
diff --git a/docs/data/kv-conventions.md b/docs/data/kv-conventions.md
@@ -0,0 +1,18 @@
+# KV conventions
+
+The EFBD scale package can persist trigger logs to KV for analytics or replay. Use a predictable key format so downstream systems can enumerate and expire entries safely.
+
+## Trigger log key format
+
+```
+efbd-trigger-log:{profileId}:{timestamp}:{axis}
+```
+
+- `profileId`: the profile identifier.
+- `timestamp`: ISO or epoch timestamp (consistent with the ingestion clock).
+- `axis`: one of the `EBF-*` axis codes.
+
+## Retention recommendations
+
+- Retain trigger logs only as long as analytics requires.
+- Consider a TTL aligned with downstream reporting windows (for example, 30–90 days).
diff --git a/docs/data/schemas.md b/docs/data/schemas.md
@@ -0,0 +1,29 @@
+# D1 schemas
+
+InterDeadCore shares a small set of D1 tables across packages. These tables are owned by the host application but must conform to the schemas below so the core packages remain portable.
+
+## Profiles
+
+`profiles` stores the identity aggregate for each player.
+
+| column                | type    | notes                                              |
+| --------------------- | ------- | -------------------------------------------------- |
+| `profile_id`          | text    | primary key for the player profile.                |
+| `data`                | text    | JSON identity aggregate and auxiliary metadata.    |
+| `last_cleanup_at`     | text    | optional timestamp for cleanup automation.         |
+| `last_cleanup_timezone` | text  | optional timezone for cleanup scheduling.          |
+| `delete_count`        | integer | optional counter for delete operations.            |
+
+Minimum required columns are `profile_id` and `data`. The remaining columns are optional but recommended for operational tooling.
+
+## EFBD scale
+
+`efbd_scale` tracks axis scores per profile.
+
+| column           | type    | notes                                   |
+| ---------------- | ------- | --------------------------------------- |
+| `profile_id`     | text    | foreign key to the host profile record. |
+| `axis_code`      | text    | one of the `EBF-*` codes.               |
+| `score`          | integer | cumulative score per axis.              |
+| `trigger_source` | text    | latest trigger origin identifier.       |
+| `updated_at`     | text    | ISO timestamp of the last update.       |
diff --git a/docs/operations/cloudflare-bindings.md b/docs/operations/cloudflare-bindings.md
@@ -0,0 +1,23 @@
+# Cloudflare bindings
+
+InterDeadCore packages expect certain Cloudflare bindings when hosted in Workers or Pages functions. Align the binding names below with your deployment configuration.
+
+## Required bindings
+
+- **D1**: `INTERDEAD_CORE` for the shared database (`profiles` and `efbd_scale`).
+- **KV**: `INTERDEAD_CORE_KV` for trigger logs and session state (if enabled).
+
+## Environment variables
+
+- `IDENTITY_DISCORD_CLIENT_ID`
+- `IDENTITY_DISCORD_CLIENT_SECRET`
+- `IDENTITY_DISCORD_REDIRECT_URI`
+
+## Optional bindings
+
+- Alternate D1 bindings for staging or localized testing.
+- Custom KV namespaces for analytics retention experiments.
+
+## Downstream notes (InterDeadIT)
+
+- The InterDeadIT `interdead-auth` worker expects the KV binding name `IDENTITY_KV` for the same trigger-log persistence and caching behaviors.
diff --git a/docs/packages/efbd-scale.md b/docs/packages/efbd-scale.md
@@ -0,0 +1,36 @@
+# EFBD scale package
+
+`@interdead/efbd-scale` is the EFBD (Echoed Big Five of Dread) scale package. It ingests triggers from mini-games, persists axis scores, and exposes query helpers for host runtimes.
+
+## Responsibilities
+
+- Ingest EFBD triggers per profile and update axis scores.
+- Clamp scores to maintain consistent bounds.
+- Provide query services for snapshots and axis inspection.
+
+## Axis codes
+
+- `EBF-SOCIAL`
+- `EBF-MIND`
+- `EBF-DECLINE`
+- `EBF-EXPOSURE`
+- `EBF-ABANDON`
+
+The hyphenated strings above are the canonical persisted codes. TypeScript uses underscore enum identifiers (for example, `AxisCode.EBF_SOCIAL`) while the enum values remain the hyphenated strings (for example, `"EBF-SOCIAL"`).
+
+## Key services
+
+- `ScaleIngestionService` for ingesting triggers.
+- `ScaleQueryService` for reading snapshots.
+- Repository interfaces for scales and trigger logs.
+
+## Expected adapters
+
+- Scale repository adapter backed by D1 or equivalent storage.
+- Trigger log repository adapter backed by KV or external telemetry storage.
+- Clock and logger adapters for runtime control.
+
+## Integration notes
+
+- Scores increment by `+1` per trigger and clamp at `100`.
+- Use shared data contracts from [Data contracts](../data/schemas.md) and [KV conventions](../data/kv-conventions.md).
diff --git a/docs/packages/identity-core.md b/docs/packages/identity-core.md
@@ -0,0 +1,28 @@
+# Identity core package
+
+`@interdead/identity-core` is the headless identity kernel that wires Discord OAuth with pluggable storage adapters. It keeps presentation concerns out of the core while exposing services and factories that host applications can register in their own containers.
+
+## Responsibilities
+
+- Authenticate players via Discord OAuth.
+- Maintain the profile aggregate that stores identity metadata.
+- Emit events for downstream services (EFBD scale, UI, analytics).
+
+## Key services
+
+- `createIdentityCore` factory that composes domain services and adapters.
+- `LinkService` for OAuth entry and completion flows.
+- `ProfileMetadata` aggregate for player identity state.
+
+## Expected adapters
+
+- OAuth adapter for Discord (or custom OAuth provider in staging).
+- Profile repository adapter backed by D1 or equivalent storage.
+- Session store adapter for OAuth state and nonce persistence.
+- Event bus and logger adapters for runtime integration.
+
+## Integration notes
+
+- Store OAuth credentials in environment variables.
+- Use adapters to enforce task separation between domain logic and platform-specific infrastructure.
+- Review the D1 schema details in [Data contracts](../data/schemas.md).
diff --git a/docs/release/downstream-upgrades.md b/docs/release/downstream-upgrades.md
@@ -0,0 +1,17 @@
+# Downstream upgrades
+
+InterDeadIT and other downstream repositories explicitly install core packages. After publishing a new version, update downstream packages intentionally to avoid unplanned changes.
+
+## Recommended workflow
+
+1. Announce the new core package version to downstream maintainers.
+2. Update the dependency in the downstream repo, for example:
+   ```bash
+   npm install @interdead/identity-core@0.1.6
+   ```
+3. Verify that runtime adapters still satisfy the ports in the updated package.
+4. Run downstream test and deployment checks.
+
+## Monorepo note
+
+Because InterDeadCore is a monorepo, tags and release notes are the primary signals for downstream teams. Avoid assuming that every commit is ready for consumption outside the core packages.
diff --git a/docs/release/versioning-and-tags.md b/docs/release/versioning-and-tags.md
diff --git a/efbd-scale/README.md b/efbd-scale/README.md
diff --git a/identity-core/README.md b/identity-core/README.md
