mikser-io 9.49.1 → 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.1",
+  "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);
@@ -214,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),
         }
@@ -231,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),
     }))
@@ -365,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 */ }
 }
@@ -382,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/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(' ')
+}