@amityco/social-plus-vise 0.14.28 → 1.0.1

package/CHANGELOG.md

@@ -4,8 +4,58 @@ 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).
 
+## 1.0.1 — 2026-06-12
+
+Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
+
+### Changed
+- **README rewritten for the public npm page.** Restructured customer-first (what it is → quick start → how it works → evidence → CLI/MCP/CI reference → sidecar contract) and cut from 531 to 308 lines: internal program reporting moved off the public surface, the mermaid diagrams (which npmjs.com renders as raw code blocks) replaced with a numbered flow, relative `docs/` links (which do not resolve from the npm page) removed, and references to pre-release functionality withheld from the public README until announced.
+
+### Internal
+- Unit-level regression case for the prose-embedded source-fingerprint path extractor in `test/run-compliance-helpers.mjs` (the 0.14.28 fix; mutation-verified). No shipped behavior change.
+
+## 1.0.0 — 2026-06-11
+
+**First stable release.** 1.0 is a stability promise about the contract surface, not a new feature: `vise check` exit codes (0–7) and their precedence, the `sp-vise/` sidecar formats (with backward-read + attestation grandfathering now gated by `test:sidecar-compat`), the CLI command and MCP tool surface, the skill's required loop, and the `packages/schemas` wire formats are now under semver — breaking changes require a major bump. See [`docs/V1_READINESS.md`](docs/V1_READINESS.md) for the decision package and evidence basis (5-platform deterministic E2E journeys with all exit codes asserted on every commit; real-agent semantic matrix; three brownfield pilots green with zero Vise findings). This release consolidates everything developed across the 0.14.x-dev line after the published 0.14.28 (block-aware completeness): the items below plus the platform-hardening and model-facts work noted under the 0.14.28 entry, which reached npm here.
+
+### Changed
+- **Skill: prefer installable blocks over hand-building.** When a Block Factory registry is available, agents are taught to check it first and use the governed `vise blocks` install path, hand-building only the remaining gaps — backed by the 2026-06-10 semantic-matrix measurement (installed path ~9× faster to green than hand-building the same outcome). No registry means hand-build as normal; block existence stays the registry's truth.
+
+### Added
+- **False-negative discovery lane — the third compass (`docs/FN_DISCOVERY.md`).** Vise already had a TP-detection compass (`bench/tp-dashboard.mjs`, seeded from the rules so circular) and an FP compass (happy-path-clean + clone cells + pilots) but NO systematic false-NEGATIVE discovery — violations the rule corpus misses only surfaced by accident. This lane closes that, mirroring the semantic lane's two-half split:
+  - **Measured lane (periodic, never CI)** — `benchmarks/fn-discovery/run-fn-discovery.mjs`: for a chosen rule, hand a real coding agent the rule's INTENT (title + rationale from `rules/*.yaml`, NOT its detector) and ask for SDK-using samples that violate that intent in novel ways; run `vise validate --json` over each; grade CAUGHT vs MISSED; write append-only dated evidence (samples + validate output + `FINDINGS.md`) under `benchmarks/fn-discovery/runs/<date>-<rule>-<generator>/`. Scoped first to TypeScript × secrets/ban-state/feed-target/session-lifecycle. Generator policy mirrors the semantic lane (default `agy`; `agent`; `claude` pinned to Sonnet). Built and proven with a **deterministic STUB generator** (default) so the grading core is testable without spawning agents or spending tokens; the real-agent path is wired but invoked only with `--generator`, and the live discovery round runs later with explicit human authorization.
+  - **Deterministic gate (CI)** — `test/run-fn-regression.mjs` (`test:fn-regression`): a frozen corpus under `test/fixtures/fn-regression/` of previously-discovered false negatives. `fires` entries assert a rule now fires on a committed sample of a class it once missed (so a fixed blind spot can't silently return); seed entries are realistic catches labeled scaffold so the gate is real and grows; quarantined entries are REAL discovered misses asserted to stay missed until a fix lands, then the gate flips loud and the entry is promoted. The gate never patches a rule — fixes are harness-engineering work with their own review.
+  - **Self-test** — `test/run-fn-discovery-selftest.mjs` (`test:fn-discovery-selftest`): runs the stub samples through the real validator + real grader and asserts every CAUGHT/MISSED/CLEAN-OK verdict against the stub's oracle, locking down the lane's plumbing. Both new gates run in `validate` right after `test:harness-e2e`.
+  - **Real false negatives discovered while building (TypeScript):** (1) `secret.inline-api-key` missed a hardcoded key re-wrapped through a template string before `createClient` (`resolveLiteralValue` resolved direct literals only); (2) `feed.target.literal` missed a feed-target literal re-bound through a second const before `createPost` (the AST resolver followed one identifier hop); (3) `feed.target.literal` missed a hardcoded feed target when the `createPost` payload carried an `as any` cast (`pickObjectProperty` required a bare object node). Controls proved the rules fire at the single-hop / un-cast forms. **All three were then fixed in this release** (see Fixed, below); their corpus entries are promoted from quarantine to `fires`, so each blind spot can never silently reopen.
+- **iOS and Flutter model facts upgraded to `names-and-types`** (previously names-only): `scripts/extract-sdk-models.mjs` now grounds both platforms in typed sources instead of the type-less docs-ops surface exports, completing the per-platform grounding table (typescript/android/ios/flutter all names-and-types). Wire format unchanged (`2026-06-10.sdk-model-facts.v1` — names-and-types was already a legal grounding); the `extraction.sourceKind` enum gains `sdk-swiftmodule-abi` and `sdk-source-dart` in `packages/schemas`.
+  - **iOS** — parsed from the prebuilt AmitySDK xcframework's Swift module ABI JSON, canonically the **`ios-arm64` device slice** (the architecture customers ship and the only single-arch slice; the simulator slices were diffed member-for-member identical for the target models). Fields carry the compiler-printed Swift type (`Swift.String?`, `[AmitySDK.AmityCommentAttachment]`) and Optional-wrapper nullability; `declaredIn` stays `null` because a prebuilt binary has no source locations. Discovery follows the import script's pattern: `--ios-abi-json` / `SP_IOS_ABI_JSON`, then the docs-repo-relative `.docs-ops/integration-tests/ios/vendor/AmitySDK.xcframework/...` location beside the surface dir.
+  - **Flutter** — parsed from the local Flutter SDK sources by the new `scripts/dart-model-extractor` helper (package:analyzer `parseString`, **syntax-only**: verbatim declared types and literal `?` nullability, no resolution or inference; analyzer version pinned by the committed `pubspec.lock` and recorded in the extraction provenance). Public instance fields and getters only; untyped members are skipped rather than invented. Real file:line anchors into the SDK checkout. Discovery: `--flutter-sdk-root` / `SP_FLUTTER_SDK_ROOT`, then the `Amity-Social-Cloud-SDK-Flutter-Internal` checkout beside `social-plus-docs`.
+  - **Degradation, recorded:** when the `.abi.json`, the Flutter checkout, or the `dart` toolchain is unreachable at import time, the platform falls back to the previous names-only surface-export extraction and the manifest records a `degradedReason` — grounding never exceeds what the reachable source proves, and the snapshot gates refuse a degraded re-import of the committed names-and-types artifacts. npm tarball 495.2 kB → 503.9 kB (regenerated typed snapshots + the Dart helper).
+
+### Verified (typed iOS/Flutter model facts)
+- `test:sdk-surface` locks the new grounding with real extracted fields: iOS `AmityComment.commentId` as required `Swift.String` and `parentId` as optional `Swift.String?` from the arm64 abi.json (plus all-fields-typed and no-source-locations invariants), Flutter `AmityComment.commentId` as nullable `String?` property anchored to `lib/src/domain/model/amity_comment.dart` and `AmityUser.isFlaggedByMe` as a non-nullable `bool` getter.
+- `test:sdk-facts` serves the typed schemas end to end (`AmityPost.postId` → `Swift.String` on iOS; source-anchored `AmityComment` on Flutter) with the new extractor ids recorded.
+- The schemas self-test now expects names-and-types on every platform and proves the extended `sourceKind` enum bites (doctored unknown sourceKind fails validation).
+- Block Factory seam unchanged by design: contracts are still TypeScript-provenance only, so `validate:sdk-facts` / `validate:adapters` pass untouched; the typed iOS/Flutter facts are ready for future native-platform `sdkProvenance`.
+
+### Verified
+- **Harness E2E platform matrix completed (`test:harness-e2e`):** the deterministic lane-1 journey now runs for **flutter** and **ios** alongside typescript and android — each with the complete journey, no partial credit (HARNESS_E2E.md). Per-platform discoveries baked into the gate: flutter/ios block on `feed_scope`/`feed_target`/`target_screen_or_route` only; `flutter-happy-path` *is* the add-feed gap state (zero-rule clean, no pagination affordance), so its known-good implementation is a structural Dart pagination helper (naming `AmityCollection` would trip the flutter `feed.ui-states-present` sensor); the ios pre-implementation state removes `AppTheme.swift` together with `FeedViewController.swift` because the feed view is the theme's only consumer (`ios.design.reuse-detected-tokens` would otherwise mask the exit-5 gap); the exit-2 injection reuses the rule-coverage-proven `flutter-rule-missing-guards` / `ios-rule-missing-guards` files, which pair the attestation-disallowed `<platform>.secret.inline-api-key` driver with attestation-level findings in one file.
+- **Exit-4 (`contract-drift`) stage:** every platform journey now tampers the recorded `rule_digest` of its feed-target rule in `sp-vise/compliance.json` and asserts `vise check --ci` exits **4** with status `contract-drift`, naming the drifted rule (`stale`, "Rule digest changed since vise init"); restoring the contract bytes restores green. Lane 1 now asserts all documented exit codes 0–7.
+- **Environment-aware iOS sensors stage:** the guarded xcodebuild sensor is asserted in *both* environments on every machine via a controlled `PATH` (stub toolchain → integrity probe + guarded build detected; empty `PATH` → the single skipped-with-reason precondition), so `test:harness-e2e` passes identically on darwin-with-Xcode and ubuntu CI without it.
+
+### Fixed
+- **Three confirmed TypeScript false negatives closed (resolver/extractor precision; behavior-parity — no rule id/severity/semantics change).** All three were surfaced by the FN-discovery lane above and verified with single-hop/un-cast controls: (1) `secret.inline-api-key` now resolves a pure-passthrough template (`` `${X}` `` ≡ `X`) — a committed production key re-wrapped through a template no longer ships undetected; (2) `feed.target.literal` now does bounded multi-hop identifier resolution (depth cap + cycle guard) so a const aliased through another const still resolves — and the shared resolver means **Kotlin/Swift re-bind chains benefit too**; (3) a new `unwrapExpression` peels `as`/`satisfies`/parenthesized/non-null wrappers before object-property extraction, so a hardcoded target inside `createPost({…} as any)` is caught (high-frequency, since agents emit `as any` constantly). Each broadening is guarded against false positives by a dedicated dynamic-clean canary (member-access / parameter / `process.env`-sourced values must stay clean), and `happy-path-clean` (the 5-platform FP canary) stays at zero findings.
+
+### Added (sidecar compatibility + hermetic docs)
+- **`test:sidecar-compat` — the backward-read gate (the semver promise 1.0 makes).** A frozen corpus of authentic `sp-vise/` sidecars generated by the real published `0.14.26` / `0.14.27` / `0.14.28` (`npx … vise init/sync/attest`, provenance recorded per version — not hand-authored) is replayed by the current build, asserting tolerant reads (no crash/parse-failure, coherent status, older `vise_version`/`foundry_version` tolerated, no unknown old-contract rule) and exercising attestation grandfathering live for the first time against a real v1-era host-agent attestation (`compatible_with` honored; `deprecated_versions` honored and flagged for re-attestation; empty `compatible_with` softens to `attestation-needed`, never a hard fail). Boundary: this covers backward reads (old sidecar, new build — the direction 1.0 promises), not forward compatibility.
+- **Hermetic docs CI mode (`VISE_DOCS_OFFLINE=1`).** Doc lookups can serve a committed `docs-cache/` corpus instead of fetching `learn.social.plus`; CI runs hermetic by default, killing the network-flake class. `test:docs-offline` proves zero network dependency (sinkhole host + 1 ms timeout, with an empty-corpus negative control that fails loudly rather than silently hitting the network); the live-fetch path is preserved off the critical path as `test:docs-live`.
+
 ## 0.14.28 — 2026-06-10
 
+> **Note (reconciled at 1.0.0):** the published npm `0.14.28` tarball shipped **block-aware completeness** (and the schemas-seam refactor). The platform-hardening (Swift tree-sitter AST, the guarded iOS build sensor) and field-level model facts described below were committed after that publish and first reached npm in **1.0.0** — they are documented here because that is where the work was authored; the version they shipped in is 1.0.0.
+
+
+
 **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