mikser-io 9.49.0 → 9.50.0

package/docs/api-reference.md

@@ -844,6 +844,35 @@ AsyncLocalStorage than the engine's, queries record no edges, and index pages,
 sitemaps and feeds silently stop rebuilding. Production consumers resolve both
 from their own tree, so the problem is local to the dev workspace.
 
+## Roles
+
+Enforcement needs only the flat capability list. Explaining a refusal needs the
+role — and without it, an admin token and a site with no roles configured are
+indistinguishable from inside a session.
+
+| Export | Does |
+| --- | --- |
+| `describeAuthority({ capabilities, roles, catalogue, summaries })` | everything a session can say about its own authority |
+| `reachOf(capabilities)` | `{ writable, readOnly }` as collection names |
+| `actingRole(held, catalogue)` | which role is in force |
+| `otherRoles(held, catalogue, summaries)` | who to ask, and what they add |
+| `explainRefusal({ capability, role, target, catalogue, summaries })` | the sentence an agent repeats |
+
+`readOnly` is the field that makes a refusal explainable, and it is more useful
+than the capabilities it comes from because it is already in the vocabulary the
+person asking uses.
+
+A principal can hold several roles. `actingRole` returns the one whose
+capabilities cover the others — roles are normally written as widening tiers —
+and `null` when none dominates, because the acting authority genuinely is the
+union and naming half of it would be a lie.
+
+> **Informational, permanently.** Naming the role that could do something is
+> what makes a handoff possible. There is no way to request one and none should
+> be added: a role is a decision about a person, taken by whoever configures the
+> site, and an agent's part is to say what it cannot do and stop. `explainRefusal`
+> deliberately suggests no retry, escalation or workaround — a test asserts it.
+
 ## Auth
 
 Building a token-gated or loopback-only route.

package/index.js

@@ -2,6 +2,7 @@ export { default as runtime } from './src/runtime.js'
 export * as constants from './src/constants.js'
 export * from './src/utils.js'
 export * from './src/auth.js'
+export * from './src/roles.js'
 export * from './src/report.js'
 // The diagnostics behind --explain. Exported so a transport — the MCP tool
 // surface, the api plugin's routes — can serve the same structured report the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.49.0",
+  "version": "9.50.0",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {

package/src/changeset.js

@@ -55,7 +55,13 @@ registerSchema('change_sets', `
         -- but there is nothing to revert FROM, which is a different answer
         -- from "no such change set".
         recorded_at INTEGER,
-        recorded_as TEXT
+        recorded_as TEXT,
+        -- Why a consumer could not record this set. A set that failed is not
+        -- a set that is waiting: without somewhere to put the reason, a
+        -- permanent failure and a pending commit look identical, and both
+        -- read as a null commit forever.
+        commit_error TEXT,
+        commit_attempts INTEGER NOT NULL DEFAULT 0
     );
     CREATE INDEX IF NOT EXISTS idx_mikser_change_sets_created
         ON mikser_change_sets (created_at DESC);
@@ -185,6 +191,20 @@ function prune(handle) {
     `).run(KEEP_SETS)
 }
 
+// Said once per process, not once per write: a broken log is one condition,
+// and repeating it per write buries the builds that follow it.
+let failureReported = false
+function reportChangeSetFailure(err) {
+    if (failureReported) return
+    failureReported = true
+    const message = 'The change-set log could not be written (%s). Writes still land on disk, but they cannot be '
+        + 'listed or undone until this is fixed.'
+    try {
+        runtime.engine?.logger?.error(message, err.message)
+    } catch { /* no logger yet — the console is what is left */ }
+    if (!runtime.engine?.logger) console.error(message.replace('%s', err.message))
+}
+
 function rowsToSets(handle, rows) {
     const stmt = handle.prepare(
         'SELECT path, operation FROM mikser_change_set_paths WHERE change_set = ? ORDER BY path')
@@ -200,6 +220,8 @@ function rowsToSets(handle, rows) {
             closed: row.closed_at != null,
             recordedAt: row.recorded_at ?? null,
             recordedAs: row.recorded_as ?? null,
+            commitError: row.commit_error ?? null,
+            commitAttempts: row.commit_attempts ?? 0,
             paths: paths.map(p => p.path),
             deletions: paths.filter(p => p.operation === 'delete').map(p => p.path),
         }
@@ -217,6 +239,8 @@ function memorySets(filter = () => true) {
         closed: Boolean(set.closedAt),
         recordedAt: set.recordedAt ?? null,
         recordedAs: set.recordedAs ?? null,
+        commitError: set.commitError ?? null,
+        commitAttempts: set.commitAttempts ?? 0,
         paths: [...set.paths.keys()],
         deletions: [...set.paths.entries()].filter(([, op]) => op === 'delete').map(([p]) => p),
     }))
@@ -283,7 +307,16 @@ export function recordChangeSetWrite({
 
     const handle = db()
     if (handle) {
-        try { persist(handle, set, rel, operation, entityId) } catch { /* memory still holds it */ }
+        try {
+            persist(handle, set, rel, operation, entityId)
+        } catch (err) {
+            // Loud. A swallowed failure here is invisible in exactly the way
+            // that matters: the write succeeds, an id comes back, and the log
+            // it points at silently never gains a row — which is how a stale
+            // column shape turned the whole feature into a no-op that looked
+            // like it was working.
+            reportChangeSetFailure(err)
+        }
     }
     return set.id
 }
@@ -298,7 +331,9 @@ export function pendingChangeSets() {
                 SELECT * FROM mikser_change_sets WHERE recorded_at IS NULL ORDER BY created_at ASC
             `).all()
             return rowsToSets(handle, rows).filter(set => set.paths.length)
-        } catch { /* fall through to memory */ }
+        } catch (err) {
+            reportChangeSetFailure(err)
+        }
     }
     return memorySets(set => !set.recordedAt).sort((a, b) => a.startedAt - b.startedAt)
 }
@@ -313,7 +348,9 @@ export function listChangeSets({ limit = 20 } = {}) {
                 SELECT * FROM mikser_change_sets ORDER BY created_at DESC LIMIT ?
             `).all(Math.max(1, Math.min(limit, 200)))
             return rowsToSets(handle, rows)
-        } catch { /* fall through to memory */ }
+        } catch (err) {
+            reportChangeSetFailure(err)
+        }
     }
     return memorySets().sort((a, b) => b.startedAt - a.startedAt).slice(0, limit)
 }
@@ -338,13 +375,13 @@ export function markChangeSetsRecorded(ids = [], recordedAs = null) {
     const at = Date.now()
     for (const id of ids) {
         const set = memory.get(id)
-        if (set) { set.recordedAt = at; set.recordedAs = recordedAs }
+        if (set) { set.recordedAt = at; set.recordedAs = recordedAs; set.commitError = null }
     }
     const handle = db()
     if (!handle) return
     try {
         const stmt = handle.prepare(
-            'UPDATE mikser_change_sets SET recorded_at = ?, recorded_as = ? WHERE id = ?')
+            'UPDATE mikser_change_sets SET recorded_at = ?, recorded_as = ?, commit_error = NULL WHERE id = ?')
         for (const id of ids) stmt.run(at, recordedAs, id)
     } catch { /* memory still holds it */ }
 }
@@ -355,6 +392,30 @@ export function clearChangeSets(ids = [], recordedAs = null) {
     markChangeSetsRecorded(ids, recordedAs)
 }
 
+// Record that a consumer tried and failed. The set stays pending — a failure
+// is worth retrying, and a transient one usually succeeds next pass — but the
+// reason is now visible instead of the set sitting at `committed: null` with
+// nothing to say why.
+export function markChangeSetFailed(id, error) {
+    const message = String(error?.stderr || error?.message || error || 'unknown error').slice(0, 500)
+    const set = memory.get(id)
+    if (set) {
+        set.commitError = message
+        set.commitAttempts = (set.commitAttempts ?? 0) + 1
+    }
+    const handle = db()
+    if (!handle) return
+    try {
+        handle.prepare(`
+            UPDATE mikser_change_sets
+            SET commit_error = ?, commit_attempts = commit_attempts + 1
+            WHERE id = ?
+        `).run(message, id)
+    } catch (err) {
+        reportChangeSetFailure(err)
+    }
+}
+
 export function forgetAllChangeSets() {
     memory.clear()
     const handle = db()

package/src/database/index.js

@@ -104,6 +104,78 @@ let db = null
 // duplicate detection. Same name twice = the later registration wins
 // (with a warning). Convention: `<owner>` matching the table prefix
 // (`catalog`, `manifest`, `vector`, etc.).
+// Column names a CREATE TABLE body declares, in order.
+//
+// Only the leading identifier of each top-level comma-separated clause, and
+// only when it is not a table constraint. Good enough for the schemas this
+// engine registers, and deliberately not a SQL parser.
+function columnsFrom(sqlScript, table) {
+    const re = new RegExp(
+        `CREATE\\s+TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?[\`"'\\[]?${table}[\`"'\\]]?\\s*\\(`, 'i')
+    const m = re.exec(sqlScript)
+    if (!m) return []
+    // Walk to the matching close paren so nested types and CHECK(...) do not
+    // end the body early.
+    let depth = 1
+    let i = m.index + m[0].length
+    const start = i
+    for (; i < sqlScript.length && depth > 0; i++) {
+        if (sqlScript[i] === '(') depth++
+        else if (sqlScript[i] === ')') depth--
+    }
+    const body = sqlScript.slice(start, i - 1)
+
+    const clauses = []
+    let current = ''
+    depth = 0
+    for (const ch of body) {
+        if (ch === '(') depth++
+        else if (ch === ')') depth--
+        if (ch === ',' && depth === 0) { clauses.push(current); current = '' } else current += ch
+    }
+    clauses.push(current)
+
+    const CONSTRAINTS = new Set(['primary', 'unique', 'foreign', 'check', 'constraint'])
+    return clauses
+        .map(clause => clause.replace(/--[^\n]*/g, '').trim())
+        .filter(Boolean)
+        .map(clause => clause.split(/\s+/)[0].replace(/["`\[\]]/g, ''))
+        .filter(name => name && !CONSTRAINTS.has(name.toLowerCase()))
+}
+
+// Add columns a DURABLE table has grown since it was created.
+//
+// `CREATE TABLE IF NOT EXISTS` does nothing to a table that already exists, so
+// re-applying a schema never adds a column. For a cache table that is
+// invisible: the version bump wipes and recreates it. A durable table is
+// exactly the one that SURVIVES the wipe, so it is the only kind that can go
+// stale — and it goes stale silently, with every insert naming the new column
+// failing against a table that still has the old shape.
+function migrateDurableColumns(handle, schemas, logger) {
+    for (const value of schemas?.values?.() ?? []) {
+        const { sql, durable } = schemaEntry(value)
+        if (!durable) continue
+        for (const table of tableNamesFrom(sql)) {
+            let existing
+            try {
+                existing = new Set(handle.prepare(`PRAGMA table_info("${table}")`).all().map(c => c.name))
+            } catch { continue }
+            if (!existing.size) continue
+            for (const column of columnsFrom(sql, table)) {
+                if (existing.has(column)) continue
+                // Only ever ADD. Dropping or retyping a column in a durable
+                // table would discard data the whole flag exists to keep.
+                try {
+                    handle.exec(`ALTER TABLE "${table}" ADD COLUMN "${column}"`)
+                    logger?.info('Durable table %s gained column %s', table, column)
+                } catch (err) {
+                    logger?.warn('Could not add column %s to %s: %s', column, table, err.message)
+                }
+            }
+        }
+    }
+}
+
 // Table names a schema script creates. Used to decide what a cache wipe
 // must leave alone — the registry knows schema NAMES, and the wipe works in
 // tables.
@@ -498,7 +570,8 @@ export function createSqliteDatabase({
         }
 
         // Apply each subsystem's registered schema script. Idempotent
-        // CREATE statements mean replay-safe across opens.
+        // CREATE statements mean replay-safe across opens — but only for
+        // tables they can recreate; see migrateDurableColumns below.
         for (const [name, value] of schemas) {
             const { sql: sqlScript } = schemaEntry(value)
             try {
@@ -511,6 +584,11 @@ export function createSqliteDatabase({
                 throw new Error(`Schema "${name}" failed to apply: ${err.message}`)
             }
         }
+
+        // A durable table survives the wipe, so re-applying its CREATE is not
+        // enough to give it a column the schema has grown. Reconciled here,
+        // additively.
+        migrateDurableColumns(handle, schemas, logger)
     }
 
     function close() {

package/src/roles.js

@@ -0,0 +1,145 @@
+// What a principal may do, in words rather than in capability strings.
+//
+// Enforcement only ever needs the flat list: does this credential carry
+// `drive:layouts:write`, yes or no. That is enough to refuse a request and not
+// nearly enough to EXPLAIN one. A session holding eighteen capabilities cannot
+// tell whether those eighteen are a role called admin, whether narrower roles
+// exist, or which one it is acting as — so an admin token and a site with no
+// roles configured look exactly the same from inside.
+//
+// The difference shows up in what an agent says when it is stopped:
+//
+//   "I got a 403 writing to styles/tokens/buttons.css."
+//   "I'm connected as editor, which does not include drive:styles:write.
+//    That file is the design system — this needs whoever built the site."
+//
+// The first invites working around the refusal. The second is a sentence the
+// end user can forward to the person who can actually do it.
+//
+// INFORMATIONAL, deliberately and permanently. Naming the role that could do
+// something is how a handoff is made possible; there is no way to ask for one
+// and none should be added. A role is a decision about a person, taken by
+// whoever configures the site, and an agent's part in it is to say what it
+// cannot do and stop.
+
+// Capabilities follow `drive:<name>` to read and `drive:<name>:write` to
+// write. That convention is the whole mapping — it needs no list of endpoints
+// to stay correct as collections are added.
+const DRIVE = /^drive:([^:]+)(?::write)?$/
+
+// Split a capability list into what it can change and what it can only look
+// at. `readOnly` is the field that makes a refusal explainable, and it is more
+// useful than the capabilities it is derived from because it is already in the
+// vocabulary the person asking uses: collection names, not verbs.
+export function reachOf(capabilities = []) {
+    const readable = new Set()
+    const writable = new Set()
+    for (const capability of capabilities ?? []) {
+        const m = DRIVE.exec(capability)
+        if (!m) continue
+        readable.add(m[1])
+        if (capability.endsWith(':write')) writable.add(m[1])
+    }
+    return {
+        writable: [...writable].sort(),
+        readOnly: [...readable].filter(name => !writable.has(name)).sort(),
+    }
+}
+
+// Which role is in force.
+//
+// A principal can hold several. Naming one of them anyway would be a lie, so
+// the answer is the role whose capabilities cover every other role held —
+// there usually is one, because roles are written as widening tiers. When none
+// dominates, the acting authority genuinely is the union and `role` is null
+// with `roles` naming the parts.
+export function actingRole(held = [], catalogue = {}) {
+    const names = (held ?? []).filter(name => catalogue[name])
+    if (!names.length) return null
+    if (names.length === 1) return names[0]
+    const covers = (a, b) => {
+        const set = new Set(catalogue[a] ?? [])
+        return (catalogue[b] ?? []).every(capability => set.has(capability))
+    }
+    return names.find(candidate => names.every(other => covers(candidate, other))) ?? null
+}
+
+// The roles this principal does NOT hold, and what each would add.
+//
+// Named so an agent can say WHO to ask. Roles are not credentials — listing
+// them reveals that a `developers` role exists, which is exactly what makes a
+// handoff possible, and nothing about how to obtain it.
+export function otherRoles(held = [], catalogue = {}, summaries = {}) {
+    const mine = new Set(held ?? [])
+    const have = new Set((held ?? []).flatMap(name => catalogue[name] ?? []))
+    return Object.entries(catalogue)
+        .filter(([name]) => !mine.has(name))
+        .map(([name, capabilities]) => {
+            const adds = (capabilities ?? []).filter(capability => !have.has(capability))
+            // A role that adds nothing this principal already has is noise in
+            // a handoff — there is nobody to ask, because it can do no more.
+            if (!adds.length) return null
+            const reach = reachOf(adds)
+            return {
+                name,
+                // Expressed as collections where the capabilities allow it,
+                // because "layouts, styles, scripts" is what a person asking
+                // for help can act on and `drive:layouts:write` is not.
+                adds: reach.writable.length ? reach.writable : adds,
+                ...(summaries[name] ? { summary: summaries[name] } : {}),
+            }
+        })
+        .filter(Boolean)
+}
+
+// Everything a session should be able to say about its own authority.
+export function describeAuthority({ capabilities, roles = [], catalogue = {}, summaries = {} } = {}) {
+    // No capability map configured at all: the credential is not
+    // capability-scoped and the endpoint's own operations are the only limit.
+    // Reporting a role here would invent one.
+    if (capabilities == null) {
+        return {
+            role: null,
+            roleSummary: 'This site has no roles configured, so this credential is limited only by what the '
+                + 'endpoint itself allows.',
+            capabilities: null,
+            writable: null,
+            readOnly: null,
+            otherRoles: [],
+        }
+    }
+    const role = actingRole(roles, catalogue)
+    const { writable, readOnly } = reachOf(capabilities)
+    return {
+        role,
+        ...(roles?.length && !role ? { roles } : {}),
+        ...(summaries[role] ? { roleSummary: summaries[role] } : {}),
+        writable,
+        readOnly,
+        otherRoles: otherRoles(roles, catalogue, summaries),
+    }
+}
+
+// The sentence an agent should repeat when a role stops it.
+//
+// Names the role, the capability it lacks and who has it, in that order,
+// because that is the order the reader needs them: what I am, what is missing,
+// who to ask. Deliberately without a suggestion to retry, escalate or work
+// around it — the correct next step is a person, not another call.
+export function explainRefusal({ capability, role, target, catalogue = {}, summaries = {} } = {}) {
+    const holders = Object.entries(catalogue)
+        .filter(([, capabilities]) => (capabilities ?? []).includes(capability))
+        .map(([name]) => name)
+    // Trim the summary's own full stop: it is a sentence in its own right and
+    // reads as a typo when a second one lands beside it.
+    const summary = summaries[holders[0]]?.replace(/\.\s*$/, '')
+    const who = holders.length
+        ? `The ${holders.join(' or ')} role carries it${summary ? ` — ${summary}` : ''}.`
+        : 'No configured role carries it.'
+    return [
+        role ? `Connected as ${role}, which does not include ${capability}.` : `This credential lacks ${capability}.`,
+        target ? `That is what writing to ${target} needs.` : null,
+        who,
+        'Ask whoever set the site up; this is not something to work around.',
+    ].filter(Boolean).join(' ')
+}