@suluk/platform 0.1.9 → 0.2.0

package/README.md

@@ -0,0 +1,77 @@
+# @suluk/platform
+
+Write **one manifest**; the generator plans the shadcn-registry adds, generates the wired Hono entry, merges each module's
+provision fragment, and emits the whole scaffold (package.json / tsconfig / wrangler.toml / .env.example / …). The
+higher-level surface over the [Suluk registry](https://github.com/MahmoodKhalil57/suluk) + `@suluk/provision`.
+
+There are two authoring surfaces. The **legacy** one (C051) is a single object and is supported forever. The **C053** one
+splits a platform into a reusable **system** and a swappable **brand**, adds typed opts, and lets services **compose**.
+
+## The C053 model
+
+### A service is a common interface
+
+`defineService<SO, BO>({ id, mount, provision?, deps?, env?, serviceOpts?, brandOpts?, reads?, compose? })` — the shape a
+community shadcn registry extends. The 19 core services are exported as typed consts (`authService`, `creditsService`, …).
+
+### System vs brand
+
+```ts
+import { defineSystem, defineBrand, definePlatform, authService, creditsService, emailService } from "@suluk/platform";
+import { analyticsService } from "@acme/suluk-analytics"; // a community service
+
+export const system = defineSystem({
+  registry: "MahmoodKhalil57/suluk",
+  services: [authService, creditsService, emailService, analyticsService],
+  globalServiceOpts: { ENVIRONMENT: "production", TRUSTED_ORIGINS: "https://app.example" },
+  serviceOpts: { auth: { mcp: { loginPage: "…", consentPage: "…", resource: "…", scopes: ["credits:read"] } } }, // typed by id
+  wire: [{ id: "signup-grant", from: "auth.onUserCreated", to: "credits.grantOnSignup", with: { amount: 100 } }],
+});
+
+export const brand = defineBrand({
+  name: "app",
+  globalBrandOpts: { BRAND_NAME: "App", BASE_URL: "https://app.example", EMAIL_FROM: "hi@app.example" },
+});
+
+export default definePlatform({ system, brand });
+```
+
+A **system** (services + serviceOpts + globalServiceOpts + wiring) is the reusable, publishable template. A **brand**
+(brandOpts + globalBrandOpts) is thin and swappable — two businesses run the same system with different brands; the generated
+entry *code* is identical, only `wrangler.toml [vars]` differ.
+
+### The 2×2 opts matrix
+
+|  | per-service | global |
+|---|---|---|
+| **service axis** (how it works) | `serviceOpts` → the entry (mount opts) | `globalServiceOpts` (a service `reads` the keys it needs) |
+| **brand axis** (identity) | `brandOpts` → `[vars]` | `globalBrandOpts` → `[vars]` |
+
+`serviceOpts` is typed per service id off the imported service objects (or `CoreServiceOptsMap` for a string id) — a wrong
+opt is a compile error.
+
+### Composition (`wire`)
+
+An edge binds a producer **port** to a consumer **capability**. It renders **into the producer's existing mount-opt field**
+(e.g. `auth.onUserCreated`), not a separate statement — so it reuses a real seam and the hook closure gets a real `env`.
+`resolveWiring` validates presence, port/capability existence, JSON-safe params, safe identifiers, and acyclicity; fan-out
+(several wires on one port) composes in declaration order. A community service participates by offering a capability (fills a
+core port) or exposing its own.
+
+## CLI
+
+```sh
+suluk-platform            # generate from ./platform.config.ts (legacy OR { system, brand })
+suluk-platform --config <path>
+suluk-platform migrate    # print the { system, brand } split of a legacy config (a starting point)
+```
+
+`migrate` is byte-faithful: `liftLegacy` → the same generated app as the legacy manifest.
+
+## Guarantees
+
+- **Byte-identity.** A legacy manifest — and any `{ system, brand }` with no wire — regenerates the exact bytes the C051
+  generator produced (pinned by a golden test over the real 18-service reference app).
+- **Fail closed.** A missing registry, a wrong-typed wire param, or a colliding wire import throws at generate time, not in
+  the shipped app.
+- **Own the wiring, npm the logic** (C052). A community extends services *and* composition without forking `@suluk` logic.

package/bin/platform.ts

@@ -3,24 +3,36 @@
  * The @suluk/platform CLI (C051) — load `platform.config.ts`, run `shadcn add` per service, write the wired entry +
  * provision.config. Then `bun install && suluk-provision apply`.
  *
- *   suluk-platform            generate from ./platform.config.ts
+ *   suluk-platform            generate from ./platform.config.ts (legacy manifest OR a { system, brand } platform)
  *   --config <path>           a different manifest
+ *   suluk-platform migrate    print the C053 { system, brand } split of a legacy platform.config.ts (a starting point)
  */
 import { resolve, dirname } from "node:path";
 import { writeFile, mkdir, readFile } from "node:fs/promises";
 import { generatePlatform } from "../src/generate";
-import type { PlatformManifest } from "../src/manifest";
+import { isPlatform, type PlatformManifest, type Platform } from "../src/manifest";
+import { liftLegacy } from "../src/resolve";
 
 const argv = process.argv.slice(2);
 const ci = argv.indexOf("--config");
 const configPath = ci >= 0 ? argv[ci + 1] : "platform.config.ts";
 
-const mod = (await import(resolve(process.cwd(), configPath))) as { default?: PlatformManifest };
+const mod = (await import(resolve(process.cwd(), configPath))) as { default?: PlatformManifest | Platform };
 if (!mod.default) {
   console.error(`✗ ${configPath} has no default export (a definePlatform(...) result)`);
   process.exit(2);
 }
 
+// `migrate` — show the { system, brand } split of a legacy manifest (does not rewrite the file; copy the output in).
+if (argv[0] === "migrate") {
+  const platform = isPlatform(mod.default) ? mod.default : liftLegacy(mod.default);
+  console.log("// C053 { system, brand } split — a starting point; move brand-specific values into defineBrand:\n");
+  console.log("export const system = defineSystem(" + JSON.stringify(platform.system, null, 2) + ");");
+  console.log("export const brand = defineBrand(" + JSON.stringify(platform.brand, null, 2) + ");");
+  console.log("export default definePlatform({ system, brand });");
+  process.exit(0);
+}
+
 const run = (cmd: string, args: string[]): Promise<void> =>
   new Promise((res, rej) => {
     const p = Bun.spawn([cmd, ...args], { stdout: "inherit", stderr: "inherit", cwd: process.cwd() });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/platform",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "The platform generator (C051): write one `definePlatform` manifest → it plans the shadcn-registry adds, generates the wired Hono entry, and merges each module's provision fragment into a single provision.config. The manifest compiles to a shadcn-add list + a C047 provision.config; the generator runs the adds + `@suluk/provision`. Turns the Suluk backend registry into a one-command platform. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"
@@ -14,6 +14,7 @@
 "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
 "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
 "type": "module",
+"files": ["src", "bin", "README.md"],
 "main": "src/index.ts",
 "bin": {
 "suluk-platform": "bin/platform.ts"

package/src/catalog.ts

@@ -1,103 +1,26 @@
 /**
- * The catalog (C051) — the OSB "offerings": each service id → how to MOUNT its router into the Hono entry + where its
- * PROVISION fragment lives. This is the mapping the generator needs beyond `shadcn add` (which handles files/deps/order on
- * its own). Kept in sync with the registry's module set (C050). `app` is the base (no mount, no fragment).
+ * The catalog (C051) — each service id → how to MOUNT its router + where its PROVISION fragment lives. Since C053 this is a
+ * DERIVED VIEW of {@link CORE_SERVICES} (the common {@link Service} interface): `CATALOG[id] = toCatalogEntry(service)`, so
+ * the C051 generator reads the exact same shape it always did (the Phase-0 golden lock proves byte-identity) while the
+ * authoring surface is now the open Service model. Types + the core service set live in `service.ts`.
  */
+import { CORE_SERVICES, toCatalogEntry, type CatalogEntry, type EnvVar } from "./service";
 
-/** How a module contributes to the generated `src/index.ts`. */
-export type Mount =
-  | { kind: "base" } // the app skeleton — `createApp()`
-  | { kind: "middleware"; symbol: string; from: string } // e.g. `mountAuthRoutes(app)`
-  | { kind: "route"; path: string; symbol: string; from: string } // e.g. `app.route("/credits", creditsRoutes())`
-  | { kind: "dev" }; // dev/CI tooling (journeys, audit) — files only, no runtime mount, no provision fragment
+// re-export the shape types from their new home so `@suluk/platform`'s public surface + `plan.ts` are unchanged.
+export { CORE_SERVICES, toCatalogEntry, defineService } from "./service";
+export type { Mount, EnvVar, CatalogEntry, Service, Port, Capability, CompositionSurface, Schema } from "./service";
 
-/** An env var a module needs at runtime — drives the generated `.env.example` + the env-check preflight. Bindings (D1/KV)
- *  are NOT here (they live in wrangler.toml); only string env vars. */
-export interface EnvVar {
-  name: string;
-  /** the app WON'T work without it (the "minimum keys") — the env-check requires a non-empty value before it's happy. */
-  required?: boolean;
-  /** a credential (never commit) — shown commented in `.env.example` + flagged in the temp file. */
-  secret?: boolean;
-  /** a one-line hint shown as a comment in `.env.example`. */
-  hint?: string;
-}
+/** The offerings, derived from the core service set. `app` is the base (no mount symbol, no fragment). */
+export const CATALOG: Record<string, CatalogEntry> = Object.fromEntries(Object.entries(CORE_SERVICES).map(([id, s]) => [id, toCatalogEntry(s)]));
 
-export interface CatalogEntry {
-  /** how it mounts into the entry. */
-  mount: Mount;
-  /** the provision fragment export, if any (`InstanceSpec[]`). */
-  provision?: { symbol: string; from: string };
-  /** the module's npm deps BEYOND the always-present base (see BASE_DEPS) — its @suluk/* logic packages + any extras
-   *  (zod, better-auth). `shadcn add` also installs these; declaring them here lets the generator emit a complete,
-   *  from-the-manifest package.json (so platform.config.ts is the only hand-authored surface). Kept in sync with the
-   *  registry item's `dependencies`. */
-  deps?: string[];
-  /** the runtime env vars this module reads — the generator unions them into `.env.example` + the env-check preflight. */
-  env?: EnvVar[];
+// DRIFT GUARD: the derived view must expose exactly the core service ids (a dropped/renamed service would silently change
+// the generated app). Trivially true while CATALOG is derived, but asserted so a future hand-edit can't diverge unnoticed.
+{
+  const a = Object.keys(CORE_SERVICES).sort().join(",");
+  const b = Object.keys(CATALOG).sort().join(",");
+  if (a !== b) throw new Error(`platform: CATALOG drifted from CORE_SERVICES (${b} vs ${a})`);
 }
 
-export const CATALOG: Record<string, CatalogEntry> = {
-  app: { mount: { kind: "base" }, env: [{ name: "TRUSTED_ORIGINS", hint: "comma-separated browser origins allowed on /api/* (CORS)" }] },
-  auth: {
-    mount: { kind: "middleware", symbol: "mountAuthRoutes", from: "./auth" },
-    provision: { symbol: "authProvision", from: "./src/provision/auth" },
-    deps: ["better-auth", "@better-auth/api-key", "@better-auth/passkey", "@suluk/better-auth"],
-    env: [
-      { name: "BETTER_AUTH_SECRET", required: true, secret: true, hint: "session-signing key — `openssl rand -base64 32`" },
-      { name: "BETTER_AUTH_URL", hint: "your deployed origin, e.g. https://api.example.com" },
-      { name: "GOOGLE_CLIENT_ID", secret: true, hint: "optional — enables Google sign-in" },
-      { name: "GOOGLE_CLIENT_SECRET", secret: true, hint: "optional — pairs with GOOGLE_CLIENT_ID" },
-    ],
-  },
-  // the contract is a MIDDLEWARE mount: it installs the scope gate (enforceApiKeyScope) + GET /api/openapi.json. Place it
-  // after `auth` in the manifest so the gate runs after identity/apiKeyAuth set keyId/scopes. Derived + stateless.
-  contract: { mount: { kind: "middleware", symbol: "mountContract", from: "./routes/contract" }, deps: ["@suluk/hono", "zod"] },
-  // the API-as-MCP server + OAuth discovery + connections — a middleware mount (registers /api/mcp + /.well-known/*).
-  mcp: { mount: { kind: "middleware", symbol: "mountMcp", from: "./routes/mcp" }, provision: { symbol: "mcpProvision", from: "./src/provision/mcp" }, deps: ["@suluk/mcp", "better-auth"] },
-  // feature routes mount under /api/* — where the caller-resolution + cors + rate-limit middleware live (toolfactory parity).
-  credits: { mount: { kind: "route", path: "/api/credits", symbol: "creditsRoutes", from: "./routes/credits" }, provision: { symbol: "creditsProvision", from: "./src/provision/credits" }, deps: ["@suluk/credits"] },
-  keys: { mount: { kind: "route", path: "/api/keys", symbol: "keysRoutes", from: "./routes/keys" }, provision: { symbol: "keysProvision", from: "./src/provision/keys" }, deps: ["@suluk/keys"] },
-  billing: {
-    mount: { kind: "route", path: "/api/billing", symbol: "billingRoutes", from: "./routes/billing" },
-    provision: { symbol: "billingProvision", from: "./src/provision/billing" },
-    deps: ["@suluk/billing", "@suluk/payments", "@suluk/credits"],
-    env: [
-      { name: "STRIPE_SECRET_KEY", required: true, secret: true, hint: "your Stripe secret key" },
-      { name: "STRIPE_PUBLISHABLE_KEY", hint: "returned by GET /api/billing/payment-config" },
-    ],
-  },
-  cost: { mount: { kind: "route", path: "/api/cost", symbol: "costRoutes", from: "./routes/cost" }, provision: { symbol: "costProvision", from: "./src/provision/cost" }, deps: ["@suluk/cost"] },
-  erasure: { mount: { kind: "route", path: "/api/erasure", symbol: "erasureRoutes", from: "./routes/erasure" }, provision: { symbol: "erasureProvision", from: "./src/provision/erasure" }, deps: ["@suluk/better-auth"] },
-  email: {
-    mount: { kind: "route", path: "/api/email", symbol: "emailRoutes", from: "./routes/email" }, // stateless binding — no provision fragment (C052)
-    deps: ["@suluk/email"],
-    env: [
-      { name: "RESEND_API_KEY", secret: true, hint: "omit → the console provider (dev)" },
-      { name: "EMAIL_FROM", hint: "the from-address" },
-      { name: "BRAND_NAME", hint: "email template branding" },
-      { name: "BASE_URL", hint: "email link base" },
-      { name: "ENVIRONMENT", hint: '"production" → use Resend (else console)' },
-    ],
-  },
-  webhooks: {
-    mount: { kind: "route", path: "/api/webhooks", symbol: "webhooksRoutes", from: "./routes/webhooks" },
-    provision: { symbol: "webhooksProvision", from: "./src/provision/webhooks" },
-    deps: ["@suluk/payments"],
-    env: [{ name: "STRIPE_WEBHOOK_SECRET", required: true, secret: true, hint: "verifies inbound Stripe events (POST /api/webhooks/stripe)" }],
-  },
-  // cross-cutting MIDDLEWARE (apply globally via app.use, emitted before any route) — not routed resources.
-  "rate-limit": { mount: { kind: "middleware", symbol: "mountRateLimit", from: "./services/rate-limit" }, deps: ["@suluk/hono"] },
-  "rate-credit": { mount: { kind: "middleware", symbol: "mountRateCredit", from: "./services/rate-credit" } }, // credit-backed free-tier bucket (KV binding); base deps cover it
-  i18n: { mount: { kind: "middleware", symbol: "mountI18n", from: "./services/i18n" }, deps: ["@suluk/i18n"] },
-  reference: { mount: { kind: "route", path: "/api/reference", symbol: "referenceRoutes", from: "./routes/reference" }, deps: ["@suluk/reference"] }, // derived doc render — no provision
-  admin: { mount: { kind: "route", path: "/api/admin", symbol: "adminRoutes", from: "./routes/admin" }, deps: ["@suluk/credits"] }, // reads existing tables — no provision
-  logs: { mount: { kind: "route", path: "/api/logs", symbol: "logsRoutes", from: "./routes/logs" }, provision: { symbol: "logsProvision", from: "./src/provision/logs" } },
-  // dev/CI tooling — pulled in as files, no runtime mount, no provision fragment.
-  journeys: { mount: { kind: "dev" }, deps: ["@suluk/journeys"] },
-  audit: { mount: { kind: "dev" }, deps: ["@suluk/cockpit", "@suluk/harden"] },
-};
-
 /**
  * The always-present framework deps (every generated app: the Effect services + Hono entry + the merged provision.config
  * that imports mergeProvision from @suluk/platform + defineProvision from @suluk/provision). Union'd with each service's
@@ -134,10 +57,10 @@ export function resolveVersion(dep: string): string {
 
 /** The env vars the selected services need, de-duped by name (first declaration wins). Split with `.secret` into the
  *  `.env` secrets (the .env.temp lifecycle) vs the non-secret CONFIG (defined in platform.config.ts `vars` → wrangler `[vars]`). */
-export function collectEnv(services: string[]): EnvVar[] {
+export function collectEnv(services: string[], catalog: Record<string, { env?: EnvVar[] }> = CATALOG): EnvVar[] {
   const seen = new Set<string>();
   const out: EnvVar[] = [];
-  for (const s of services) for (const e of CATALOG[s]?.env ?? []) if (!seen.has(e.name)) (seen.add(e.name), out.push(e));
+  for (const s of services) for (const e of catalog[s]?.env ?? []) if (!seen.has(e.name)) (seen.add(e.name), out.push(e));
   return out;
 }
 

package/src/generate.ts

@@ -4,8 +4,9 @@
  * `run` + `write` are INJECTED (the CLI provides a real spawn + fs; a test provides recorders), so the orchestration is
  * testable. Stops short of `provision apply` — that's a live infra op the operator triggers.
  */
-import type { PlatformManifest } from "./manifest";
-import { planPlatform, mergePackageJson, mergeWranglerToml, type PlatformPlan } from "./plan";
+import { type PlatformManifest, type Platform, isPlatform } from "./manifest";
+import { liftSystemBrand } from "./resolve";
+import { planPlatform, mergePackageJson, mergeWranglerToml, mergeGitignore, type PlatformPlan } from "./plan";
 
 export interface GenerateOptions {
   /** run a command — the CLI spawns `bunx shadcn add <ref>`; a test records. */
@@ -25,9 +26,10 @@ export interface GenerateResult {
   written: string[];
 }
 
-export async function generatePlatform(manifest: PlatformManifest, opts: GenerateOptions): Promise<GenerateResult> {
+export async function generatePlatform(input: PlatformManifest | Platform, opts: GenerateOptions): Promise<GenerateResult> {
   const log = opts.log ?? (() => {});
   const read = opts.read ?? (async () => null);
+  const manifest = isPlatform(input) ? liftSystemBrand(input) : input;
   const plan = planPlatform(manifest);
   const written: string[] = [];
 
@@ -43,10 +45,14 @@ export async function generatePlatform(manifest: PlatformManifest, opts: Generat
   log("▸ writing wrangler.toml");
   await opts.write("wrangler.toml", mergeWranglerToml(plan.wranglerToml, await read("wrangler.toml")));
   written.push("wrangler.toml");
+  // .gitignore MERGES (append missing entries) — critically ensures .env/.env.temp are ignored even if the app already had
+  // a minimal .gitignore, so secrets are never committed. .env.example + the env-check are always (re)written (no values).
+  log("▸ writing .gitignore");
+  await opts.write(".gitignore", mergeGitignore(plan.gitignore, await read(".gitignore")));
+  written.push(".gitignore");
   for (const [file, content, always] of [
     ["tsconfig.json", plan.tsconfig, false],
     ["components.json", plan.componentsJson, false],
-    [".gitignore", plan.gitignore, false],
     [".env.example", plan.envExample, true], // a checked-in template (no values) — keep it current
     ["scripts/env-check.ts", plan.envCheck, true], // the .env.temp lifecycle preflight
   ] as const) {

package/src/index.ts

@@ -4,8 +4,14 @@
  * provision.config. The higher-level surface over C047's provision.config + the C050 registry: `services: ["auth",
  * "credits", "billing"]` → a whole backend. The generated `provision.config.ts` imports `mergeProvision` from here.
  */
-export { definePlatform, type PlatformManifest } from "./manifest";
+export { definePlatform, defineSystem, defineBrand, isPlatform, type PlatformManifest, type SystemManifest, type BrandManifest, type Platform, type ServiceRef, type WireDecl } from "./manifest";
+export { resolveNodeOpts, liftSystemBrand, liftLegacy, serviceId } from "./resolve";
+export { resolveWiring, groupImports, assertJsonSafe, validateIdentifier, lit, type Wiring, type WireImport } from "./wire";
+// C053 — the open Service interface (the common shape community registries extend): defineService + the core service set.
+export { defineService, optsType, CORE_SERVICES, toCatalogEntry, type Service, type Port, type Capability, type CompositionSurface, type Schema, type McpOAuthOpts, type AuthServiceOpts } from "./service";
+// the core services as named, typed consts — import these into `defineSystem({ services: [...] })` for typed opts by id.
+export { appService, authService, contractService, mcpService, creditsService, keysService, billingService, costService, erasureService, emailService, webhooksService, rateLimitService, rateCreditService, i18nService, referenceService, adminService, logsService, journeysService, auditService } from "./service";
 export { CATALOG, orderServices, collectEnv, resolveVersion, BASE_DEPS, ECOSYSTEM_VERSIONS, DEV_DEPS, type CatalogEntry, type Mount, type EnvVar } from "./catalog";
 export { mergeProvision } from "./merge";
-export { planPlatform, buildPackageJson, mergePackageJson, mergeWranglerToml, type PlatformPlan } from "./plan";
+export { planPlatform, buildPackageJson, mergePackageJson, mergeWranglerToml, mergeGitignore, type PlatformPlan } from "./plan";
 export { generatePlatform, type GenerateOptions, type GenerateResult } from "./generate";

package/src/manifest.ts

@@ -1,36 +1,119 @@
 /**
- * The platform manifest (C051) — the ONLY author-facing document. Name the registry + the services you want; the generator
- * compiles it to EVERYTHING: the shadcn-add list, the wired Hono entry, the merged provision.config, AND the scaffold config
- * (package.json with each module's deps — @suluk/* on "latest" so fixes flow via `bun update`, ecosystem pinned; plus
- * tsconfig.json + components.json). `platform.config.ts` is the single surface; regenerating keeps deps current + preserves
- * any deps/scripts you added. The higher-level surface over C047's provision.config: you say "auth, credits, billing" and
- * the catalog knows each one's component + provision fragment + npm deps.
+ * The platform manifest. TWO authoring surfaces:
+ *  - LEGACY {@link PlatformManifest} (C051) — `definePlatform({ name, registry, services, opts?, vars? })`. Kept FOREVER; the
+ *    C053 refactor keeps it a strict subset so an existing config regenerates byte-for-byte (the Phase-0 golden lock).
+ *  - C053 {@link SystemManifest} + {@link BrandManifest} — `definePlatform({ system, brand })`. A SYSTEM (services + their
+ *    serviceOpts + globalServiceOpts + composition) is the REUSABLE/PUBLISHABLE template; a BRAND (brandOpts + globalBrandOpts)
+ *    is thin + SWAPPABLE. `defineSystem` is GENERIC over the services TUPLE, so `serviceOpts` is typed per service id off the
+ *    imported service objects — no codegen. The new shape LOWERS into a legacy manifest (`liftSystemBrand`) and runs the same
+ *    generator.
  */
+import type { Service, Schema, CoreServiceOptsMap } from "./service";
+
+/** The C051 legacy manifest — still valid, still the byte-identity anchor. */
 export interface PlatformManifest {
   /** the app/repo name (used in the generated scaffold). */
   name: string;
   /** the shadcn registry, e.g. "MahmoodKhalil57/suluk". */
   registry: string;
-  /** the services to include, in mount order — resolved against the catalog. `app` + `auth` are implied if any is listed
-   *  but list them for clarity; the base + foundation always come first. */
+  /** the services to include, in mount order — resolved against the catalog. `app` + `auth` are implied if any is listed. */
   services: string[];
-  /**
-   * Per-service static OPTIONS passed to that service's mount in the generated entry (a plain JSON-serializable object).
-   * E.g. enable MCP OAuth: `opts: { auth: { mcp: { loginPage, consentPage, resource, scopes } } }` → the entry emits
-   * `mountAuthRoutes(app, {...})`. Only JSON-safe values (no functions/env-refs — edit the generated entry for those).
-   */
+  /** per-service static OPTIONS passed to that service's mount in the generated entry (JSON-serializable). */
   opts?: Record<string, Record<string, unknown>>;
-  /**
-   * NON-SECRET config values (`BASE_URL`, `EMAIL_FROM`, `TRUSTED_ORIGINS`, `ENVIRONMENT`, `STRIPE_PUBLISHABLE_KEY`, …) —
-   * defined HERE, in the committed manifest, and generated into `wrangler.toml` `[vars]`. SECRETS never go here; they live
-   * in `.env` (see the generated `.env.example` + the env-check preflight). Keyed by the env var name.
-   */
+  /** NON-SECRET config values → generated into `wrangler.toml` `[vars]`. SECRETS never go here (they live in `.env`). */
   vars?: Record<string, string>;
 }
 
-/** Validate + return the manifest (throws on an empty service list). */
-export function definePlatform(manifest: PlatformManifest): PlatformManifest {
-  if (!manifest.registry) throw new Error("platform: `registry` is required (e.g. \"MahmoodKhalil57/suluk\")");
-  if (!manifest.services?.length) throw new Error("platform: `services` must list at least one module");
-  return manifest;
+// ── C053: the open system/brand surface ──────────────────────────────────────────────────────────────────────────────
+
+/** A reference to a service: an imported {@link Service} object (fully typed) or a bare string id (resolved against the
+ *  catalog; opts typed as `unknown`). */
+export type ServiceRef = string | Service<any, any>;
+
+/** the service id of a ref (a Service object's literal `id`, or the string itself). */
+type IdOf<R> = R extends { id: infer Id extends string } ? Id : R extends string ? R : never;
+/** the serviceOpts value type a ref carries: from its `serviceOpts` marker (imported object); else the {@link
+ *  CoreServiceOptsMap} entry for a known core string id; else `unknown` for an unknown string; `{}` for a typed service
+ *  without opts. */
+type SoOf<R> = R extends { serviceOpts: Schema<infer SO> } ? SO : R extends keyof CoreServiceOptsMap ? CoreServiceOptsMap[R] : R extends string ? unknown : {};
+
+/**
+ * An inter-service composition EDGE (Phase 3). Declared here so a Phase-2 manifest's shape is forward-compatible; the
+ * resolver ignores `wire` until the Phase-3 engine lands. `from`/`to` are `"<service>.<port|capability>"`.
+ */
+export interface WireDecl {
+  id?: string;
+  from: string;
+  to: string;
+  with?: Record<string, unknown>;
+}
+
+/** A SYSTEM — the reusable, publishable template. Generic over the services tuple so `serviceOpts` is typed by service id. */
+export interface SystemManifest<T extends readonly ServiceRef[] = readonly ServiceRef[]> {
+  /** the single core registry, e.g. "MahmoodKhalil57/suluk". (Multi-registry alias map: `registries`, Phase 4.) */
+  registry?: string;
+  /** alias → registry map for multi-registry systems (Phase 4). `registries.core` is the default when `registry` is unset. */
+  registries?: Record<string, string>;
+  /** the services, in mount order — imported {@link Service} objects (typed) and/or string ids. */
+  services: T;
+  /** system-wide behaviour shared by services; a service receives the keys it names in `reads.globalService` (else inert). */
+  globalServiceOpts?: Record<string, unknown>;
+  /** per-service serviceOpts — TYPED by service id off the imported service objects. */
+  serviceOpts?: Partial<{ [K in T[number] as IdOf<K>]: SoOf<K> }>;
+  /** inter-service composition edges (Phase 3). */
+  wire?: WireDecl[];
+}
+
+/** A BRAND — thin, swappable per deployment. Carries the app identity + the brand-facing opts (→ `[vars]`). */
+export interface BrandManifest {
+  /** the deployment/app name (the wrangler + package name). Differs per brand of the same system. */
+  name: string;
+  /** brand identity shared by every service (BRAND_NAME, baseUrl, emailFrom, …) → `[vars]`. */
+  globalBrandOpts?: Record<string, unknown>;
+  /** per-service brand-facing opts → `[vars]`. */
+  brandOpts?: Record<string, Record<string, unknown>>;
+  /** brand-tunable EDGE params keyed by `wire.id` (Phase 3). */
+  wireBrandOpts?: Record<string, Record<string, unknown>>;
+}
+
+/** A bound platform = a system + a brand. */
+export interface Platform {
+  system: SystemManifest<any>;
+  brand: BrandManifest;
+}
+
+/** Author a SYSTEM. `const T` captures the services tuple so `serviceOpts` types resolve per service id. */
+export function defineSystem<const T extends readonly ServiceRef[]>(s: SystemManifest<T>): SystemManifest<T> {
+  if (!s.services?.length) throw new Error("defineSystem: `services` must list at least one service");
+  return s;
+}
+
+/** Author a BRAND. */
+export function defineBrand(b: BrandManifest): BrandManifest {
+  if (!b.name) throw new Error("defineBrand: `name` is required");
+  return b;
+}
+
+/**
+ * Validate + return a platform. Accepts BOTH the legacy {@link PlatformManifest} and the C053 `{ system, brand }` shape
+ * (discriminated on the `system` key). Overloaded so the return type matches the input surface.
+ */
+export function definePlatform(input: PlatformManifest): PlatformManifest;
+export function definePlatform(input: Platform): Platform;
+export function definePlatform(input: PlatformManifest | Platform): PlatformManifest | Platform {
+  if (isPlatform(input)) {
+    if (!input.system?.services?.length) throw new Error("platform: `system.services` must list at least one service");
+    if (!input.brand?.name) throw new Error("platform: `brand.name` is required");
+    // fail CLOSED on a missing registry (the legacy surface does), so every `adds` entry is `<registry>/<service>`.
+    if (!input.system.registry && !input.system.registries?.core) throw new Error('platform: `system.registry` (or `system.registries.core`) is required (e.g. "MahmoodKhalil57/suluk")');
+    return input;
+  }
+  if (!input.registry) throw new Error('platform: `registry` is required (e.g. "MahmoodKhalil57/suluk")');
+  if (!input.services?.length) throw new Error("platform: `services` must list at least one module");
+  return input;
+}
+
+/** Discriminate the C053 `{ system, brand }` shape from the legacy manifest. */
+export function isPlatform(input: PlatformManifest | Platform): input is Platform {
+  return typeof input === "object" && input !== null && "system" in input;
 }

package/src/plan.ts

@@ -3,8 +3,10 @@
  * generated `provision.config.ts` (importing + merging the fragments). No I/O; `generate` executes this. Testable to the
  * character.
  */
-import type { PlatformManifest } from "./manifest";
-import { CATALOG, orderServices, collectEnv, BASE_DEPS, DEV_DEPS, resolveVersion, type EnvVar } from "./catalog";
+import { type PlatformManifest, type Platform, isPlatform } from "./manifest";
+import { liftSystemBrand } from "./resolve";
+import { resolveWiring, groupImports, type Wiring } from "./wire";
+import { CATALOG, CORE_SERVICES, orderServices, collectEnv, BASE_DEPS, DEV_DEPS, resolveVersion, type EnvVar, type Service } from "./catalog";
 
 export interface PlatformPlan {
   services: string[];
@@ -31,17 +33,28 @@ export interface PlatformPlan {
   envCheck: string;
 }
 
-export function planPlatform(manifest: PlatformManifest): PlatformPlan {
+export function planPlatform(input: PlatformManifest | Platform): PlatformPlan {
+  // C053: a `{ system, brand }` platform lowers to the legacy manifest first, then the UNCHANGED lowering runs — so the
+  // legacy path is byte-for-byte identical and the new surface is sugar over it.
+  const manifest = isPlatform(input) ? liftSystemBrand(input) : input;
+  // the EFFECTIVE catalog = core services + any inline (community) Service objects a `{system,brand}` platform carries. It
+  // threads through EVERY emitter (mounts, provision, deps, env, wiring), so a community service contributes end-to-end. For
+  // the legacy path and an all-core `{system,brand}` it === CORE_SERVICES → the Phase-0 golden lock still holds byte-for-byte.
+  const catalog: Record<string, Service> = { ...CORE_SERVICES };
+  if (isPlatform(input)) for (const ref of input.system.services) if (typeof ref !== "string") catalog[ref.id] = ref;
   const services = orderServices(manifest.services);
-  const unknown = services.filter((s) => !CATALOG[s]);
+  const unknown = services.filter((s) => !catalog[s]);
   if (unknown.length) throw new Error(`platform: unknown service(s) [${unknown.join(", ")}] — not in the catalog`);
-  const env = collectEnv(services);
+  const env = collectEnv(services, catalog);
+  // resolve the wires (a `{system,brand}` platform may carry `wire`; a legacy manifest never does → no wiring → byte-identical).
+  const wiring = resolveWiring(services, isPlatform(input) ? input.system.wire ?? [] : [], catalog);
   return {
     services,
-    adds: services.map((s) => `${manifest.registry}/${s}`),
-    entry: buildEntry(services, manifest.opts),
-    provisionConfig: buildProvisionConfig(services),
-    packageJson: buildPackageJson(manifest.name, services),
+    // a service may override the registry it's pulled from (multi-registry); core services fall back to the system registry.
+    adds: services.map((s) => `${catalog[s].registry ?? manifest.registry}/${s}`),
+    entry: buildEntry(services, manifest.opts, wiring, catalog),
+    provisionConfig: buildProvisionConfig(services, catalog),
+    packageJson: buildPackageJson(manifest.name, services, catalog),
     tsconfig: buildTsconfig(),
     componentsJson: buildComponentsJson(),
     envExample: buildEnvExample(env),
@@ -137,6 +150,18 @@ function buildGitignore(): string {
   return ["node_modules/", ".env", ".env.temp", ".dev.vars", ".wrangler/", "dist/", ""].join("\n");
 }
 
+/** Merge the generated .gitignore into an existing one — APPEND any missing entries (never skip-if-present, so an app's
+ *  minimal .gitignore can't leave `.env`/`.env.temp` UNIGNORED and risk committing secrets). Dedup, preserve app entries. */
+export function mergeGitignore(generated: string, existing: string | null): string {
+  if (!existing) return generated;
+  const norm = (s: string) => s.trim().replace(/\/$/, "");
+  const have = new Set(existing.split("\n").map(norm).filter(Boolean));
+  const add = generated.split("\n").filter((l) => l.trim() && !have.has(norm(l)));
+  if (!add.length) return existing.endsWith("\n") ? existing : existing + "\n";
+  const base = existing.replace(/\n*$/, "");
+  return `${base}\n${add.join("\n")}\n`;
+}
+
 /** The `.env.temp` lifecycle preflight (run via `predev` / `bun run check`): if every REQUIRED secret is present (in `.env`
  *  or the process env), delete `.env.temp`; else write `.env.temp` from `.env.example` + report the missing keys + fail. */
 function buildEnvCheckScript(env: EnvVar[]): string {
@@ -181,9 +206,9 @@ process.exit(1);
 
 /** The framework baseline package.json — name from the manifest, the union of BASE + each service's deps (versions
  *  resolved: @suluk/* → "latest", ecosystem → pinned), + the toolchain devDeps + the regenerate/typecheck scripts. */
-export function buildPackageJson(name: string, services: string[]): string {
+export function buildPackageJson(name: string, services: string[], catalog: Record<string, Service> = CORE_SERVICES): string {
   const deps = new Set<string>(BASE_DEPS);
-  for (const s of services) for (const d of CATALOG[s]?.deps ?? []) deps.add(d);
+  for (const s of services) for (const d of catalog[s]?.deps ?? []) deps.add(d);
   const dependencies: Record<string, string> = {};
   for (const d of [...deps].sort()) dependencies[d] = resolveVersion(d);
   const pkg = {
@@ -269,33 +294,56 @@ function buildComponentsJson(): string {
   );
 }
 
-function buildEntry(services: string[], opts?: Record<string, Record<string, unknown>>): string {
+function buildEntry(services: string[], opts?: Record<string, Record<string, unknown>>, wiring?: Wiring, catalog: Record<string, Service> = CORE_SERVICES): string {
   const imports = ['import { createApp } from "./app";'];
   const middleware: string[] = [];
   const routes: string[] = [];
-  // per-service static options → a JSON literal passed to the mount (e.g. auth's mcp OAuth config). Empty ⇒ no 2nd arg.
+  const hooksByService = wiring?.hooksByService ?? {};
+  // every identifier bound at the top of the entry (base + each mount) → its module. A wire import that reuses a symbol from
+  // a DIFFERENT module would shadow/duplicate-declare it, so reject it (fail closed); a same-module re-import is deduped.
+  const bound = new Map<string, string>([["createApp", "./app"]]);
+  // a service's mount opts = its serviceOpts (JSON) + any wire-injected hook closures (raw code). With NO hooks, render is
+  // the EXACT legacy JSON.stringify path (byte-identical); with hooks, a mixed object literal (JSON values + code fields).
   const optOf = (s: string): string => {
-    const o = opts?.[s];
-    return o && Object.keys(o).length ? `, ${JSON.stringify(o)}` : "";
+    const so = opts?.[s];
+    const hooks = hooksByService[s];
+    if (!hooks || !Object.keys(hooks).length) {
+      return so && Object.keys(so).length ? `, ${JSON.stringify(so)}` : "";
+    }
+    const parts: string[] = [];
+    for (const [k, v] of Object.entries(so ?? {})) parts.push(`${JSON.stringify(k)}: ${JSON.stringify(v)}`);
+    for (const [k, code] of Object.entries(hooks)) parts.push(`${JSON.stringify(k)}: ${code}`);
+    return `, { ${parts.join(", ")} }`;
   };
   // TWO passes: ALL middleware mounts (app.use / handler) emit BEFORE any route mount, so a cross-cutting concern
   // (auth, rate-limit, i18n) applies to every route regardless of where it sits in the manifest.
   for (const s of services) {
-    const m = CATALOG[s].mount;
+    const m = catalog[s].mount;
     if (m.kind === "middleware") {
       imports.push(`import { ${m.symbol} } from "${m.from}";`);
+      bound.set(m.symbol, m.from);
       middleware.push(`${m.symbol}(app${optOf(s)});`);
     } else if (m.kind === "route") {
       imports.push(`import { ${m.symbol} } from "${m.from}";`);
+      bound.set(m.symbol, m.from);
       routes.push(`app.route("${m.path}", ${m.symbol}(${optOf(s).replace(/^, /, "")}));`);
     }
   }
+  // the wires' consumed capabilities need imports (e.g. Effect / Credits / CreditsLive / DbLive) — appended after the mounts,
+  // rejecting any that collides with a base/mount symbol from a different module (would break the generated entry).
+  const safeWireImports = (wiring?.imports ?? []).filter((imp) => {
+    const existing = bound.get(imp.symbol);
+    if (existing === undefined) return (bound.set(imp.symbol, imp.from), true);
+    if (existing !== imp.from) throw new Error(`wire: import symbol "${imp.symbol}" (from "${imp.from}") collides with an existing import from "${existing}" — rename the capability's export`);
+    return false; // same symbol + module already imported → dedup
+  });
+  for (const line of groupImports(safeWireImports)) imports.push(line);
   const body = ["const app = createApp();", ...middleware, ...routes];
   return `// AUTO-GENERATED by @suluk/platform from platform.config.ts — the wired Hono entry. Edit freely.\n${imports.join("\n")}\n\n${body.join("\n")}\n\nexport default app;\n`;
 }
 
-function buildProvisionConfig(services: string[]): string {
-  const frags = services.map((s) => CATALOG[s].provision).filter((p): p is NonNullable<typeof p> => !!p);
+function buildProvisionConfig(services: string[], catalog: Record<string, Service> = CORE_SERVICES): string {
+  const frags = services.map((s) => catalog[s].provision).filter((p): p is NonNullable<typeof p> => !!p);
   const imports = frags.map((f) => `import { ${f.symbol} } from "${f.from}";`);
   return [
     "// AUTO-GENERATED by @suluk/platform — the merged provision config. Run `suluk-provision apply`.",