chore(core-realtime): scaffold package

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/core-realtime/AGENTS.md

@@ -0,0 +1,19 @@
+# @repo/core-realtime
+
+Vendor-isolated realtime abstractions over Socket.IO. Feature packages depend only on the interfaces; only this package imports `socket.io`.
+
+See `docs/superpowers/specs/2026-05-08-realtime-design.md` for the full design and `docs/decisions/adr-016-realtime-layer.md` for the rationale (added during implementation).
+
+## Public exports
+
+- `IRealtimeBroadcaster` — server → client broadcasts
+- `IRealtimeServer` — lifecycle, used at app boot only
+- `IRealtimeAuthenticator` — connect-time identity attachment (cookie / header → user)
+- `IRealtimeHandlerRegistry` + `RealtimeHandlerRegistry` — inbound handler registration
+- `defineRealtimeChannel`, `RealtimeChannelDescriptor`, `ChannelScope`
+- `InMemoryRealtimeBroadcaster` (test/dev), `SocketIORealtimeBroadcaster`, `SocketIORealtimeServer` (production)
+- `CORE_REALTIME_SYMBOLS`
+
+## Boundary
+
+Tagged `core`. The only place in the repo where `import "socket.io"` is allowed is `src/socket-io-*.ts` here, plus `apps/*/server.ts`. Enforced by the ESLint rule `core-eslint/no-direct-socket-io`.

packages/core-realtime/eslint.config.js

@@ -0,0 +1,2 @@
+import baseConfig from "@repo/core-eslint/base";
+export default baseConfig;

packages/core-realtime/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@repo/core-realtime",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "socket.io": "^4.7.0",
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "payload": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "payload": { "optional": true }
+  },
+  "devDependencies": {
+    "@repo/core-eslint": "workspace:*",
+    "@repo/core-typescript": "workspace:*",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}

packages/core-realtime/src/index.ts

@@ -0,0 +1,2 @@
+// Public barrel — populated as components land in Phase 2.
+export {};

packages/core-realtime/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@repo/core-typescript/base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["src/**/*", "*.config.ts"]
+}

packages/core-realtime/turbo.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://turborepo.dev/schema.json",
+  "extends": ["//"],
+  "tags": ["core"]
+}

packages/core-realtime/vitest.config.ts

@@ -0,0 +1,9 @@
+import path from "node:path";
+import { mergeConfig } from "vitest/config";
+import { nodeVitestConfig } from "@repo/core-typescript/vitest.base.node";
+
+export default mergeConfig(nodeVitestConfig, {
+  resolve: {
+    alias: { "@": path.resolve(__dirname, "./src") },
+  },
+});