@oimlsmart/platform-server 0.2.11 → 0.2.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OIML SMART project contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/migrations/0027_notify_mentions_saved.sql

@@ -0,0 +1,33 @@
+-- TODO.notify/05's remainders (platform-server#25 — the smart side's
+-- TODO.notify/00 banner: the mentions-parse half and the per-event saved
+-- flag ride a KERNEL migration). Expand-only per the migration contract
+-- (append, never renumber): two columns, both NULL-defaulted, existing
+-- rows untouched.
+--
+--   events.mentions            the act's @user mentions (TODO.notify/00's
+--                              "Mentions land as the 'mentioned' reason"):
+--                              a JSON array of the mentioned USER IDS,
+--                              resolved by the comment surfaces' parse at
+--                              event time and recorded ON THE ROW — the
+--                              inbox feed computes its reasons at READ,
+--                              and a mention is a fact of the act, never
+--                              re-derivable from the entity. NULL = none
+--                              (every pre-0027 row, every mention-free
+--                              act). The recipient resolution's
+--                              'mentioned' candidate class reads it; the
+--                              mutes and the visibility gate still win
+--                              (a mention never widens access).
+--
+--   notify_inbox_state.saved_at  the per-event saved flag (TODO.notify/
+--                              00's inbox state "read / done / saved",
+--                              the GitHub Save): stamps at the save act,
+--                              clears at the un-save. Independent of
+--                              read/done — a saved row that is done stays
+--                              saved in the archive. The marker row's
+--                              posture is unchanged (the user's own state,
+--                              lazily written, no foreign keys).
+--
+-- The schema's SQLite mirror (src/store/sqlite/schema.sql) updates in
+-- the same commit; test/migrations.test.ts fails the package otherwise.
+ALTER TABLE events ADD COLUMN mentions TEXT;
+ALTER TABLE notify_inbox_state ADD COLUMN saved_at TEXT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimlsmart/platform-server",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "The OIML SMART platform server kernel: the store seam (ServerStore + the D1 and SQLite implementations), the canonical D1 migration set both deployments apply, the instance profile, the mailer, the RBAC map, the OIDC/OAuth client cones, and the shared role/permission vocabulary. Consumed by the smart monorepo (browser/) and the identity service.",
   "type": "module",
   "repository": {

package/src/store/d1.ts

@@ -438,8 +438,9 @@ const INSTRUMENT_REGISTRATION_INSERT_SQL = `INSERT OR IGNORE INTO instrument_reg
 
 /** The event append's INSERT … RETURNING * — ONE textual source for
  *  appendEvent and appendEvents alike (the stored row — seq + the
- *  default at — answers off the write itself). */
-const EVENT_INSERT_SQL = 'INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?) RETURNING *'
+ *  default at — answers off the write itself). The mentions column
+ *  (migration 0027) lands from the input, NULL when absent. */
+const EVENT_INSERT_SQL = 'INSERT INTO events (id, domain, entity_id, action, payload, mentions) VALUES (?, ?, ?, ?, ?, ?) RETURNING *'
 
 export class D1ServerStore implements ServerStore {
   /** The RAW binding — the ensure memos (and d1StoreFor's map) key on
@@ -3600,6 +3601,7 @@ export class D1ServerStore implements ServerStore {
       entityId: row.entity_id as string,
       action: row.action as string,
       payload: row.payload as string,
+      mentions: (row.mentions as string | null) ?? null,
       at: row.at as string,
     }
   }
@@ -3611,7 +3613,7 @@ export class D1ServerStore implements ServerStore {
     // two round trips per event, halved).
     const row = await this.stmt(
       EVENT_INSERT_SQL,
-      input.id, input.domain, input.entityId, input.action, input.payload,
+      input.id, input.domain, input.entityId, input.action, input.payload, input.mentions ?? null,
     ).first<Record<string, unknown>>()
     return D1ServerStore.toPlatformEvent(row!)
   }
@@ -3630,7 +3632,7 @@ export class D1ServerStore implements ServerStore {
       const chunk = events.slice(i, i + APPEND_EVENTS_CHUNK)
       const statements = chunk.map(e => this.stmt(
         EVENT_INSERT_SQL,
-        e.id, e.domain, e.entityId, e.action, e.payload,
+        e.id, e.domain, e.entityId, e.action, e.payload, e.mentions ?? null,
       ))
       const results = await this.db.batch(statements)
       for (const res of results) {
@@ -3842,6 +3844,7 @@ export class D1ServerStore implements ServerStore {
       eventId: row.event_id as string,
       readAt: (row.read_at as string | null) ?? null,
       doneAt: (row.done_at as string | null) ?? null,
+      savedAt: (row.saved_at as string | null) ?? null,
       createdAt: row.created_at as string,
     }
   }
@@ -3860,6 +3863,7 @@ export class D1ServerStore implements ServerStore {
     eventId: string
     read?: boolean
     done?: boolean
+    saved?: boolean
   }): Promise<NotifyInboxState> {
     await this.stmt(
       'INSERT OR IGNORE INTO notify_inbox_state (user_id, event_id) VALUES (?, ?)',
@@ -3877,6 +3881,12 @@ export class D1ServerStore implements ServerStore {
         input.done ? 1 : 0, input.userId, input.eventId,
       ).run()
     }
+    if (input.saved !== undefined) {
+      await this.stmt(
+        "UPDATE notify_inbox_state SET saved_at = CASE WHEN ? THEN datetime('now') ELSE NULL END WHERE user_id = ? AND event_id = ?",
+        input.saved ? 1 : 0, input.userId, input.eventId,
+      ).run()
+    }
     const row = await this.stmt(
       'SELECT * FROM notify_inbox_state WHERE user_id = ? AND event_id = ?',
       input.userId, input.eventId,

package/src/store/sqlite/events.ts

@@ -18,6 +18,7 @@ interface EventRow {
   entity_id: string
   action: string
   payload: string
+  mentions: string | null
   at: string
 }
 
@@ -29,17 +30,23 @@ function toPlatformEvent(row: EventRow): PlatformEvent {
     entityId: row.entity_id,
     action: row.action,
     payload: row.payload,
+    mentions: row.mentions,
     at: row.at,
   }
 }
 
+/** The event append's INSERT … RETURNING * — ONE textual source for
+ *  appendEvent and appendEvents alike (the D1 half's EVENT_INSERT_SQL's
+ *  twin; the stored row answers off the write itself). The mentions
+ *  column (migration 0027) lands from the input, NULL when absent. */
+const EVENT_INSERT_SQL = 'INSERT INTO events (id, domain, entity_id, action, payload, mentions) VALUES (?, ?, ?, ?, ?, ?) RETURNING *'
+
 export function appendEvent(input: EventWriteInput): PlatformEvent {
   // ONE statement: RETURNING answers the stored row (seq + the default
   // at) off the INSERT itself — the same halving as the D1 half.
   return toPlatformEvent(
-    getDb().prepare(
-      `INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?) RETURNING *`,
-    ).get(input.id, input.domain, input.entityId, input.action, input.payload) as EventRow,
+    getDb().prepare(EVENT_INSERT_SQL)
+      .get(input.id, input.domain, input.entityId, input.action, input.payload, input.mentions ?? null) as EventRow,
   )
 }
 
@@ -55,15 +62,13 @@ export function appendEvent(input: EventWriteInput): PlatformEvent {
 export function appendEvents(events: readonly EventWriteInput[]): PlatformEvent[] {
   if (events.length === 0) return []
   const db = getDb()
-  const insert = db.prepare(
-    `INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?) RETURNING *`,
-  )
+  const insert = db.prepare(EVENT_INSERT_SQL)
   const out: PlatformEvent[] = []
   for (let i = 0; i < events.length; i += APPEND_EVENTS_CHUNK) {
     const chunk = events.slice(i, i + APPEND_EVENTS_CHUNK)
     db.transaction(() => {
       for (const e of chunk) {
-        out.push(toPlatformEvent(insert.get(e.id, e.domain, e.entityId, e.action, e.payload) as EventRow))
+        out.push(toPlatformEvent(insert.get(e.id, e.domain, e.entityId, e.action, e.payload, e.mentions ?? null) as EventRow))
       }
     })()
   }

package/src/store/sqlite/notify.ts

@@ -205,6 +205,7 @@ interface InboxStateRow {
   event_id: string
   read_at: string | null
   done_at: string | null
+  saved_at: string | null
   created_at: string
 }
 
@@ -214,6 +215,7 @@ function toNotifyInboxState(row: InboxStateRow): NotifyInboxState {
     eventId: row.event_id,
     readAt: row.read_at,
     doneAt: row.done_at,
+    savedAt: row.saved_at,
     createdAt: row.created_at,
   }
 }
@@ -233,6 +235,7 @@ export function putNotifyInboxState(input: {
   eventId: string
   read?: boolean
   done?: boolean
+  saved?: boolean
 }): NotifyInboxState {
   const db = getDb()
   db.prepare(
@@ -246,6 +249,10 @@ export function putNotifyInboxState(input: {
     db.prepare("UPDATE notify_inbox_state SET done_at = CASE WHEN ? THEN datetime('now') ELSE NULL END WHERE user_id = ? AND event_id = ?")
       .run(input.done ? 1 : 0, input.userId, input.eventId)
   }
+  if (input.saved !== undefined) {
+    db.prepare("UPDATE notify_inbox_state SET saved_at = CASE WHEN ? THEN datetime('now') ELSE NULL END WHERE user_id = ? AND event_id = ?")
+      .run(input.saved ? 1 : 0, input.userId, input.eventId)
+  }
   return toNotifyInboxState(
     db.prepare('SELECT * FROM notify_inbox_state WHERE user_id = ? AND event_id = ?')
       .get(input.userId, input.eventId) as InboxStateRow,

package/src/store/sqlite/schema.sql

@@ -149,7 +149,12 @@ CREATE INDEX IF NOT EXISTS idx_entity_changes_store_seq ON entity_changes (store
 -- envelope (the summary line, the deep link, the actors, the entity's
 -- store for the read-time visibility gate). seq is the feed cursor;
 -- written inside the acting request's envelope, never blocking the
--- triggering flow (the mailer doctrine).
+-- triggering flow (the mailer doctrine). mentions (migration 0027,
+-- TODO.notify/05's remainders) is the act's @user mentions as a JSON
+-- array of user ids, resolved by the comment surfaces' parse at event
+-- time and recorded ON THE ROW — a mention is a fact of the act, never
+-- re-derivable from the entity at the feed's read-time computation.
+-- NULL = none.
 CREATE TABLE IF NOT EXISTS events (
   seq INTEGER PRIMARY KEY AUTOINCREMENT,
   id TEXT UNIQUE NOT NULL,
@@ -157,6 +162,7 @@ CREATE TABLE IF NOT EXISTS events (
   entity_id TEXT NOT NULL,
   action TEXT NOT NULL,
   payload TEXT NOT NULL,
+  mentions TEXT,
   at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 CREATE INDEX IF NOT EXISTS idx_events_domain_entity ON events (domain, entity_id);
@@ -219,7 +225,10 @@ CREATE TABLE IF NOT EXISTS notify_preferences (
 -- TODO.notify/03 — the inbox state: the per-user per-event read markers
 -- (migration 0014). One row per (user, event), written lazily at the
 -- first act on the inbox row: read_at stamps the mark-read, done_at the
--- archive (a done row leaves the feed; the marker keeps the state). The
+-- archive (a done row leaves the feed; the marker keeps the state),
+-- saved_at the per-event saved flag (migration 0027, TODO.notify/05's
+-- remainders — the GitHub Save, independent of read/done: a saved row
+-- that is done stays saved in the archive). The
 -- feed itself is COMPUTED at read (events × the user's rules × the
 -- visibility gate) — this table is the state the computation joins, and
 -- a marker on a wiped event simply never joins (the user's state is
@@ -233,6 +242,7 @@ CREATE TABLE IF NOT EXISTS notify_inbox_state (
   event_id TEXT NOT NULL,
   read_at TEXT,
   done_at TEXT,
+  saved_at TEXT,
   created_at TEXT NOT NULL DEFAULT (datetime('now')),
   PRIMARY KEY (user_id, event_id)
 );

package/src/store/sqlite/store.ts

@@ -154,6 +154,18 @@ function migrateAuthTables(db: Database.Database): void {
   if (emailChangeCols.length && !emailChangeCols.some(c => c.name === 'kind')) {
     db.exec("ALTER TABLE email_change_tokens ADD COLUMN kind TEXT NOT NULL DEFAULT 'change'")
   }
+  // TODO.notify/05's remainders (migration 0027): the event row's
+  // mentions column + the inbox marker's saved_at stamp — a dev file
+  // predating it grows the columns here. NULL = none / unsaved: existing
+  // rows keep their posture silently.
+  const eventCols = db.prepare('PRAGMA table_info(events)').all() as Array<{ name: string }>
+  if (eventCols.length && !eventCols.some(c => c.name === 'mentions')) {
+    db.exec('ALTER TABLE events ADD COLUMN mentions TEXT')
+  }
+  const inboxCols = db.prepare('PRAGMA table_info(notify_inbox_state)').all() as Array<{ name: string }>
+  if (inboxCols.length && !inboxCols.some(c => c.name === 'saved_at')) {
+    db.exec('ALTER TABLE notify_inbox_state ADD COLUMN saved_at TEXT')
+  }
 }
 
 // AuthUserPayload lives in ./backend (see the re-export above).

package/src/store.ts

@@ -206,7 +206,12 @@ export const PUT_ENTITIES_CHUNK = 50
  *  composed key is derived at read, never stored. `payload` is the JSON
  *  envelope the catalog row declares (the summary line, the deep link,
  *  the actors, the entity's store for the read-time visibility gate).
- *  `seq` is the feed cursor (the entity_changes journal's pattern). */
+ *  `mentions` (migration 0027, TODO.notify/05's remainders) is the act's
+ *  @user mentions as a JSON array of user ids — the comment surfaces'
+ *  parse resolves them at event time and records them ON THE ROW (a
+ *  mention is a fact of the act; the feed's read-time reason computation
+ *  could never re-derive it from the entity). NULL = none. `seq` is the
+ *  feed cursor (the entity_changes journal's pattern). */
 export interface PlatformEvent {
   seq: number
   id: string
@@ -214,6 +219,9 @@ export interface PlatformEvent {
   entityId: string
   action: string
   payload: string
+  /** The mentioned user ids' JSON array (raw, the payload/channelOverrides
+   *  posture — the consumer parses); NULL = no mentions. */
+  mentions: string | null
   at: string
 }
 
@@ -226,6 +234,9 @@ export interface EventWriteInput {
   entityId: string
   action: string
   payload: string
+  /** The act's mentioned user ids (JSON array; TODO.notify/05's
+   *  remainders) — absent/NULL lands NULL (no mentions). */
+  mentions?: string | null
 }
 
 /** The key pattern's SQL legs: a subscription pattern (`application/**`,
@@ -330,7 +341,10 @@ export interface NotifyPreferences {
  *  lazily at read"): one row per (user, event), created at the first act
  *  on the inbox row. `readAt` stamps the mark-read (NULL = unread);
  *  `doneAt` stamps the archive (NULL = in the inbox — a done row leaves
- *  the feed, the marker keeps the state). 'saved' joins with wave 05.
+ *  the feed, the marker keeps the state); `savedAt` (migration 0027,
+ *  TODO.notify/05's remainders) stamps the per-event saved flag — the
+ *  GitHub Save, independent of read/done (a saved row that is done stays
+ *  saved in the archive).
  *  The feed is COMPUTED at read (events × the user's rules × the
  *  visibility gate); this table is the state that computation joins. A
  *  marker on a wiped event never joins (the user's state is their own,
@@ -340,6 +354,7 @@ export interface NotifyInboxState {
   eventId: string
   readAt: string | null
   doneAt: string | null
+  savedAt: string | null
   createdAt: string
 }
 
@@ -2593,17 +2608,20 @@ export interface ServerStore {
   putNotifyPreferences(userId: string, channels: string): Promise<NotifyPreferences>
 
   // ── the inbox state (TODO.notify/03) ──
-  /** The user's inbox markers (the feed's join: read/done per event).
-   *  Written lazily at the first act — most events carry no row. */
+  /** The user's inbox markers (the feed's join: read/done/saved per
+   *  event). Written lazily at the first act — most events carry no row. */
   listNotifyInboxStates(userId: string): Promise<NotifyInboxState[]>
   /** The marker write (the upsert on PRIMARY KEY (user_id, event_id)):
    *  each PRESENT flag sets its stamp (datetime('now')) or clears it
-   *  (NULL); absent flags keep. Answers the stored row. */
+   *  (NULL); absent flags keep. `saved` (migration 0027, TODO.notify/05's
+   *  remainders) is the per-event saved flag, the same stamp/clear
+   *  posture. Answers the stored row. */
   putNotifyInboxState(input: {
     userId: string
     eventId: string
     read?: boolean
     done?: boolean
+    saved?: boolean
   }): Promise<NotifyInboxState>
 
   // ── the email channel's delivery store (TODO.notify/04) ──