@amityco/social-plus-vise 0.14.27 → 0.14.28

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to `@amityco/social-plus-vise` are documented in this file.
 
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.14.28 — 2026-06-10
+
+**Theme:** block-aware completeness — install a block, end green. Plus platform-leg hardening: Swift gets the tree-sitter treatment and iOS gets a guarded build sensor.
+
+### Added
+- **Field-level SDK model facts (sdk-facts Phase 4):** `vise sdk-facts` / `get_sdk_facts` no longer prove symbol existence only. The bundled snapshot now includes `sdk-surface/models.<platform>.json` (wire format `2026-06-10.sdk-model-facts.v1`, owned by `packages/schemas/model-facts.schema.json` with a type-only TS twin) carrying capability-anchored model schemas — per field: `name`, `type` (the platform's own string form), `optional`, `memberKind`, and `declaredIn` source anchor — plus full extraction provenance (extractor id/version, timestamp, upstream docs-ops extractor, upstream git commit). `--include-models` (MCP `includeModels`) serves the schemas; capability model entries gain a verbatim `schema`; every result carries a `modelFacts` status so absence is explicit.
+- **Extraction-grounded by construction:** `scripts/extract-sdk-models.mjs` (run by `sdk-surface:import`) grounds each platform mechanically — TypeScript via the compiler API over the local SDK sources (`names-and-types`, including `?` optionality and file:line), Android via dokka signature data (`names-and-types`, Kotlin `?` nullability, doc-prose stripped), iOS/Flutter as `names-only` because their docc-abi/dart exports carry no type data (the schema then forces field `type`/`optional` to `null` — fabricated detail cannot validate). A platform whose field source is unreachable ships no model file and the manifest records why. Scope is limited to the first factory capabilities (comments, reactions, posts, users): npm tarball grew 479.2 kB → 484.2 kB.
+- **Reaction model anchors:** the `reactions` capability now also anchors `Amity.Reactor` and `Amity.Reactable` (the reaction-summary shape blocks actually consume), alongside `Amity.Reaction`.
+
+### Verified (model facts)
+- `test:sdk-surface` locks the manifest `models` map (sha256, per-platform grounding) and one real extracted model per platform — including that `Amity.Comment` carries `userId` but **not** the imagined `creatorId`/`isHidden` fields that previously lived in hand-written factory fixtures.
+- `test:sdk-facts` covers `modelFacts` status, capability schema attachment, `includeModels` capability filtering, names-only null enforcement, and the CLI `--include-models` path.
+- The schemas package self-test validates every committed snapshot against `model-facts.schema.json` and proves the schema bites (11 doctored snapshots fail, including fabricated types under names-only grounding).
+- **Swift AST validators (tree-sitter-swift 0.7.x):** the highest-false-positive-risk iOS rules move from regex to the same tree-sitter helper layer Kotlin uses (`tree-sitter-swift` is the maintained alex-pinkus grammar; its node shapes descend from the Kotlin grammar, so `findCallExpressions` shares the walk and adds Swift labeled-argument extraction via the new `pickLabeledArgument`). Migrated rules — ids, severities, and pass/fail semantics unchanged, only precision improved:
+  - `ios.auth.no-literal-user-id`, `ios.secret.inline-api-key`, `ios.feed.target.literal` now resolve **indirect literals** (`let FALLBACK_USER = "demo-user-42"` … `login(userId: FALLBACK_USER)`) that the call-site regex could never see — proven by the new `ios-userid-via-constant` / `ios-secret-via-constant` / `ios-feed-target-via-constant` fixtures.
+  - `ios.session-handler.retained` asks the real scope question (is the binding inside a function body?) instead of bridging 200 chars from any `func … {`. A bare class-scope `let sessionHandler = …` directly after a short function used to false-fire (the rescue pattern demanded an access modifier); the new `ios-session-handler-class-scope-bare` fixture locks the fix. Type-annotated locals (`let h: AmitySessionHandler = …`) the regex bridge missed are now caught.
+  - `ios.user.ban-state-respected` detects its interaction surface on the comment-stripped view — `// TODO: wire createPost here` no longer counts as an interaction (new `ios-ban-state-comment-only` fixture); the `// vise: ban state checked at` escape hatch deliberately stays on raw text.
+  - All Swift gate rules now use the precise tree-sitter comment stripper, chained onto the conservative scanner so bindings-unavailable/oversized files degrade to the previous behavior, never to raw text. `ios-happy-path` stays at zero findings (FP canary), and a missing `tree-sitter-swift` prebuild degrades only the Swift helpers — ts/tsx/kotlin AST stays up.
+- **Dart AST honestly skipped:** every Dart grammar on npm fails against the pinned `tree-sitter@^0.21` (stale nan binding, ≥0.22-only API, forked core, WASM-only, or an unmaintained vendor-internal fork). Dart rules remain regex + conservative scanner; the verdict and re-evaluation trigger are recorded in ARCHITECTURE.md.
+- **iOS build sensor — guarded best-effort (revises the old "xcodebuild is too fragile to wire" decision):** an `.xcodeproj`/`.xcworkspace` at the surface root now enables two sensors, **only when `xcodebuild` is on PATH** — absent, `vise run-sensors` reports the sensor `skipped` with the install-Xcode precondition (the pf-003 visible-precondition pattern) instead of returning no-sensors. When runnable: a cheap `xcodebuild -list` integrity probe, then a bounded-timeout build with signing disabled (`CODE_SIGNING_ALLOWED=NO`/`CODE_SIGNING_REQUIRED=NO`/`CODE_SIGN_IDENTITY=`). Non-zero exits are classified before being reported: environment-caused failures (Command-Line-Tools-only `xcode-select`, unaccepted Xcode license, signing/provisioning demands, missing simulator/SDK destination, undeterminable workspace scheme) become **skipped-with-reason and exit 0** — never project failure — while real compile/link errors stay `failed` with a non-zero CLI exit (pf-004-era semantics). The classification channel is a new serializable `environmentSkips` field on command sensors, available to any future toolchain with the same exit-code conflation. Locked by a stub-`xcodebuild` controlled-PATH matrix in `test:sensors` (detected+green, detected+real-failure, environmental skips, absent toolchain).
+- **Installed blocks satisfy completeness baselines:** `vise check` previously scanned customer source only, so a capability delivered inside an installed Block Factory package (e.g. the Comments block's composer) still reported `completeness-gap` (exit 5). Now a checklist capability counts as present with evidence `source: "block:<blockId>"` (and a note naming the block) when an installed sidecar entry declares it and the install is still locally valid.
+- **Factory declares, Vise validates:** Block Factory contracts declare `providesCapabilities` using Vise's completeness-checklist id vocabulary (Vise owns the id space, the factory owns the per-block claim; an empty list is legitimate — the Reactions block provides no baseline ids). `vise blocks plan`/`add` carry the registry entry's ids into the install plan and `--apply` records them — plus the manifest `dependencyName` — in `sp-vise/blocks.json` (sidecar `schemaVersion` bumped to `2026-06-10.vise-blocks-sidecar.v1`).
+- **Seam guard:** `vise blocks plan`/`add`/`validate` emit a `blocks.providesCapabilities.known` **warning** finding (never a failure) for declared ids outside Vise's completeness vocabulary; unknown ids never satisfy a gap.
+
+### Changed
+- **Skill: bounded-turn stop guidance.** Agents running in one-shot/print mode are told to reach a `vise check` verdict before the turn ends rather than ending mid-environment-setup (finding from the first semantic harness-E2E measurement).
+- **Gap returns on drift:** the block evidence is registry-free and re-validated on every `vise check` — the block's dependency must still be declared in the project manifest and every recorded `filesTouched` path must exist. Remove the touched source file or the package and the capability reverts to the normal `completeness-gap`. Pre-`0.14.28` sidecar entries carry no package evidence and fail closed.
+
+### Verified
+- `test:ast` extended with the Swift section: grammar availability, labeled-argument call extraction, identifier→literal resolution (with the env-fallback `?? ""` and interpolated-string non-resolution cases), comment stripping that preserves `//` inside strings, function-local vs type-scope handler declarations, the three indirect-literal fixtures, and the two false-positive-kill fixtures (each verified to fire under the pre-change regexes). `ios-happy-path` asserted at zero findings; existing `ios-session-handler-local-var`/`-retained` pass/fail semantics asserted unchanged.
+- `test:sensors` gains the stub-`xcodebuild` controlled-PATH matrix: detection with/without the toolchain, detected+green (exit 0), detected+real-build-failure (exit 1, not environment-skipped), no-simulator and CLT-only environmental skips (exit 0), and the absent-toolchain skip end to end.
+- New `test:blocks-completeness` gate: real `blocks add --apply` against the monorepo Block Factory registry, init with answers, `check --ci` green via `block:comments` evidence, gap restored after deleting a touched file and after removing the manifest dependency, empty `providesCapabilities` tolerated end to end, and the unknown-id warning on a doctored registry.
+- The Block Factory react target-project journey (`validate:target-projects:react`) now asserts the full install journey ends **green** with `comment-composer` satisfied by `block:comments`.
+
+### Internal
+- **Registry seam contract extracted to `packages/schemas`:** the block-registry wire format and the `sp-vise/blocks.json` sidecar shape now live in the root workspace package `@amityco/social-plus-schemas` (private, unpublished) — a JSON Schema (`registry.schema.json`) enforced on the factory's `validate:registry`, plus the TypeScript types formerly hand-written in `src/tools/blocks.ts`. Vise imports them **type-only** via a `workspace:*` devDependency, so nothing from the package survives into the published `dist/` (proven by the packed-tarball E2E). Type-only refactor; no behavior change.
+
+### Fixed
+- **Attestation evidence fingerprints no longer truncate prose-embedded paths:** the source-path extractor's extension alternation was shortest-first, so `.tsx`→`.ts`, `.json`→`.js`, and `.kts`→`.kt` inside evidence prose silently recorded no fingerprint (weakening drift detection for that attestation). Found by the harness E2E attestation stage, which now cites paths in prose as the standing regression test.
+
+
 ## 0.14.27 — 2026-06-10
 
 **Theme:** social-plus-forge monorepo move. No runtime behavior changes.

package/README.md

@@ -77,9 +77,9 @@ Vise validates on three layers, and the layer is set by the *kind of claim* —
 |---|---|---|---|
 | **SDK compliance** | "this is **wrong**" | 300+ deterministic rules (session renewal, live-collection vs one-shot, no secret in logs, parent-child rendering, ban-state gating…) | **Hard gate** — `vise check` blocks until green or attested. A small advisory subset surfaces as informational only and never blocks. |
 | **Design conformance** | "this **looks off**" | extract the customer's design system into a contract, render a preview for confirmation, then check token usage | **Advisory** — `vise design check`/`preview`; never fails a build |
-| **Feature completeness** | "this is **missing**" | Vise proposes a narrow baseline per outcome; for add-feed, pagination is mandatory, for add-comments, the composer/write affordance is mandatory, for add-chat, send plus read/unread state are mandatory, and for add-follow/profile, SDK-backed follower/following data is mandatory, while richer feed capabilities are opt-in choices from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline capability is built or validly opted out; selected optional capabilities run separate sensors |
+| **Feature completeness** | "this is **missing**" | Vise proposes a narrow baseline per outcome; for add-feed, pagination is mandatory, for add-comments, the composer/write affordance is mandatory, for add-chat, send plus read/unread state are mandatory, and for add-follow/profile, SDK-backed follower/following data is mandatory, while richer feed capabilities are opt-in choices from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline capability is built, satisfied by an installed Block Factory block (evidence `source: "block:<id>"`, re-validated locally on every check), or validly opted out; selected optional capabilities run separate sensors |
 
-Correctness is gated by deterministic rules or attestations. Baseline completeness is gated by explicit scope decisions: if a baseline capability is legitimately out of scope, record `// vise: scope-omit <id> — <reason>` and it no longer blocks. Optional feed capabilities such as image upload, poll creation, and edit post are offered during planning and become checked only after the user opts in. Conformance remains advisory because "matches the brand" is legitimately subjective. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Correctness is gated by deterministic rules or attestations. Baseline completeness is gated by explicit scope decisions: if a baseline capability is legitimately out of scope, record `// vise: scope-omit <id> — <reason>` and it no longer blocks. Installed Block Factory blocks count too: the factory declares the completeness ids a block provides (`providesCapabilities`), `vise blocks add --apply` records them in `sp-vise/blocks.json`, and `vise check` honours them only while the block's manifest dependency and touched files are intact — on drift the gap returns. Optional feed capabilities such as image upload, poll creation, and edit post are offered during planning and become checked only after the user opts in. Conformance remains advisory because "matches the brand" is legitimately subjective. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### Engagement Intelligence roadmap
 
@@ -232,7 +232,7 @@ The benchmark suite is intentionally reported with boundaries:
 | **React Native** | ✅ Full | `tsc`, `npm lint`, SDK import smoke |
 | **Flutter / Dart** | ✅ Full | `flutter analyze`, `flutter test` |
 | **Android (Kotlin)** | ✅ Full | Gradle assemble, unit tests |
-| **iOS (Swift)** | ✅ Full | Static rule checks fully operational. Build sensor not wired (`xcodebuild` environment requirements make it fragile) — `vise run-sensors` returns no-sensors for iOS; compliance rules run regardless. |
+| **iOS (Swift)** | ✅ Full | Static rule checks fully operational (highest-risk rules use the Swift tree-sitter AST). Build sensor is **guarded best-effort**: an `.xcodeproj`/`.xcworkspace` enables an `xcodebuild -list` integrity probe plus a signing-disabled build — only when `xcodebuild` is on PATH (absent → skipped with the visible precondition). Environment-caused failures (no simulator runtime, Command-Line-Tools-only `xcode-select`, signing demands, unaccepted license) report **skipped-with-reason**, never project failure; a real build failure still exits non-zero. |
 
 Each platform has dozens of rules across 10 compliance domains (feed, comments, moderation, chat, secrets, session & auth, notifications, live objects, logging hygiene, design tokens).
 

package/dist/capabilities.js

@@ -1187,6 +1187,50 @@ function baselineCapabilities(outcome) {
 export function capabilityChecklist(outcome) {
     return baselineCapabilities(outcome).map((c) => ({ id: c.id, label: c.label, hint: c.hint }));
 }
+/**
+ * The Vise-owned completeness id vocabulary — every id a Block Factory contract
+ * may reference in `providesCapabilities`. Vise owns this id space; the factory
+ * owns the per-block declaration (see block-factory/docs/vise-boundary.md).
+ */
+export function completenessCapabilityIds() {
+    return new Set(CAPABILITIES.map((capability) => capability.id));
+}
+/**
+ * Overlay installed-block evidence onto a source-scan completeness assessment.
+ * A still-missing checklist capability becomes present with evidence
+ * `source: "block:<blockId>"` when a locally validated installed block declares
+ * it in `providesCapabilities`. Callers are responsible for the local validation
+ * (package declared + filesTouched intact); on drift they must simply not pass
+ * the capability here, so the normal gap returns.
+ */
+export function applyBlockProvidedCompleteness(assessment, provided) {
+    if (provided.length === 0 || assessment.missing.length === 0) {
+        return assessment;
+    }
+    const blockByCapability = new Map();
+    for (const item of provided) {
+        if (!blockByCapability.has(item.capabilityId)) {
+            blockByCapability.set(item.capabilityId, item.blockId);
+        }
+    }
+    const present = [...assessment.present];
+    const missing = [];
+    for (const item of assessment.missing) {
+        const blockId = blockByCapability.get(item.id);
+        if (blockId) {
+            present.push({
+                id: item.id,
+                label: item.label,
+                source: `block:${blockId}`,
+                note: `Satisfied by installed block "${blockId}" (sp-vise/blocks.json): the block package delivers this capability and its local install validation passed.`,
+            });
+        }
+        else {
+            missing.push(item);
+        }
+    }
+    return { ...assessment, present, missing };
+}
 /** Optional feed-forward choices. These are not baseline completeness requirements. */
 export function optionalCapabilityChecklist(outcome, availableIds) {
     const available = availableIds ? new Set(availableIds) : undefined;

package/dist/server.js

@@ -342,7 +342,7 @@ async function handleCli(args) {
             return "exit";
         }
         if (command === "sdk-facts" || command === "sdk_facts") {
-            assertOnlyKnownFlags(args, ["platform", "capability", "surface-dir", "format", "include-symbols"], "sdk-facts");
+            assertOnlyKnownFlags(args, ["platform", "capability", "surface-dir", "format", "include-symbols", "include-models"], "sdk-facts");
             const format = flagValue(args, "format") ?? "json";
             if (format !== "json") {
                 throw new Error("sdk-facts currently supports --format json only.");
@@ -352,6 +352,7 @@ async function handleCli(args) {
                 capability: flagValue(args, "capability"),
                 surfaceDir: flagValue(args, "surface-dir"),
                 includeSymbols: hasFlag(args, "include-symbols"),
+                includeModels: hasFlag(args, "include-models"),
             });
             return "exit";
         }
@@ -776,10 +777,15 @@ Usage:
         return `${packageName} sdk-facts
 
 Read bundled SDK surface facts for social.plus Block Factory planning. Internal, projectless, and read-only.
+Symbol facts prove existence; --include-models adds extraction-grounded field-level model schemas
+(modelSchemas, plus capability model entries gain a schema). Platforms without grounded field data
+report modelFacts.status=absent instead of fabricated fields.
 
 Usage:
   vise sdk-facts --platform typescript --capability comments --format json
+  vise sdk-facts --platform typescript --capability comments --include-models
   vise sdk-facts --platform react-native --capability reactions --include-symbols
+  vise sdk-facts --platform android --include-models --format json
   vise sdk-facts --platform android --surface-dir ./sdk-surface --format json`;
     }
     if (command === "blocks") {

package/dist/tools/ast.js

@@ -29,11 +29,21 @@ function loadNativeBindings() {
         const ParserCtor = nodeRequire("tree-sitter");
         const tsGrammars = nodeRequire("tree-sitter-typescript");
         const kotlinGrammar = nodeRequire("tree-sitter-kotlin");
+        // Swift loads in its own try/catch: a missing tree-sitter-swift prebuild on an
+        // exotic platform must degrade ONLY the Swift helpers, not all AST analysis.
+        let swiftGrammar = null;
+        try {
+            swiftGrammar = nodeRequire("tree-sitter-swift");
+        }
+        catch {
+            swiftGrammar = null;
+        }
         nativeBindings = {
             Parser: ParserCtor,
             tsGrammar: tsGrammars.typescript,
             tsxGrammar: tsGrammars.tsx,
             kotlinGrammar,
+            swiftGrammar,
         };
     }
     catch {
@@ -50,6 +60,14 @@ function loadNativeBindings() {
 export function astAvailable() {
     return loadNativeBindings() !== null;
 }
+/**
+ * Whether the Swift grammar specifically is available. tree-sitter-swift is loaded
+ * independently of the core bindings (see loadNativeBindings), so Swift-only
+ * validators can check this and fall back to regex without disabling ts/tsx/kotlin.
+ */
+export function swiftAstAvailable() {
+    return loadNativeBindings()?.swiftGrammar != null;
+}
 /**
  * Strip comments from source code using tree-sitter AST.
  * Replaces comment spans with whitespace (preserving line structure).
@@ -101,6 +119,12 @@ function getParser(language) {
             parser.setLanguage(native.tsxGrammar);
         else if (language === "kotlin")
             parser.setLanguage(native.kotlinGrammar);
+        else if (language === "swift") {
+            if (native.swiftGrammar == null) {
+                throw new Error("tree-sitter-swift unavailable; Swift AST analysis disabled (regex fallback in effect)");
+            }
+            parser.setLanguage(native.swiftGrammar);
+        }
         else
             parser.setLanguage(native.tsGrammar);
         parsers.set(language, parser);
@@ -166,7 +190,10 @@ export function findCallExpressions(tree, calleePattern) {
             results.push({ callee, node, args });
             return;
         }
-        // Kotlin: call_expression = navigation_expression + call_suffix
+        // Kotlin AND Swift: call_expression = navigation_expression + call_suffix.
+        // (tree-sitter-swift descends from the Kotlin grammar, so the node names —
+        // navigation_expression / navigation_suffix / call_suffix / value_arguments —
+        // are identical; only Swift's labeled arguments add a value_argument_label.)
         const navNode = node.namedChild(0);
         const suffixNode = node.namedChild(1);
         if (!navNode || !suffixNode || suffixNode.type !== "call_suffix")
@@ -181,8 +208,11 @@ export function findCallExpressions(tree, calleePattern) {
             for (let i = 0; i < valArgsNode.namedChildCount; i++) {
                 const valArg = valArgsNode.namedChild(i);
                 if (valArg && valArg.type === "value_argument") {
-                    // The actual expression is inside value_argument
-                    const expr = valArg.namedChild(0);
+                    // The actual expression is inside value_argument. Swift labeled arguments
+                    // put a value_argument_label first — the value is the last named child.
+                    // Kotlin behaviour (namedChild(0)) is intentionally unchanged.
+                    const first = valArg.namedChild(0);
+                    const expr = first?.type === "value_argument_label" ? valArg.namedChild(valArg.namedChildCount - 1) : first;
                     if (expr)
                         args.push(expr);
                 }
@@ -233,6 +263,93 @@ export function pickObjectProperty(objectNode, propertyName) {
     }
     return undefined;
 }
+/**
+ * Pick the value of a labeled argument from a Swift call expression node.
+ * E.g., from `client.login(userId: HARDCODED, sessionHandler: handler)`,
+ * pick the value node for label "userId".
+ *
+ * Swift-shaped trees only (call_suffix → value_arguments → value_argument with a
+ * value_argument_label). Returns undefined when the label is absent.
+ */
+export function pickLabeledArgument(callNode, label) {
+    for (let i = 0; i < callNode.namedChildCount; i++) {
+        const suffix = callNode.namedChild(i);
+        if (!suffix || suffix.type !== "call_suffix")
+            continue;
+        const valArgs = suffix.namedChild(0);
+        if (!valArgs || valArgs.type !== "value_arguments")
+            continue;
+        for (let j = 0; j < valArgs.namedChildCount; j++) {
+            const valArg = valArgs.namedChild(j);
+            if (!valArg || valArg.type !== "value_argument")
+                continue;
+            const first = valArg.namedChild(0);
+            if (first?.type !== "value_argument_label" || first.text !== label)
+                continue;
+            const value = valArg.namedChild(valArg.namedChildCount - 1);
+            // namedChild(last) === the label itself when the argument has no value
+            // (selector-reference form) — treat as absent.
+            return value && value !== first ? value : undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Find Swift `let`/`var` declarations whose initializer text matches a pattern AND
+ * which are function-local (declared inside a function/initializer/closure/computed-
+ * property body rather than at type or file scope). Used for retention rules: a
+ * function-local binding dies with the stack frame, while a type-scope property
+ * lives with the object — a distinction regex bridges cannot make reliably.
+ *
+ * Conservative direction: a declaration only counts as local when a KNOWN
+ * function-ish ancestor encloses it, so unknown containers degrade toward
+ * "retained" (quiet), never toward a false positive.
+ */
+export function findSwiftFunctionLocalDeclarations(tree, initializerPattern) {
+    const results = [];
+    walkTree(tree.rootNode, (node) => {
+        if (node.type !== "property_declaration")
+            return;
+        const value = swiftPropertyInitializer(node);
+        if (!value || !initializerPattern.test(value.text))
+            return;
+        if (hasFunctionAncestor(node))
+            results.push(node);
+    });
+    return results;
+}
+const SWIFT_FUNCTION_SCOPES = new Set([
+    "function_declaration",
+    "init_declaration",
+    "deinit_declaration",
+    "lambda_literal",
+    "computed_property",
+    "computed_getter",
+    "computed_setter",
+]);
+function hasFunctionAncestor(node) {
+    let current = node.parent;
+    while (current) {
+        if (SWIFT_FUNCTION_SCOPES.has(current.type))
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+/** The initializer expression of a Swift property_declaration (the value after `=`), if any. */
+function swiftPropertyInitializer(node) {
+    // Shape: property_declaration = value_binding_pattern, pattern, [type_annotation], [value expr]
+    // The initializer (when present) is the last named child and is none of the structural parts.
+    const last = node.namedChild(node.namedChildCount - 1);
+    if (!last)
+        return undefined;
+    if (["value_binding_pattern", "pattern", "type_annotation", "modifiers", "attribute"].includes(last.type))
+        return undefined;
+    // computed_property is a body, not an initializer.
+    if (last.type === "computed_property")
+        return undefined;
+    return last;
+}
 // ── Internal helpers ──────────────────────────────────────────────────────────
 function walkTree(node, visit) {
     visit(node);
@@ -322,6 +439,25 @@ function extractStringLiteral(node) {
             return text.slice(1, -1);
         }
     }
+    // Swift: line_string_literal contains line_str_text chunks; an interpolated
+    // string has >1 named child (line_str_text + interpolated_expression) and is
+    // NOT statically resolvable — mirror the TS template-literal treatment.
+    if (node.type === "line_string_literal") {
+        if (node.namedChildCount === 0)
+            return ""; // empty string ""
+        if (node.namedChildCount === 1 && node.namedChild(0)?.type === "line_str_text") {
+            return node.namedChild(0).text;
+        }
+        return undefined;
+    }
+    // Swift: multi-line """…""" literal. Swift semantics strip the newline after the
+    // opening and before the closing delimiter.
+    if (node.type === "multi_line_string_literal") {
+        if (node.namedChildCount === 1 && node.namedChild(0)?.type === "multi_line_str_text") {
+            return node.namedChild(0).text.replace(/^\n/, "").replace(/\n[ \t]*$/, "");
+        }
+        return undefined;
+    }
     return undefined;
 }
 function resolveIdentifierToLiteral(name, root) {
@@ -345,15 +481,31 @@ function resolveIdentifierToLiteral(name, root) {
         // Kotlin: property_declaration with variable_declaration + string_literal
         if (node.type === "property_declaration") {
             const varDecl = node.namedChildren.find((c) => c.type === "variable_declaration");
-            if (!varDecl)
+            if (varDecl) {
+                const idNode = varDecl.namedChildren.find((c) => c.type === "simple_identifier");
+                if (!idNode || idNode.text !== name)
+                    return;
+                const strLit = node.namedChildren.find((c) => c.type === "string_literal");
+                if (!strLit)
+                    return;
+                const literal = extractStringLiteral(strLit);
+                if (literal !== undefined)
+                    result = literal;
+                return;
+            }
+            // Swift: property_declaration with pattern → simple_identifier; the string
+            // literal must be a DIRECT child (the initializer) — a literal nested inside
+            // e.g. `env["KEY"] ?? ""` is not a static binding and must not resolve.
+            const pattern = node.namedChildren.find((c) => c.type === "pattern");
+            if (!pattern)
                 return;
-            const idNode = varDecl.namedChildren.find((c) => c.type === "simple_identifier");
-            if (!idNode || idNode.text !== name)
+            const swiftId = pattern.namedChildren.find((c) => c.type === "simple_identifier");
+            if (!swiftId || swiftId.text !== name)
                 return;
-            const strLit = node.namedChildren.find((c) => c.type === "string_literal");
-            if (!strLit)
+            const swiftLit = node.namedChildren.find((c) => c.type === "line_string_literal" || c.type === "multi_line_string_literal");
+            if (!swiftLit)
                 return;
-            const literal = extractStringLiteral(strLit);
+            const literal = extractStringLiteral(swiftLit);
             if (literal !== undefined)
                 result = literal;
         }

package/dist/tools/blocks.js

@@ -1,9 +1,11 @@
 import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { completenessCapabilityIds } from "../capabilities.js";
 import { packageVersion } from "../version.js";
 import { inspectProject } from "./project.js";
 import { detectCommandSensors } from "./harness.js";
 import { readDesignContract } from "./design.js";
+const blocksSidecarSchemaVersion = "2026-06-10.vise-blocks-sidecar.v1";
 const registryPlatformByVisePlatform = {
     typescript: "react",
     "react-native": "react-native",
@@ -21,6 +23,7 @@ export async function listRegistryBlocks(registryPath) {
             status: block.status,
             surfaces: block.surfaces,
             requiredSdkCapabilities: block.requiredSdkCapabilities,
+            providesCapabilities: providesCapabilitiesFor(block),
             events: block.events,
         })),
     };
@@ -88,7 +91,8 @@ export async function validateBlockInstall(options) {
     const repoPath = requiredRepoPath(options);
     const sidecar = await readSidecar(repoPath);
     const installed = (sidecar?.installed ?? []).filter((entry) => !options.blockId || entry.blockId === options.blockId);
-    const findings = [];
+    // Seed with plan findings so the providesCapabilities seam guard also surfaces in validate mode.
+    const findings = [...plan.findings];
     if (installed.length === 0) {
         findings.push({
             ruleId: "blocks.sidecar.installed",
@@ -154,6 +158,18 @@ async function buildInstallPlan(options, mode) {
             stopConditions.push(`Missing safe install anchor ${targetFile.anchor} in ${targetFile.path}.`);
         }
     }
+    // Seam guard: the factory declares providesCapabilities, but Vise owns the
+    // completeness id vocabulary. Unknown ids warn (never block) — they simply
+    // can't satisfy a completeness gap in `vise check`.
+    const providesCapabilities = providesCapabilitiesFor(block);
+    const knownCapabilityIds = completenessCapabilityIds();
+    const unknownCapabilityIds = providesCapabilities.filter((id) => !knownCapabilityIds.has(id));
+    const findings = unknownCapabilityIds.map((id) => ({
+        ruleId: "blocks.providesCapabilities.known",
+        severity: "warning",
+        message: `Block ${block.blockId} declares providesCapabilities id "${id}", which is not in this Vise's completeness checklist vocabulary.`,
+        recommendation: "Unknown ids never satisfy completeness gaps. Align the Block Factory contract with Vise's capability catalog (vise owns the id space) or upgrade Vise.",
+    }));
     return {
         status: stopConditions.length > 0 ? "needs-review" : "ready",
         mode,
@@ -168,11 +184,19 @@ async function buildInstallPlan(options, mode) {
         packageSource: options.packageSource,
         packageChange,
         targetFiles,
+        providesCapabilities,
+        findings,
         sensors: sensors.map((sensor) => ({ name: sensor.name, command: sensor.command, source: sensor.source })),
         stopConditions,
         sidecarPath: path.join("sp-vise", "blocks.json"),
     };
 }
+function providesCapabilitiesFor(block) {
+    if (!Array.isArray(block.providesCapabilities)) {
+        return [];
+    }
+    return [...new Set(block.providesCapabilities.filter((id) => typeof id === "string" && id.trim() !== ""))];
+}
 async function loadRegistry(registryPath) {
     if (!registryPath) {
         throw new Error("blocks command requires --registry <path>.");
@@ -286,7 +310,7 @@ async function writeBlocksSidecar(repoPath, plan, packageSource, filesTouched) {
     const sidecarPath = path.join(repoPath, "sp-vise", "blocks.json");
     const existing = await readSidecar(repoPath);
     const sidecar = existing ?? {
-        schemaVersion: "2026-06-04.vise-blocks-sidecar.v1",
+        schemaVersion: blocksSidecarSchemaVersion,
         viseVersion: packageVersion,
         generatedAt: new Date().toISOString(),
         installed: [],
@@ -296,11 +320,14 @@ async function writeBlocksSidecar(repoPath, plan, packageSource, filesTouched) {
         blockVersion: plan.block.version,
         platform: plan.registryPlatform,
         packageSource,
+        dependencyName: plan.package.dependencyName,
+        providesCapabilities: plan.providesCapabilities,
         filesTouched,
         designContractDigest: designContract?.digest,
         sdkFactsVersion: plan.block.version,
         validationStatus: "installed",
     };
+    sidecar.schemaVersion = blocksSidecarSchemaVersion;
     sidecar.viseVersion = packageVersion;
     sidecar.generatedAt = new Date().toISOString();
     sidecar.installed = [...sidecar.installed.filter((item) => item.blockId !== plan.block.id), entry];
@@ -317,6 +344,72 @@ async function readSidecar(repoPath) {
         return null;
     }
 }
+/**
+ * Registry-free evidence that installed blocks deliver completeness capabilities.
+ *
+ * `vise check` cannot assume registry access, so a sidecar entry's
+ * `providesCapabilities` only counts when the install is still locally valid:
+ * the block's manifest dependency is declared in the project's package manifest
+ * AND every recorded `filesTouched` path still exists. On drift (file removed,
+ * package gone, pre-providesCapabilities sidecar) the entry contributes nothing
+ * and the capability reverts to the normal completeness gap.
+ */
+export async function installedBlockProvidedCapabilities(repoPath) {
+    const repoRoot = path.resolve(repoPath);
+    const sidecar = await readSidecar(repoRoot);
+    if (!sidecar || !Array.isArray(sidecar.installed)) {
+        return [];
+    }
+    const provided = [];
+    for (const entry of sidecar.installed) {
+        const capabilities = Array.isArray(entry.providesCapabilities)
+            ? entry.providesCapabilities.filter((id) => typeof id === "string" && id.trim() !== "")
+            : [];
+        if (capabilities.length === 0) {
+            continue;
+        }
+        if (!(await installedEntryLocallyValid(repoRoot, entry))) {
+            continue;
+        }
+        for (const capabilityId of capabilities) {
+            provided.push({ capabilityId, blockId: entry.blockId });
+        }
+    }
+    return provided;
+}
+async function installedEntryLocallyValid(repoRoot, entry) {
+    if (!(await blockDependencyDeclared(repoRoot, entry))) {
+        return false;
+    }
+    for (const touched of entry.filesTouched ?? []) {
+        if (typeof touched !== "string" || touched.trim() === "") {
+            return false;
+        }
+        if (!(await exists(path.join(repoRoot, touched)))) {
+            return false;
+        }
+    }
+    return true;
+}
+async function blockDependencyDeclared(repoRoot, entry) {
+    const dependencyName = entry.dependencyName;
+    if (!dependencyName) {
+        // Pre-2026-06-10 sidecars carry no package evidence; fail closed so the gap stays.
+        return false;
+    }
+    if (entry.platform === "flutter") {
+        const source = await readFile(path.join(repoRoot, "pubspec.yaml"), "utf8").catch(() => "");
+        return new RegExp(`\\b${escapeRegExp(dependencyName)}\\s*:`).test(source);
+    }
+    try {
+        const packageJson = await readPackageJson(path.join(repoRoot, "package.json"));
+        const devDependencies = packageJson.devDependencies;
+        return Boolean(packageJson.dependencies?.[dependencyName] ?? devDependencies?.[dependencyName]);
+    }
+    catch {
+        return false;
+    }
+}
 function dependencyValue(root, packageInfo, packageSource, platform) {
     if (!packageSource || packageSource === "npm") {
         return platform === "flutter" ? "^0.1.0" : "^0.1.0";

package/dist/tools/compliance.js

@@ -2,12 +2,13 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { assessProjectCompleteness, assessProjectSelectedOptionalCapabilities, availableOptionalCapabilityIds, optionalCapabilityChecklist, platformCapabilityAvailability, selectedOptionalCapabilityIds, } from "../capabilities.js";
+import { applyBlockProvidedCompleteness, assessProjectCompleteness, assessProjectSelectedOptionalCapabilities, availableOptionalCapabilityIds, optionalCapabilityChecklist, platformCapabilityAvailability, selectedOptionalCapabilityIds, } from "../capabilities.js";
 import { getOutcomeDefinition, hasAnswer, planContextFor, resolveOutcome, } from "../outcomes.js";
 import { contractRuleCandidatesForPublicId, hasMultipleContractRuleCandidates, productExpectationBindingForSensor, productExpectationTitle, publicProductRuleId, } from "../productExpectations.js";
 import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
 import { DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID, buildDesignBrief, designContractConfirmationFromAnswers, designPreviewPath, readDesignContract, } from "./design.js";
+import { installedBlockProvidedCapabilities } from "./blocks.js";
 import { inspectProject, validateSetup } from "./project.js";
 import { readCreativeSelection } from "./creative.js";
 import { assessUxHarness, buildExperienceReport, buildUxHarness, readUxHarness, } from "./uxHarness.js";
@@ -737,7 +738,17 @@ export async function checkCompliance(repoPath) {
     // Completeness-gap: capabilities that are neither present nor validly opted-out require an explicit decision
     // (build it, or place // vise: scope-omit <id> — <reason>). The scope-omit escape hatch keeps this
     // FP-free because any capability can be excluded with a recorded reason. Failure to assess is silently ignored.
-    const completeness = (await assessProjectCompleteness(inspection.effectiveRoot, compliance.outcome).catch(() => null)) ?? undefined;
+    const sourceCompleteness = (await assessProjectCompleteness(inspection.effectiveRoot, compliance.outcome).catch(() => null)) ?? undefined;
+    // Installed Block Factory blocks deliver capabilities inside their packages,
+    // which the customer-source scan cannot see. Overlay block evidence for
+    // still-missing checklist items, but only from sidecar entries that pass
+    // registry-free local validation (manifest dependency declared + every
+    // filesTouched path intact — see installedBlockProvidedCapabilities). On
+    // local drift the evidence is withheld and the normal gap returns.
+    const blockProvided = sourceCompleteness && sourceCompleteness.missing.length > 0
+        ? await installedBlockProvidedCapabilities(repoRoot).catch(() => [])
+        : [];
+    const completeness = sourceCompleteness ? applyBlockProvidedCompleteness(sourceCompleteness, blockProvided) : undefined;
     const hasCompletenessGap = (completeness?.missing.length ?? 0) > 0;
     const selectedOptionalCapabilities = (await assessProjectSelectedOptionalCapabilities(inspection.effectiveRoot, compliance.outcome, compliance.selected_optional_capabilities ?? []).catch(() => null)) ?? undefined;
     const hasSelectedOptionalFailures = ((selectedOptionalCapabilities?.failed.length ?? 0) > 0) || ((selectedOptionalCapabilities?.unknown.length ?? 0) > 0);
@@ -1337,7 +1348,7 @@ function sourcePathCandidatesFromString(value) {
     if (looksLikeSourcePath(trimmed)) {
         candidates.add(trimmed);
     }
-    const pathPattern = /(?:[A-Za-z0-9_@.-]+\/)+[A-Za-z0-9_@.-]+\.(?:ts|tsx|js|jsx|kt|java|dart|swift|xml|gradle|kts|json|ya?ml|env|plist|pbxproj|podspec)|\b(?:Podfile|Package\.swift|pubspec\.yaml|package\.json|AndroidManifest\.xml)\b/g;
+    const pathPattern = /(?:[A-Za-z0-9_@.-]+\/)+[A-Za-z0-9_@.-]+\.(?:tsx|ts|jsx|json|js|kts|kt|java|dart|swift|xml|gradle|ya?ml|env|plist|pbxproj|podspec)|\b(?:Podfile|Package\.swift|pubspec\.yaml|package\.json|AndroidManifest\.xml)\b/g;
     for (const match of trimmed.matchAll(pathPattern)) {
         candidates.add(match[0]);
     }
@@ -1346,7 +1357,7 @@ function sourcePathCandidatesFromString(value) {
 function looksLikeSourcePath(value) {
     return (/[/\\]/.test(value) ||
         /^(?:Podfile|Package\.swift|pubspec\.yaml|package\.json|AndroidManifest\.xml)$/.test(value) ||
-        /\.(?:ts|tsx|js|jsx|kt|java|dart|swift|xml|gradle|kts|json|ya?ml|env|plist|pbxproj|podspec)(?::\d+)?$/i.test(value));
+        /\.(?:tsx|ts|jsx|json|js|kts|kt|java|dart|swift|xml|gradle|ya?ml|env|plist|pbxproj|podspec)(?::\d+)?$/i.test(value));
 }
 function cleanEvidencePathCandidate(value) {
     return value