@volter/world-core 3.0.146 → 3.0.147

package/dist/src/derived-core.d.ts

@@ -1084,10 +1084,12 @@ export type SemanticsContext = {
     /** A vendor's Redis (the kernel's Redis library, redis/engine.ts): a request's commands run in order over this call's
      *  tree and clock, in the pack's own service, under its wire's dialect, in one of its databases (`database`: its keys
      *  and scripts apart from the others'); each answered `{result}` or `{error}`, and whether any wrote. A read-only
-     *  World raises ReadOnlyError at the first write. The wire around it (Upstash's REST envelope) is the pack's. */
+     *  World raises ReadOnlyError at the first write. `transaction` distinguishes a wire's queued transaction from
+     *  a pipeline for script restrictions. The wire around it (Upstash's REST envelope) is the pack's. */
     redis(commands: string[][], options: {
         dialect: RedisDialect;
         database?: string;
+        transaction?: boolean;
     }): Promise<{
         items: RunItem[];
         wrote: boolean;

package/dist/src/derived-core.js

@@ -1536,6 +1536,7 @@ export async function contextFor(m, call, scope) {
         redis: (commands, options) => execRedisRun(commands, {
             root, occurredAt: at, service: m.service, readOnly: scope.readOnly === true || isReadOnlyRequest(call.request), dialect: options.dialect,
             ...(options.database === undefined ? {} : { database: options.database }),
+            ...(options.transaction === undefined ? {} : { transaction: options.transaction }),
         }),
         blobs: {
             put: (key, bytes) => writeResourceBlob(m.service, key, bytes, root),

package/dist/src/redis/engine.d.ts

@@ -85,6 +85,8 @@ export type RedisContext = {
     occurredAt: string;
     /** When true, any write command raises `ReadOnlyError` (the wire answers its read-only refusal). */
     readOnly?: boolean;
+    /** Commands queued in a wire transaction, rather than an ordinary pipeline. */
+    transaction?: boolean;
     /** A database other than the service's first (Redis's SELECT n, a vendor's database id), whose keys and scripts
      *  are its own: subjects `db:<id>:key:<name>` and `db:<id>:script:<sha1>`. Absent: `key:<name>`, `script:<sha1>`. */
     database?: string;
@@ -116,6 +118,9 @@ export type RedisDialect = {
     lua: Required<Pick<LuaHost, 'extend' | 'numberArg'>>;
     /** Whether a script that fails part-way keeps what it wrote (Redis) or leaves nothing (Upstash). */
     scriptErrorsKeepWrites: boolean;
+    /** Wire-specific Lua flags. A flag installs a restriction before each command; the core owns `no-writes`.
+     *  Flags absent here are refused, never ignored. A transaction is passed explicitly by the wire. */
+    scriptFlags?: Record<string, (keys: readonly string[], transaction: boolean) => (argv: string[]) => void>;
     /** How the dialect's keys are laid out in the tree, when not one subject per key (`keyspaceImageOf`, `flushKeySpace`). */
     storage?: {
         image: (ctx: RedisContext) => KeyspaceImage;
@@ -137,6 +142,11 @@ export declare function wrongArity(name: string): string;
  * a connection's (Redis) or a URL's (Upstash).
  */
 export declare const SERVED_COMMANDS: Record<string, [number, number]>;
+/** Redis hash tag: the first nonempty {...} pair, otherwise the entire key (an empty first pair is invalid). */
+export declare function redisHashTag(key: string): string;
+/** Key positions of the shared core's commands. Undefined means database-wide access, a script, or an unknown
+ *  command; callers must refuse an unsupported restriction rather than guess that the command has no keys. */
+export declare function redisCommandKeys(argv: readonly string[]): string[] | undefined;
 /**
  * Does this command MUTATE? Takes the whole argv, not just the name, because two commands are
  * only writes for some of their subcommands. A read-only twin and `EVAL_RO` both key off this,

package/dist/src/redis/engine.js

@@ -49,6 +49,7 @@ import { treeChangesSince, treeStamp } from "../log.js";
 import { applyTwinWrite } from "../serve.js";
 import { getActiveWorldStore } from "../world-store.js";
 import { LUA_NULL, luaScriptSha1, LuaError, LuaTable, runLua } from "./lua.js";
+import { inlineCommand } from "./frames.js";
 /**
  * A Redis SIMPLE STATUS reply, kept distinct from a bulk string.
  *
@@ -138,6 +139,60 @@ export const SERVED_COMMANDS = {
     XADD: [4, -1], XLEN: [1, 1], XRANGE: [3, -1], XREVRANGE: [3, -1], XDEL: [2, -1],
     SCRIPT: [1, -1], EVAL: [2, -1], EVAL_RO: [2, -1], EVALSHA: [2, -1], EVALSHA_RO: [2, -1],
 };
+/** Redis hash tag: the first nonempty {...} pair, otherwise the entire key (an empty first pair is invalid). */
+export function redisHashTag(key) {
+    const start = key.indexOf('{');
+    const end = start < 0 ? -1 : key.indexOf('}', start + 1);
+    return end > start + 1 && start >= 0 ? key.slice(start + 1, end) : key;
+}
+/** Key positions of the shared core's commands. Undefined means database-wide access, a script, or an unknown
+ *  command; callers must refuse an unsupported restriction rather than guess that the command has no keys. */
+export function redisCommandKeys(argv) {
+    const name = (argv[0] ?? '').toUpperCase();
+    if (['PING', 'ECHO', 'SCRIPT'].includes(name))
+        return [];
+    if (['EXISTS', 'TOUCH', 'DEL', 'UNLINK', 'MGET'].includes(name))
+        return argv.slice(1);
+    if (name === 'MSET' || name === 'MSETNX')
+        return argv.slice(1).filter((_, i) => i % 2 === 0);
+    if (['RENAME', 'RENAMENX', 'RPOPLPUSH'].includes(name))
+        return argv.slice(1, 3);
+    if (['DBSIZE', 'FLUSHDB', 'FLUSHALL', 'KEYS', 'RANDOMKEY', 'SCAN', 'EVAL', 'EVALSHA', 'EVAL_RO', 'EVALSHA_RO'].includes(name))
+        return undefined;
+    return SERVED_COMMANDS[name] && argv[1] !== undefined ? [argv[1]] : undefined;
+}
+/** EVAL shebang metadata: keep the newline for Lua line numbers and the original script for cache identity.
+ *  source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/eval.c (evalExtractShebangFlags). */
+function redisScript(script, dialect) {
+    const flags = new Set();
+    if (!script.startsWith('#!'))
+        return { body: script, flags };
+    const newline = script.indexOf('\n');
+    if (newline < 0)
+        throw new RedisCommandError('ERR Invalid script shebang');
+    let parts;
+    try {
+        parts = inlineCommand(script.slice(0, newline));
+    }
+    catch {
+        throw new RedisCommandError('ERR Invalid engine in script shebang');
+    }
+    if (parts[0] !== '#!lua')
+        throw new RedisCommandError(`ERR Unexpected engine in script shebang: ${parts[0] ?? ''}`);
+    for (const option of parts.slice(1)) {
+        if (!option.startsWith('flags='))
+            throw new RedisCommandError(`ERR Unknown lua shebang option: ${option}`);
+        for (const flag of option.slice(6).split(',')) {
+            if (!flag && option === 'flags=')
+                continue;
+            if (flag !== 'no-writes' && !Object.hasOwn(dialect.scriptFlags ?? {}, flag)) {
+                throw new RedisCommandError(dialect.unmodeled(`Lua script flag ${flag}`));
+            }
+            flags.add(flag);
+        }
+    }
+    return { body: script.slice(newline), flags };
+}
 /** Commands that mutate state — refused by a read-only twin and inside `EVAL_RO`/`EVALSHA_RO`. */
 const WRITE_COMMANDS = new Set([
     'SET', 'SETEX', 'PSETEX', 'SETNX', 'MSET', 'MSETNX', 'GETSET', 'GETDEL', 'GETEX', 'APPEND',
@@ -1366,6 +1421,7 @@ export function execOne(space, argv) {
             if (sub === 'LOAD') {
                 if (a.length !== 2)
                     throw new RedisCommandError(wrongArity('script'));
+                redisScript(a[1], dialect);
                 return storeScript(space, a[1]);
             }
             if (sub === 'EXISTS')
@@ -1400,6 +1456,7 @@ export function execOne(space, argv) {
             }
             else {
                 script = a[0];
+                redisScript(script, dialect); // an invalid/unsupported header must not enter the script cache
                 // Caching is a WRITE, so a read-only twin must not attempt it — otherwise `EVAL_RO`, which
                 // is a read by definition, would 405 on the cache rather than on anything it does (§9
                 // round 1). The cost is that a read-only twin cannot serve a later EVALSHA for this
@@ -1797,15 +1854,23 @@ function luaToRedis(v) {
 function evalScript(space, script, keys, args, readOnly) {
     const before = space.snapshot();
     try {
-        const result = runLua(script, {
+        const { body, flags } = redisScript(script, space.ctx.dialect);
+        const guards = [...flags].filter(flag => flag !== 'no-writes')
+            .map(flag => space.ctx.dialect.scriptFlags[flag](keys, space.ctx.transaction === true));
+        const result = runLua(body, {
             keys,
             argv: args,
             call: (callArgs, line) => {
                 const cmd = String(callArgs[0] ?? '').toUpperCase();
                 // Redis's refusal, as EVAL_RO's page prints it (redis.io/docs/latest/commands/eval_ro/): the script by its SHA1
                 // and the line of the call
-                if (readOnly && isWriteCommand(cmd, callArgs.slice(1), space.ctx.dialect))
+                if ((readOnly || flags.has('no-writes')) && isWriteCommand(cmd, callArgs.slice(1), space.ctx.dialect))
                     throw new RedisCommandError(`ERR Error running script (call to ${luaScriptSha1(script)}): @user_script:${line}: @user_script: ${line}: Write commands are not allowed from read-only scripts.`);
+                const shape = commandShapeError(callArgs, space.ctx.dialect);
+                if (shape !== null)
+                    throw new RedisCommandError(shape);
+                for (const guard of guards)
+                    guard(callArgs);
                 return redisToLua(execOne(space, callArgs));
             },
             ...space.ctx.dialect.lua,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.146",
+  "version": "3.0.147",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/derived-core.ts

@@ -1873,8 +1873,9 @@ export type SemanticsContext = {
   /** A vendor's Redis (the kernel's Redis library, redis/engine.ts): a request's commands run in order over this call's
    *  tree and clock, in the pack's own service, under its wire's dialect, in one of its databases (`database`: its keys
    *  and scripts apart from the others'); each answered `{result}` or `{error}`, and whether any wrote. A read-only
-   *  World raises ReadOnlyError at the first write. The wire around it (Upstash's REST envelope) is the pack's. */
-  redis(commands: string[][], options: { dialect: RedisDialect; database?: string }): Promise<{ items: RunItem[]; wrote: boolean }>;
+   *  World raises ReadOnlyError at the first write. `transaction` distinguishes a wire's queued transaction from
+   *  a pipeline for script restrictions. The wire around it (Upstash's REST envelope) is the pack's. */
+  redis(commands: string[][], options: { dialect: RedisDialect; database?: string; transaction?: boolean }): Promise<{ items: RunItem[]; wrote: boolean }>;
   /** Another vendor's own URL answered by the World's twin of it (vendor-call.ts): a vendor's call to another as part of
    *  its behaviour (Clerk exchanging a Google sign-in's code). A vendor the World runs no twin of is refused
    *  (VendorUnreachableError); nothing leaves the World. */
@@ -2136,6 +2137,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     redis: (commands, options) => execRedisRun(commands, {
       root, occurredAt: at, service: m.service, readOnly: scope.readOnly === true || isReadOnlyRequest(call.request), dialect: options.dialect,
       ...(options.database === undefined ? {} : { database: options.database }),
+      ...(options.transaction === undefined ? {} : { transaction: options.transaction }),
     }),
     blobs: {
       put: (key, bytes) => writeResourceBlob(m.service, key, bytes, root),

package/src/redis/engine.ts

@@ -49,6 +49,7 @@ import { treeChangesSince, treeStamp } from '../log.ts';
 import { applyTwinWrite, type TwinResource } from '../serve.ts';
 import { getActiveWorldStore } from '../world-store.ts';
 import { LUA_NULL, luaScriptSha1, LuaError, LuaTable, runLua, type LuaHost, type LuaValue } from './lua.ts';
+import { inlineCommand } from './frames.ts';
 
 /**
  * A Redis SIMPLE STATUS reply, kept distinct from a bulk string.
@@ -147,6 +148,8 @@ export type RedisContext = {
   occurredAt: string;
   /** When true, any write command raises `ReadOnlyError` (the wire answers its read-only refusal). */
   readOnly?: boolean;
+  /** Commands queued in a wire transaction, rather than an ordinary pipeline. */
+  transaction?: boolean;
   /** A database other than the service's first (Redis's SELECT n, a vendor's database id), whose keys and scripts
    *  are its own: subjects `db:<id>:key:<name>` and `db:<id>:script:<sha1>`. Absent: `key:<name>`, `script:<sha1>`. */
   database?: string;
@@ -179,6 +182,9 @@ export type RedisDialect = {
   lua: Required<Pick<LuaHost, 'extend' | 'numberArg'>>;
   /** Whether a script that fails part-way keeps what it wrote (Redis) or leaves nothing (Upstash). */
   scriptErrorsKeepWrites: boolean;
+  /** Wire-specific Lua flags. A flag installs a restriction before each command; the core owns `no-writes`.
+   *  Flags absent here are refused, never ignored. A transaction is passed explicitly by the wire. */
+  scriptFlags?: Record<string, (keys: readonly string[], transaction: boolean) => (argv: string[]) => void>;
   /** How the dialect's keys are laid out in the tree, when not one subject per key (`keyspaceImageOf`, `flushKeySpace`). */
   storage?: { image: (ctx: RedisContext) => KeyspaceImage; flush: (space: KeySpace) => Promise<void> };
 };
@@ -233,6 +239,49 @@ export const SERVED_COMMANDS: Record<string, [number, number]> = {
   SCRIPT: [1, -1], EVAL: [2, -1], EVAL_RO: [2, -1], EVALSHA: [2, -1], EVALSHA_RO: [2, -1],
 };
 
+/** Redis hash tag: the first nonempty {...} pair, otherwise the entire key (an empty first pair is invalid). */
+export function redisHashTag(key: string): string {
+  const start = key.indexOf('{');
+  const end = start < 0 ? -1 : key.indexOf('}', start + 1);
+  return end > start + 1 && start >= 0 ? key.slice(start + 1, end) : key;
+}
+
+/** Key positions of the shared core's commands. Undefined means database-wide access, a script, or an unknown
+ *  command; callers must refuse an unsupported restriction rather than guess that the command has no keys. */
+export function redisCommandKeys(argv: readonly string[]): string[] | undefined {
+  const name = (argv[0] ?? '').toUpperCase();
+  if (['PING', 'ECHO', 'SCRIPT'].includes(name)) return [];
+  if (['EXISTS', 'TOUCH', 'DEL', 'UNLINK', 'MGET'].includes(name)) return argv.slice(1);
+  if (name === 'MSET' || name === 'MSETNX') return argv.slice(1).filter((_, i) => i % 2 === 0);
+  if (['RENAME', 'RENAMENX', 'RPOPLPUSH'].includes(name)) return argv.slice(1, 3);
+  if (['DBSIZE', 'FLUSHDB', 'FLUSHALL', 'KEYS', 'RANDOMKEY', 'SCAN', 'EVAL', 'EVALSHA', 'EVAL_RO', 'EVALSHA_RO'].includes(name)) return undefined;
+  return SERVED_COMMANDS[name] && argv[1] !== undefined ? [argv[1]] : undefined;
+}
+
+/** EVAL shebang metadata: keep the newline for Lua line numbers and the original script for cache identity.
+ *  source: https://raw.githubusercontent.com/redis/redis/c9d29f6a918c335bc1778d9f68e521c1bbb36a0f/src/eval.c (evalExtractShebangFlags). */
+function redisScript(script: string, dialect: RedisDialect): { body: string; flags: Set<string> } {
+  const flags = new Set<string>();
+  if (!script.startsWith('#!')) return { body: script, flags };
+  const newline = script.indexOf('\n');
+  if (newline < 0) throw new RedisCommandError('ERR Invalid script shebang');
+  let parts: string[];
+  try { parts = inlineCommand(script.slice(0, newline)); }
+  catch { throw new RedisCommandError('ERR Invalid engine in script shebang'); }
+  if (parts[0] !== '#!lua') throw new RedisCommandError(`ERR Unexpected engine in script shebang: ${parts[0] ?? ''}`);
+  for (const option of parts.slice(1)) {
+    if (!option.startsWith('flags=')) throw new RedisCommandError(`ERR Unknown lua shebang option: ${option}`);
+    for (const flag of option.slice(6).split(',')) {
+      if (!flag && option === 'flags=') continue;
+      if (flag !== 'no-writes' && !Object.hasOwn(dialect.scriptFlags ?? {}, flag)) {
+        throw new RedisCommandError(dialect.unmodeled(`Lua script flag ${flag}`));
+      }
+      flags.add(flag);
+    }
+  }
+  return { body: script.slice(newline), flags };
+}
+
 /** Commands that mutate state — refused by a read-only twin and inside `EVAL_RO`/`EVALSHA_RO`. */
 const WRITE_COMMANDS = new Set([
   'SET', 'SETEX', 'PSETEX', 'SETNX', 'MSET', 'MSETNX', 'GETSET', 'GETDEL', 'GETEX', 'APPEND',
@@ -1185,7 +1234,7 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
     // ── scripting ────────────────────────────────────────────────────────────────────────────
     case 'SCRIPT': {
       const sub = a[0]!.toUpperCase();
-      if (sub === 'LOAD') { if (a.length !== 2) throw new RedisCommandError(wrongArity('script')); return storeScript(space, a[1]!); }
+      if (sub === 'LOAD') { if (a.length !== 2) throw new RedisCommandError(wrongArity('script')); redisScript(a[1]!, dialect); return storeScript(space, a[1]!); }
       if (sub === 'EXISTS') return a.slice(1).map((sha) => (space.hasScript(sha.toLowerCase()) ? 1 : 0));
       if (sub === 'FLUSH') { space.flushScripts(); return OK; }
       throw new RedisCommandError(`ERR Unknown SCRIPT subcommand or wrong number of arguments for '${a[0]}'`);
@@ -1207,6 +1256,7 @@ export function execOne(space: KeySpace, argv: string[]): RedisValue {
         script = found;
       } else {
         script = a[0]!;
+        redisScript(script, dialect); // an invalid/unsupported header must not enter the script cache
         // Caching is a WRITE, so a read-only twin must not attempt it — otherwise `EVAL_RO`, which
         // is a read by definition, would 405 on the cache rather than on anything it does (§9
         // round 1). The cost is that a read-only twin cannot serve a later EVALSHA for this
@@ -1511,14 +1561,20 @@ function luaToRedis(v: LuaValue): RedisValue {
 function evalScript(space: KeySpace, script: string, keys: string[], args: string[], readOnly: boolean): RedisValue {
   const before = space.snapshot();
   try {
-    const result = runLua(script, {
+    const { body, flags } = redisScript(script, space.ctx.dialect);
+    const guards = [...flags].filter(flag => flag !== 'no-writes')
+      .map(flag => space.ctx.dialect.scriptFlags![flag]!(keys, space.ctx.transaction === true));
+    const result = runLua(body, {
       keys,
       argv: args,
       call: (callArgs, line) => {
         const cmd = String(callArgs[0] ?? '').toUpperCase();
         // Redis's refusal, as EVAL_RO's page prints it (redis.io/docs/latest/commands/eval_ro/): the script by its SHA1
         // and the line of the call
-        if (readOnly && isWriteCommand(cmd, callArgs.slice(1), space.ctx.dialect)) throw new RedisCommandError(`ERR Error running script (call to ${luaScriptSha1(script)}): @user_script:${line}: @user_script: ${line}: Write commands are not allowed from read-only scripts.`);
+        if ((readOnly || flags.has('no-writes')) && isWriteCommand(cmd, callArgs.slice(1), space.ctx.dialect)) throw new RedisCommandError(`ERR Error running script (call to ${luaScriptSha1(script)}): @user_script:${line}: @user_script: ${line}: Write commands are not allowed from read-only scripts.`);
+        const shape = commandShapeError(callArgs, space.ctx.dialect);
+        if (shape !== null) throw new RedisCommandError(shape);
+        for (const guard of guards) guard(callArgs);
         return redisToLua(execOne(space, callArgs));
       },
       ...space.ctx.dialect.lua,
@@ -1570,4 +1626,3 @@ export async function execRedisRun(commands: string[][], ctx: RedisContext): Pro
   await (space.ctx.dialect.storage?.flush(space) ?? flushKeySpace(space));
   return { items, wrote, instant: nowMs };
 }
-