@jgengine/sql 0.10.0 → 0.12.0

package/README.md

@@ -1,3 +1,3 @@
 # @jgengine/sql
 
-Postgres persistence for the [JGengine](https://github.com/Noisemaker111/jgengine) host: `HostPersistence` over a structural pool interface (no hard `pg` dependency). AGPL-3.0-only.
+Postgres persistence for the [JGengine](https://github.com/Noisemaker111/jgengine) host: `HostPersistence` over a structural pool interface (no hard `pg` dependency). Apache-2.0.

package/dist/sqlPersistence.js

@@ -1,4 +1,4 @@
-import { clampLimit, trimFeedEntries } from "@jgengine/core/runtime/hostPersistence";
+import { clampLimit, FEED_RING_LIMIT } from "@jgengine/core/runtime/hostPersistence";
 import { applyRunReset } from "@jgengine/core/runtime/persistenceScope";
 const SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS jg_game_servers (
@@ -34,13 +34,15 @@ const SCHEMA_STATEMENTS = [
     PRIMARY KEY (game_id, scope, stat, server_id, user_id)
   )`,
     `CREATE INDEX IF NOT EXISTS jg_leaderboard_top ON jg_leaderboard_rows (game_id, scope, stat, value)`,
-    `CREATE TABLE IF NOT EXISTS jg_feed_buffers (
+    `CREATE TABLE IF NOT EXISTS jg_feed_entries (
     server_id text NOT NULL,
     action text NOT NULL,
+    seq bigserial NOT NULL,
+    entry jsonb NOT NULL,
     updated_at bigint NOT NULL,
-    entries jsonb NOT NULL,
-    PRIMARY KEY (server_id, action)
+    PRIMARY KEY (server_id, action, seq)
   )`,
+    `CREATE INDEX IF NOT EXISTS jg_feed_entries_order ON jg_feed_entries (server_id, action, seq)`,
 ];
 export async function ensureSchema(pool) {
     for (const statement of SCHEMA_STATEMENTS) {
@@ -127,7 +129,7 @@ export function sqlPersistence(pool, now = Date.now) {
                         await client.query(`DELETE FROM jg_world_chunks WHERE server_id = $1`, [reset.serverId]);
                     }
                     if (reset.wipeServerSession) {
-                        await client.query(`DELETE FROM jg_feed_buffers WHERE server_id = $1`, [reset.serverId]);
+                        await client.query(`DELETE FROM jg_feed_entries WHERE server_id = $1`, [reset.serverId]);
                         await client.query(`DELETE FROM jg_leaderboard_rows WHERE game_id = $1 AND server_id = $2`, [
                             reset.gameId,
                             reset.serverId,
@@ -143,7 +145,7 @@ export function sqlPersistence(pool, now = Date.now) {
                             await client.query(`DELETE FROM jg_world_chunks WHERE server_id = $1`, [serverId]);
                         }
                         if (reset.wipeServerSession) {
-                            await client.query(`DELETE FROM jg_feed_buffers WHERE server_id = $1`, [serverId]);
+                            await client.query(`DELETE FROM jg_feed_entries WHERE server_id = $1`, [serverId]);
                         }
                     }
                     if (reset.wipeServerSession) {
@@ -208,22 +210,23 @@ export function sqlPersistence(pool, now = Date.now) {
             ]);
         },
         async loadFeed({ serverId, action }) {
-            const result = await pool.query(`SELECT entries FROM jg_feed_buffers WHERE server_id = $1 AND action = $2`, [serverId, action]);
-            const row = result.rows[0];
-            return row === undefined ? [] : asJson(row.entries);
+            const result = await pool.query(`SELECT entry FROM jg_feed_entries WHERE server_id = $1 AND action = $2 ORDER BY seq ASC`, [serverId, action]);
+            return result.rows.map((row) => asJson(row.entry));
         },
         async appendFeed({ serverId, action, entry }) {
             let entries = [];
             await transact(async (client) => {
-                const result = await client.query(`SELECT entries FROM jg_feed_buffers WHERE server_id = $1 AND action = $2`, [serverId, action]);
-                const row = result.rows[0];
-                const existing = row === undefined ? [] : asJson(row.entries);
-                entries = trimFeedEntries([...existing, entry]);
-                await client.query(`INSERT INTO jg_feed_buffers (server_id, action, updated_at, entries)
-           VALUES ($1, $2, $3, $4)
-           ON CONFLICT (server_id, action) DO UPDATE SET
-             updated_at = EXCLUDED.updated_at,
-             entries = EXCLUDED.entries`, [serverId, action, now(), JSON.stringify(entries)]);
+                await client.query(`INSERT INTO jg_feed_entries (server_id, action, entry, updated_at) VALUES ($1, $2, $3, $4)`, [serverId, action, JSON.stringify(entry), now()]);
+                await client.query(`DELETE FROM jg_feed_entries
+           WHERE server_id = $1 AND action = $2
+           AND seq < (
+             SELECT seq FROM jg_feed_entries
+             WHERE server_id = $1 AND action = $2
+             ORDER BY seq DESC
+             LIMIT 1 OFFSET $3
+           )`, [serverId, action, FEED_RING_LIMIT - 1]);
+                const result = await client.query(`SELECT entry FROM jg_feed_entries WHERE server_id = $1 AND action = $2 ORDER BY seq ASC`, [serverId, action]);
+                entries = result.rows.map((row) => asJson(row.entry));
             });
             return entries;
         },

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jgengine/sql",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Postgres persistence for the JGengine host: implements HostPersistence over a structural pool interface (no hard pg dependency).",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "repository": {
@@ -13,7 +13,7 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "llms.txt"
+    "skills"
   ],
   "exports": {
     ".": {
@@ -31,7 +31,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.10.0"
+    "@jgengine/core": "^0.12.0"
   },
   "devDependencies": {
     "pg-mem": "^3.0.5"

package/skills/jgengine/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: jgengine
+description: Route game work to the smallest useful JGengine guidance set.
+---
+
+# JGengine intake and router
+
+Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+
+## 1. Establish the target
+
+Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
+
+- player point of view and controls
+- world shape and authored content
+- core loop, interaction, combat, and progression
+- solo, local, hosted, or persistent multiplayer
+- HUD/menu states and **custom** UI art direction (every game owns its presentation — no stock drop-in face)
+- one observable completion scenario
+
+For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+
+## 2. Select domains
+
+Load only rows the target needs. Do not preload every domain.
+
+| Need | Skill | Owner |
+| --- | --- | --- |
+| player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
+| metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
+| scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
+| runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
+| game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
+| targeting, stats, damage, effects, abilities, projectiles, loot | `jgengine-combat` | combat resolution |
+| HUD, menus, layout, accessibility, touch presentation | `jgengine-ui` | player-facing interface |
+| models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
+| authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
+
+World content routes editor-first: any request that adds, moves, restyles, or removes something visible in the world — however phrased ("design this world", "place the enemies", "make it look better") — starts in `jgengine-editor`; the other domains consume the authored document. Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
+
+## 3. Discover before designing
+
+Within each selected domain:
+
+1. Search `capabilities.md` by intent; it maps needs to imports.
+2. Open `api.md` only when exact signatures or export inventory are needed.
+3. Open the linked reference only for a deeper recipe or trap.
+4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
+
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+
+## 4. Build and finish
+
+Keep scene coordinates in the editor document, state serializable, randomness injected, and hot-path work bounded. Use `jgengine-verify` for evidence appropriate to the change. Inside this monorepo, `workflow` owns issue/PR completion. Visual polish work also uses the `jgengine-ui` quality reference.