@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/swift/ReadmeRef_swift.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -7,7 +7,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftListMatch } from './utility_swift'
 
 
 // Type names come from the shared canonToType 'swift' column (single source of truth).
@@ -15,6 +15,7 @@ import { swiftVarName } from './utility_swift'
 // A type-correct Swift `Value` literal for a field's canonical type.
 function swiftLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return '.null'
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'
@@ -27,28 +28,33 @@ function swiftLit(type: any, placeholder: string = 'example'): string {
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, ctrl) throws -> Value',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and throws on error.',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data()` reads, as a native `Value` that `asNative as? Entity` unwraps, and throws on error.',
   },
   list: {
     sig: 'list(reqmatch, ctrl) throws -> Value',
-    returns: 'a Value list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list(nil, nil)` to list all records. Returns a Value list and throws on error.',
+    returns: 'a `Value` list of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call `list(nil, nil)` to list all records. Returns a `Value` list of entities, one per record, and throws on error.',
   },
   create: {
     sig: 'create(reqdata, ctrl) throws -> Value',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and throws on error.',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and throws on error.',
   },
   update: {
     sig: 'update(reqdata, ctrl) throws -> Value',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and throws on error.',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and throws on error.',
+  },
+  patch: {
+    sig: 'patch(reqdata, ctrl) throws -> Value',
+    returns: 'the patched entity',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity and throws on error.',
   },
   remove: {
     sig: 'remove(reqmatch, ctrl) throws -> Value',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Throws on error.',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and throws on error.',
   },
 }
 
@@ -216,7 +222,7 @@ let ${eVar} = client.${accessor}()
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -257,6 +263,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             const matchItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
@@ -275,8 +285,12 @@ let result = try client.${accessor}().${opname}(${arg}, nil)
           }
           else if ('list' === opname) {
             Content(`\`\`\`swift
-let results = try client.${accessor}().list(nil, nil)
-print(results)
+let results = try client.${accessor}().list(${swiftListMatch(ent)}, nil)
+for item in results.asList?.items ?? [] {
+    if let entity = item.asNative as? Entity {
+        print(entity.data())
+    }
+}
 \`\`\`
 
 `)
@@ -297,8 +311,8 @@ let result = try client.${accessor}().create(VMap([
 
 `)
           }
-          else if ('update' === opname) {
-            const updateItems = opRequestShape(ent, 'update').items
+          else if ('update' === opname || 'patch' === opname) {
+            const updateItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
@@ -308,12 +322,19 @@ let result = try client.${accessor}().create(VMap([
                 it.name === idF ? ent.name + '_id' : it.name)})${comma}\n`
             }).join('')
             Content(`\`\`\`swift
-let result = try client.${accessor}().update(VMap([
+let result = try client.${accessor}().${opname}(VMap([
 ${updateLines}]), nil)
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a `String`, or `Data` or `[UInt8]` as a `.nat` value',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/swift/ReadmeTopQuick_swift.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftListMatch } from './utility_swift'
 
 
 // A type-correct Swift `Value` literal for a param: numeric/boolean/array/
@@ -15,6 +15,7 @@ import { swiftVarName } from './utility_swift'
 // The SDK's loose object model means every value is a `Value` inside a `VMap`.
 function swiftLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return '.null'
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'
@@ -65,10 +66,12 @@ let client = ${SDK}(options)
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eNameLower}s (returns a Value list, throws on error)
-let ${eVar}List = try client.${eName}().list(nil, nil)
-for ${eVar} in ${eVar}List.asList?.items ?? [] {
-    print(${eVar})
+      Content(`// List all ${eNameLower}s (a Value list of entities, one per record; throws on error)
+let ${eVar}List = try client.${eName}().list(${swiftListMatch(exampleEntity)}, nil)
+for ${eVar}Item in ${eVar}List.asList?.items ?? [] {
+    if let ${eVar}Entity = ${eVar}Item.asNative as? Entity {
+        print(${eVar}Entity.data())
+    }
 }
 `)
     }
@@ -87,9 +90,11 @@ for ${eVar} in ${eVar}List.asList?.items ?? [] {
             it.name === idF ? 'example_id' : 'example_' + it.name)})`).join(', ')}])`
         : 'nil'
       Content(`
-// Load a specific ${eNameLower} (returns the record, throws on error)
+// Load a specific ${eNameLower} (returns the entity, throws on error)
 let ${eVar} = try client.${eName}().load(${loadArg}, nil)
-print(${eVar})
+if let ${eVar}Entity = ${eVar}.asNative as? Entity {
+    print(${eVar}Entity.data())
+}
 `)
     }
   }

package/project/.sdk/src/cmp/swift/ReadmeTopTest_swift.ts

@@ -1,17 +1,18 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { swiftVarName } from './utility_swift'
+import { swiftVarName, swiftString } from './utility_swift'
 
 
 // A type-correct Swift `Value` literal for a field's canonical type.
 function swiftLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return '.null'
   if ('INTEGER' === k) return '.int(1)'
   if ('NUMBER' === k) return '.double(1.0)'
   if ('BOOLEAN' === k) return '.bool(true)'
@@ -41,28 +42,38 @@ let client = ${SDK}.testSDK(nil, nil)
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'nil'
-    if (isMatchOp) {
+    if (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length)) {
       // Every REQUIRED match key (id first) — the same shape that generates
       // the op's request type, so the block stays honest.
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+      const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF) : requiredItems(exampleEntity, 'list'))
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = 0 < items.length
         ? `VMap([${items.map((it: any) =>
-          `("${it.name}", ${it.name === idF ? '.string("test01")' : swiftLit(it.type)})`).join(', ')}])`
+          `(${swiftString(it.name)}, ${isMatchOp && it.name === idF ? '.string("test01")' : swiftLit(it.type)})`).join(', ')}])`
         : 'nil'
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)
       const chosen = required.length ? required : items.slice(0, 3)
       arg = `VMap([${chosen.map((it: any) =>
-        `("${it.name}", ${swiftLit(it.type)})`).join(', ')}])`
+        `(${swiftString(it.name)}, ${swiftLit(it.type)})`).join(', ')}])`
+    }
+    const eVar = swiftVarName(exampleEntity.name)
+    Content('list' === primaryOp
+      ? `let ${eVar}List = try client.${eName}().list(${arg}, nil)
+for ${eVar}Item in ${eVar}List.asList?.items ?? [] {
+    if let ${eVar}Entity = ${eVar}Item.asNative as? Entity {
+        print(${eVar}Entity.data())
     }
-    const eVar = swiftVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
-    Content(`let ${eVar} = try client.${eName}().${primaryOp}(${arg}, nil)
-print(${eVar})
+}
+`
+      : `let ${eVar} = try client.${eName}().${primaryOp}(${arg}, nil)
+if let ${eVar}Entity = ${eVar}.asNative as? Entity {
+    print(${eVar}Entity.data())
+}
 `)
   }
 

package/project/.sdk/src/cmp/swift/TestClean_swift.ts

@@ -8,6 +8,7 @@ import {
   isHttpBasicAuth,
   resolveAuthIn,
   resolveAuthName,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -31,6 +32,10 @@ const TestClean = cmp(function TestClean(props: any) {
     basic: isHttpBasicAuth(model),
   }
 
+  // CostRecord is declared by the cost feature's source, which ships only
+  // when the model selects the feature.
+  const cost = null != targetFeatures(model, target).cost
+
   // Same order the ts sweep tries: list, then load, then the rest.
   const rank: Record<string, number> = { list: 0, load: 1 }
   const candidates = each(entityCollection(model))
@@ -47,7 +52,7 @@ const TestClean = cmp(function TestClean(props: any) {
 
   // Inside Tests/<Name>SdkTests already: Test_swift.ts opens those folders.
   File({ name: 'CleanTest.' + target.ext }, () =>
-    Content(render(model.const.Name, auth, candidates)))
+    Content(render(model.const.Name, auth, candidates, cost)))
 })
 
 
@@ -71,6 +76,7 @@ function render(
   Name: string,
   auth: { suppressed: boolean, where: string, name: string, basic: boolean },
   candidates: { name: string, Name: string, ops: string[], params: Record<string, string[]> }[],
+  cost: boolean,
 ): string {
   const swiftList = (items: string[]) => '[' + items.map((i) => swiftString(i)).join(', ') + ']'
   const candidateLines = candidates.map((c) =>
@@ -329,8 +335,19 @@ final class ${Name}CleanTest: XCTestCase {
     gp(SdkConfig.makeConfig(), "feature").asMap?.entries[name] != nil
   }
 
+  // Offline, as every generated suite is: the test OPTION resolves a required
+  // server variable to test-<name>, and installs no transport. A construction
+  // that fails traps, which no harness can catch, so the option is the guard.
+  static func offline(_ opts: VMap) -> VMap {
+    let out = VMap()
+    for (k, v) in opts.entries { out.entries[k] = v }
+    out.entries["test"] = .map(vm(("active", .bool(true))))
+    return out
+  }
+
   static func makeSdk(
-    _ scenario: Scenario, _ box: SinkBox, _ cleanopts: VMap? = nil, _ extra: [BaseFeature] = []
+    _ scenario: Scenario, _ box: SinkBox, _ cleanopts: VMap? = nil, _ extra: [BaseFeature] = [],
+    auth: VMap? = nil
   ) -> ${Name}SDK {
     func capture(_ name: String) -> (VMap) -> Void {
       return { rec in box.sinks += formsOf(name, rec) }
@@ -352,11 +369,11 @@ final class ${Name}CleanTest: XCTestCase {
     if hasFeature("telemetry") {
       feature.entries["telemetry"] = .map(vm(("active", .bool(true)), ("exporter", .nat(capture("telemetry")))))
     }
-    if hasFeature("cost") {
+${cost ? `    if hasFeature("cost") {
       let sink: (CostRecord) -> Void = { rec in box.sinks += formsOf("cost", rec) }
       feature.entries["cost"] = .map(vm(("active", .bool(true)), ("sink", .nat(sink))))
     }
-    if hasFeature("metrics") {
+` : ''}    if hasFeature("metrics") {
       feature.entries["metrics"] = .map(vm(("active", .bool(true))))
     }
     if hasFeature("clienttrack") {
@@ -381,7 +398,8 @@ final class ${Name}CleanTest: XCTestCase {
     for f in extra { extend.append(.nat(f)) }
     opts.entries["extend"] = .list(VList(extend))
     opts.entries["utility"] = .map(vm(("fetcher", .nat(fetch))))
-    return ${Name}SDK(opts)
+    if let a = auth { opts.entries["auth"] = .map(a) }
+    return ${Name}SDK(${Name}CleanTest.offline(opts))
   }
 
   // Emitted from the model: every active entity with the operations it
@@ -400,6 +418,7 @@ ${candidateLines}
     case "load": return try ent.load(args, ctrl)
     case "create": return try ent.create(args, ctrl)
     case "update": return try ent.update(args, ctrl)
+    case "patch": return try ent.patch(args, ctrl)
     case "remove": return try ent.remove(args, ctrl)
     default: throw TransportError(message: "unknown operation: " + op)
     }
@@ -412,7 +431,7 @@ ${candidateLines}
     let opts = VMap()
     opts.entries["apikey"] = .string(canaryApikey)
     opts.entries["utility"] = .map(vm(("fetcher", .nat(fetch))))
-    let plain = ${Name}SDK(opts)
+    let plain = ${Name}SDK(${Name}CleanTest.offline(opts))
     for candidate in candidates {
       for op in candidate.ops {
         let filled: [String] = candidate.params[op] ?? []
@@ -429,15 +448,18 @@ ${candidateLines}
   static func drive(_ sdk: ${Name}SDK, _ target: Target, _ ctrl: VMap, _ box: SinkBox) -> Error? {
     // A caller may keep the record it passed rather than read ctrl["explain"].
     let held = ctrl.entries["explain"]?.asMap
+    let entity = target.candidate.accessor(sdk)
     var out: Value = .noval
     var err: Error? = nil
     do {
-      out = try invoke(target.candidate.accessor(sdk), target.op, target.params, ctrl)
+      out = try invoke(entity, target.op, target.params, ctrl)
     } catch {
       err = error
     }
     if let e = err { box.sinks += formsOf("error", e) }
     if !isNil(out) { box.sinks += formsOf("result", out) }
+    // Raw, as a caller copying the match into another query reads it.
+    box.sinks += formsOf("match", entity.matchv(nil))
     if let explain = ctrl.entries["explain"]?.asMap { box.sinks += formsOf("explain", explain) }
     if let h = held, h !== ctrl.entries["explain"]?.asMap { box.sinks += formsOf("explain:held", h) }
     return err
@@ -470,13 +492,19 @@ ${candidateLines}
       }
     }
 
+    // A name given at run time replaces the declared one: the match leaves
+    // out whichever name prepareAuth placed.
+    _ = ${Name}CleanTest.drive(
+      ${Name}CleanTest.makeSdk(${Name}CleanTest.scenarios[0], box, auth: vm(("name", .string("zzcred")))),
+      target, VMap(), box)
+
     // A credential mistyped as a map. This struct port's validate collects
     // its errors instead of throwing, so nothing rejects it: the client it
     // produced is swept instead.
     let mistyped = VMap()
     mistyped.entries["apikey"] = .map(vm(("value", .string(canaryApikey))))
     mistyped.entries["clean"] = .map(vm(("values", .string(canaryValue))))
-    box.sinks += ${Name}CleanTest.formsOf("mistyped", ${Name}SDK(mistyped))
+    box.sinks += ${Name}CleanTest.formsOf("mistyped", ${Name}SDK(${Name}CleanTest.offline(mistyped)))
 
     // An error a feature hook raises, quoting the request, skips makeError.
     // A swift hook cannot throw, so no variant fails from PreUnexpected.
@@ -532,13 +560,15 @@ ${candidateLines}
       if !isNil(clean) {
         bareopts.entries["clean"] = clean
       }
-      let bareerr = ${Name}CleanTest.drive(${Name}SDK(bareopts), target, vm(("explain", .map(VMap()))), box)
+      let bareerr = ${Name}CleanTest.drive(
+        ${Name}SDK(${Name}CleanTest.offline(bareopts)), target, vm(("explain", .map(VMap()))), box)
       XCTAssertNotNil(bareerr, "the 404 should fail with clean: " + stringify(clean))
     }
 
     // A feature's name is not a field name: only the sensitive names inside
     // its settings register. An entity block, of entity settings or seeded
-    // records keyed by entity name and id, is not read at all.
+    // records keyed by entity name and id, is not read at all, and nor are
+    // rbac's rules, keyed by entity and operation names.
     let record = vm(("zztoken", .map(vm(("ZZTOKEN01", .map(vm(("note", .string("PLAINRECORD-t5r3e1w9")))))))))
     let alias = vm(("zztoken", .map(vm(("alias", .map(vm(("zzkey", .string("PLAINALIAS-m2n4b6v8")))))))))
     let featopts = VMap()
@@ -546,6 +576,8 @@ ${candidateLines}
     featopts.entries["feature"] = .map(vm(
       ("zzsecrets", .map(vm(("active", .bool(false)), ("kind", .string("PLAINSETTING-q8w2e4r6"))))),
       ("zzfeat", .map(vm(("active", .bool(false)), ("apitoken", .string("FEATTOKEN-z9y8x7w6"))))),
+      ("rbac", .map(vm(("active", .bool(false)),
+        ("rules", .map(vm(("zztoken.load", .string("PLAINRULE-k7j5h3g1")))))))),
       ("test", .map(vm(("active", .bool(false)), ("entity", .map(record)))))))
     featopts.entries["entity"] = .map(alias)
     let fctx = Context(["options": makeOptionsUtil(Context(["options": featopts], nil))], nil)
@@ -553,6 +585,7 @@ ${candidateLines}
     let ftoken = cleanUtil(fctx, .string("token FEATTOKEN-z9y8x7w6")).asString
     let frecord = cleanUtil(fctx, .string("record PLAINRECORD-t5r3e1w9")).asString
     let falias = cleanUtil(fctx, .string("alias PLAINALIAS-m2n4b6v8")).asString
+    let frule = cleanUtil(fctx, .string("rule PLAINRULE-k7j5h3g1")).asString
 
     // direct() returns its error rather than throwing it. Only the SDK's own
     // error can be cleaned in place, so the coded transport is the one used.
@@ -597,6 +630,7 @@ ${candidateLines}
     XCTAssertEqual(ftoken, "token " + mask)
     XCTAssertEqual(frecord, "record PLAINRECORD-t5r3e1w9")
     XCTAssertEqual(falias, "alias PLAINALIAS-m2n4b6v8")
+    XCTAssertEqual(frule, "rule PLAINRULE-k7j5h3g1")
     XCTAssertEqual(rawerr?.code, "denied_" + mask)
 
     let explained = explains["ok/explain"] ?? VMap()

package/project/.sdk/src/cmp/swift/TestEntity_swift.ts

@@ -3,6 +3,8 @@ import {
   Content,
   File,
   cmp,
+  invalidRequest,
+  opReachable,
 } from '@voxgig/sdkgen'
 
 
@@ -16,7 +18,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const { target, entity } = props
   const Name = model.const.Name
 
-  const hasList = Object.keys(entity.op || {}).includes('list')
+  // The stream test lists with no match, so a bare call must reach a route.
+  const hasList = opReachable(entity.op?.list, [])
 
   File({ name: entity.Name + 'EntityTest.' + target.ext }, () => {
     Content(`// ${entity.name} entity test (generated from the API model).
@@ -66,15 +69,100 @@ final class ${entity.Name}EntityTest: XCTestCase {
     for await item in seq2 { streamed2.append(item) }
     XCTAssertEqual(streamed2.count, listedN)
   }
+
+  // A failed operation throws from a stream as it does from the operation; under
+  // throw false the stream ends quietly. The caller's ctrl stays its own.
+  func testStreamError() async throws {
+    let offline = vm(("net", .map(vm(("offline", .bool(true))))))
+    var err: Error? = nil
+    do { _ = try ${Name}SDK.testSDK(offline, nil).${entity.Name}().stream("list", VMap(), nil) } catch { err = error }
+    XCTAssertTrue((err as? ${Name}Error)?.message.contains("offline") ?? false,
+      "expected the transport failure to raise from the stream, got \\(String(describing: err))")
+
+    var quiet: [Value] = []
+    let seq = try ${Name}SDK.testSDK(offline, nil).${entity.Name}()
+      .stream("list", VMap(), vm(("ctrl", .map(vm(("throw", .bool(false)))))))
+    for await item in seq { quiet.append(item) }
+    XCTAssertEqual(quiet.count, 0, "throw false should end the stream quietly")
+
+    if ${entity.Name}EntityTest.hasFeature("rbac") {
+      let denied = ${Name}SDK.testSDK(nil,
+        vm(("feature", .map(vm(("rbac", .map(vm(("active", .bool(true)), ("deny", .bool(true))))))))))
+      var denyerr: Error? = nil
+      do { _ = try denied.${entity.Name}().stream("list", VMap(), nil) } catch { denyerr = error }
+      XCTAssertEqual((denyerr as? ${Name}Error)?.code, "rbac_denied",
+        "expected the rbac denial to raise from the stream, got \\(String(describing: denyerr))")
+    }
+  }
+
+  func testStreamCtrl() async throws {
+    let explain = VMap()
+    let ctrl = vm(("explain", .map(explain)))
+    let seq = try ${Name}SDK.testSDK(nil, nil).${entity.Name}().stream("list", VMap(), vm(("ctrl", .map(ctrl))))
+    for await _ in seq {}
+    XCTAssertEqual(ctrl.entries.count, 1, "the stream changed the caller's ctrl")
+    XCTAssertTrue(ctrl.entries["explain"]?.asMap === explain, "the caller's explain record is not its own")
+    XCTAssertFalse(explain.entries.isEmpty, "the caller's explain record was not filled")
+  }
+
+  // A swift hook cannot throw, so the failure here is the transport's: makeError
+  // fires PreUnexpected for it, under throw false too.
+  func testUnexpected() throws {
+    final class CountHook: BaseFeature {
+      var unexpected = 0
+      override init() { super.init(); name = "counthook"; version = "0.0.1"; active = true }
+      override func preUnexpected(_ ctx: Context) { unexpected += 1 }
+    }
+    let hook = CountHook()
+    let sdk = ${Name}SDK.testSDK(vm(("net", .map(vm(("offline", .bool(true)))))), nil)
+    sdk.features.append(hook)
+    var err: Error? = nil
+    do { _ = try sdk.${entity.Name}().list(VMap(), nil) } catch { err = error }
+    XCTAssertTrue((err as? ${Name}Error)?.message.contains("offline") ?? false,
+      "expected the transport failure, got \\(String(describing: err))")
+    XCTAssertGreaterThan(hook.unexpected, 0, "PreUnexpected did not fire")
+
+    let fired = hook.unexpected
+    _ = try sdk.${entity.Name}().list(VMap(), vm(("throw", .bool(false))))
+    XCTAssertGreaterThan(hook.unexpected, fired, "PreUnexpected did not fire under throw false")
+  }
 `)
     }
 
-    Content(`}
+    const bad = invalidRequest(entity)
+    if (null != bad) {
+      const args = Object.entries(bad.args)
+        .map(([k, v]) => '(' + JSON.stringify(k) + ', ' + swiftValue(v) + ')').join(', ')
+      Content(`
+  // An invalid request fails with validate's own error, before it is sent.
+  func testValidate() throws {
+    try XCTSkipUnless(${entity.Name}EntityTest.hasFeature("validate"), "feature not present in this SDK: validate")
+    let client = ${Name}SDK.testSDK(nil, vm(("feature", .map(vm(("validate", .map(vm(("active", .bool(true))))))))))
+    var err: Error? = nil
+    do { _ = try client.${entity.Name}().${bad.op}(vm(${args}), nil) } catch { err = error }
+    XCTAssertEqual((err as? ${Name}Error)?.code, "validate_failed",
+      "expected validate_failed, got \\(String(describing: err))")
+  }
+`)
+    }
+
+    Content(`
+  // True when this SDK was generated with the named feature.
+  static func hasFeature(_ name: String) -> Bool {
+    gp(SdkConfig.makeConfig(), "feature").asMap?.entries[name] != nil
+  }
+}
 `)
   })
 })
 
 
+function swiftValue(v: any): string {
+  return 'number' === typeof v ? '.int(' + v + ')' :
+    'boolean' === typeof v ? '.bool(' + v + ')' : '.string(' + JSON.stringify(v) + ')'
+}
+
+
 export {
   TestEntity
 }

package/project/.sdk/src/cmp/swift/fragment/Entity.fragment.swift

@@ -19,5 +19,7 @@ public final class EntyClass: ProjectNameEntityBase {
 
   // #UpdateOp
 
+  // #PatchOp
+
   // #RemoveOp
 }

package/project/.sdk/src/cmp/swift/fragment/EntityBase.fragment.swift

@@ -80,6 +80,10 @@ open class ProjectNameEntityBase: Entity {
     throw unsupportedOp("update", name)
   }
 
+  open func patch(_ reqdata: VMap?, _ ctrl: VMap?) throws -> Value {
+    throw unsupportedOp("patch", name)
+  }
+
   open func remove(_ reqmatch: VMap?, _ ctrl: VMap?) throws -> Value {
     throw unsupportedOp("remove", name)
   }
@@ -188,7 +192,11 @@ open class ProjectNameEntityBase: Entity {
 
     let signal = opts.entries["signal"]?.asNative as? @Sendable () -> Bool
 
-    let ctrl = opts.entries["ctrl"]?.asMap ?? VMap()
+    // A copy: the caller's ctrl gains no key, and explain stays its own record.
+    let ctrl = VMap()
+    if let given = opts.entries["ctrl"]?.asMap {
+      ctrl.entries = given.entries
+    }
     ctrl.entries["stream"] = .map(opts)
 
     var ctxmap: [String: Any?] = [

package/project/.sdk/src/cmp/swift/fragment/EntityPatchOp.fragment.swift

@@ -0,0 +1,24 @@
+// Patch operation fragment (spliced into the entity class by
+// EntityOperation_swift; only the EJECT region is emitted).
+
+import Foundation
+
+final class EntyClassPatchOpFragment: EntyClass {
+// EJECT-START
+public override func patch(_ reqdata: VMap?, _ ctrl: VMap?) throws -> Value {
+  var ctxmap: [String: Any?] = ["opname": "patch", "match": match, "data": data]
+  if let ctrl = ctrl { ctxmap["ctrl"] = ctrl }
+  if let reqdata = reqdata { ctxmap["reqdata"] = reqdata }
+  let ctx = utility.makeContext(ctxmap, entctx)
+
+  return try runOp(ctx) {
+    if let result = ctx.result {
+      if let rm = result.resmatch { self.match = rm }
+      if !isNil(result.resdata) {
+        self.data = clone(result.resdata).asMap ?? VMap()
+      }
+    }
+  }
+}
+// EJECT-END
+}

package/project/.sdk/src/cmp/swift/fragment/Main.fragment.swift

@@ -107,6 +107,13 @@ public final class ProjectNameSDK {
     let path = gp(fetchargs, "path").asString ?? ""
     var method = gp(fetchargs, "method").asString ?? ""
     if method == "" { method = "GET" }
+    method = method.uppercased()
+
+    if !allowed(gpath(options, "allow", "method"), method) {
+      throw ctx.makeError("spec_method_allow",
+        "Method \"\(method)\" not allowed by SDK option allow.method value: \""
+          + (gpath(options, "allow", "method").asString ?? "") + "\"")
+    }
 
     let pathParams = gp(fetchargs, "params").asMap ?? ProjectNameSdk.VMap()
     let query = gp(fetchargs, "query").asMap ?? ProjectNameSdk.VMap()
@@ -155,8 +162,7 @@ public final class ProjectNameSDK {
 
   // Is this raw-access op permitted by the SDK's allow.op option?
   private func opAllowed(_ op: String) -> Bool {
-    guard let allow = gpath(options, "allow", "op").asString else { return false }
-    return allow.contains(op)
+    return allowed(gpath(options, "allow", "op"), op)
   }
 
   private func opDenied(_ op: String) -> ProjectNameSdk.VMap {
@@ -230,11 +236,25 @@ public final class ProjectNameSDK {
         jsonData = jf()
       }
 
+      var bodyErr: Swift.Error? = nil
+      if !noBody, gp(fm, "unreadable") == .bool(true) {
+        var failed: Swift.Error? = nil
+        if status < 200 || status >= 300 {
+          failed = ctx.makeError(
+            "request_status", "request: \(status): \(gp(fm, "statusText").asString ?? "")")
+        }
+        bodyErr = ProjectNameSdk.Response.unreadableBody(
+          ctx, status, headers, gp(fm, "body"), gp(fetchdef, "headers"), failed)
+      }
+
       let r = ProjectNameSdk.VMap()
-      r.entries["ok"] = .bool(status >= 200 && status < 300)
+      r.entries["ok"] = .bool(bodyErr == nil && status >= 200 && status < 300)
       r.entries["status"] = .int(Int64(status))
       r.entries["headers"] = headers
       r.entries["data"] = jsonData
+      if let bodyErr = bodyErr {
+        r.entries["err"] = utility.clean(ctx, .nat(bodyErr))
+      }
       return r
     }