@tileflow/dev 0.1.0-alpha.37 → 0.1.0-alpha.39

package/docs/native-artifacts.md

@@ -1,287 +0,0 @@
-# Prepare native map artifacts
-
-Use the existing artifact pipeline with `renderer: 'native'` to prepare the `native-v1` static
-profile. The same config loader, inheritance resolver, semantic compiler, icon composition and
-font pipeline are used. There is no separate native map language.
-
-Install the packages and create a trusted `tileflow.config.ts` as described in the
-[package README](../README.md). The source version containing this option must be installed;
-a source branch or a successful build does not establish npm availability.
-
-## Prepare in memory
-
-<!-- docs:check -->
-
-```ts
-import {createTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
-
-const artifacts = await createTileflowBuildArtifacts({
-  config: 'tileflow.config.ts',
-  renderer: 'native',
-});
-
-try {
-  console.log(artifacts.manifest);
-  console.log(artifacts.nativeBuild);
-} finally {
-  await artifacts.dispose?.();
-}
-```
-
-The pipeline checks every concrete theme. A rejected theme fails the complete generation before
-production output is written. Native preparation applies the versioned transformations below;
-other unsupported layers, fonts or protocols are not silently removed.
-Local PMTiles are rejected before creating archive snapshots. URL checks do not fetch remote
-TileJSON, glyphs or tiles and do not prove their content or availability.
-
-Font preparation verifies the same licensed source bytes as web preparation, then maps exact full
-names into Native's `font-faces` root property. It does not retain browser `tileflow:fontFaces`
-metadata or claim a system font is equivalent. Sprites keep the original independently generated
-1x and 2x bytes; the native check verifies their pair, dimensions, IDs and existing size limits.
-
-## Versioned native lowering
-
-Selecting `renderer: 'native'` applies `native-lowering-v1` after shared semantic compilation and
-before final native validation. It never edits the authored map, the official map definitions or
-the shared compiler. Web output is not lowered.
-
-A browser `sky` is removed, because Native draws no sky, and the entry records `sky: 'removed'`.
-A fixed `projection: {type: 'globe'}` is explicitly normalized to Native's implicit Mercator. This
-is a renderer-specific projection change, not equivalent globe rendering. An explicit fixed
-Mercator declaration is also omitted. Adaptive/expression projections and unknown projection
-options remain errors. Every style receipt states which normalization, if any, occurred.
-
-For line layers, finite `line-cap` and `line-dasharray` decisions become contiguous physical layers
-with constant values. Supported trees use constant leaves, `literal`, first-match `case`, disjoint
-`match` labels and `step`. Predicates may combine boolean operations, scalar equality, membership,
-`has`, geometry type and typed numeric comparisons/steps. Unchecked feature values are restricted
-to vector sources, whose properties are scalar. Numeric coercion requires an explicit finite
-fallback. Arbitrary feature-valued leaves, continuous interpolation, feature state, unsupported
-operators and any unprovable decision fail with the original property pointer.
-
-The partition preserves first-match priority. Each feature accepted by the original filter is
-accepted by exactly one active replacement with the same cap and dash values; all other features
-remain excluded. Existing legacy filters are converted with the pinned Style Spec converter before
-intersection. Source, source-layer, metadata and other layout/paint values are preserved. Existing
-`minzoom`/`maxzoom` are intersected with the decision intervals. Both target properties use integer
-camera-zoom evaluation, so a step at 8.5 changes its value at zoom 9, while an original fractional
-layer visibility bound remains fractional. New branch filters contain no camera-zoom expression.
-
-Grouped outcomes use compact boolean decision trees rather than repeated lists of every earlier
-arm's negated guard. Multi-arm cases remain flat to avoid trading size for excessive depth.
-Identical outcomes and adjacent identical intervals are coalesced. IDs derive from the original
-layer ID, the lowering version and deterministic branch order, with collision checks against the
-whole input style. The original layer's replacements stay together; surrounding layers are not
-reordered. Existing sort-key expressions are retained, not simplified or replaced.
-
-Replacements shift the physical index of every later layer, so lowering rebinds the style's layer
-references from the recorded spans. Each `tileflow:interaction-manifest` POI `priority` becomes its
-layer's final index. An overlay placement anchor naming an expanded layer moves to that layer's first
-replacement, because anchors mark insertion-before boundaries. Metadata that the spans cannot prove,
-such as a POI priority that differs from its compiled layer index, a POI entry whose source does not
-match its layer or an anchor naming a missing layer, fails with `NATIVE_UNSUPPORTED_STYLE` at the
-style's `/metadata` pointer rather than being guessed. Local builds, watched sessions and native
-preview share this step with Hosted publication.
-
-MapLibre Native has no symbol overlap modes and reads only `icon-allow-overlap` and
-`text-allow-overlap`. Lowering replaces each constant `icon-overlap` or `text-overlap` value with
-the matching `*-allow-overlap`: `false` for `never` and `true` for `always` and `cooperative`. A
-cooperative symbol therefore no longer gives way to symbols placed with `never` and can cover labels
-it avoids on the web. The layer keeps its ID and position, so the build record lists it under
-`symbolOverlap` rather than as a layer span. An overlap mode given as an expression fails with its
-property pointer.
-
-Work is bounded per property by depth 16, 512 decision visits, 64 decision paths, 16 distinct
-outcomes and 64 dash elements; the product is limited to 32 physical layers and 32 zoom intervals
-per logical layer. Raw compiler input must fit 160,000 JSON nodes before any lowering. Its expanded
-native representation has a separate fixed 540,000-node ceiling, checked after lowering, after
-font preparation and after generation URL retargeting. Both stages retain 4,096 layers, depth 64
-and 8 MiB. No caller option raises either budget and no rejected input is retried under the output
-allowance. A failure occurs before output writes and leaves the previous valid generation intact.
-
-This is one shared authored map, not a second mobile catalog: the native-v1 representation adapts
-only finite `line-cap`/`line-dasharray` decisions and constant symbol overlap modes, together with
-its explicit fixed-projection policy. Unsupported advanced expressions or other properties fail
-with their native diagnostic and JSON Pointer; their web behavior is unchanged. The raw and
-prepared validators share their semantic checks and bounded traversal. See the
-[Core budget contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md#input-and-prepared-style-budgets)
-for the measured Streets sizes and the approximately 5.2% output margin.
-
-The equivalence checks cover per-feature selection, cap/dash values and zoom ranges, **not draw
-order across features**. Copying `line-sort-key` preserves ordering only inside each physical
-layer. If a feature with sort key 1 enters the first branch and a feature with sort key 0 enters
-the second, the physical layers draw them as 1 then 0 instead of 0 then 1. Both features can satisfy
-mutually exclusive filters yet have overlapping geometry. The resulting composition can differ,
-not merely its antialiasing. Even without a sort key, partitioning can change source feature order.
-
-The native-lowering-v1 policy permits these bounded partitions without promising identical global
-feature order. Applications requiring exact overlapping-feature order must not treat such an
-artifact as order-equivalent to its web style. Automated checks establish feature selection,
-cap/dash values, zoom ranges, determinism and resource bounds, not pixel equivalence.
-
-A small directed iOS/Android rendering check of cap/dash/overlap is required for each accepted
-candidate using the recipe below. Full visual qualification belongs to the general mobile release
-gate; it is not claimed by artifact preparation. Browser capture cannot replace either native
-check, and a few visual samples cannot prove preservation of arbitrary feature order.
-
-## Write a separate output
-
-<!-- docs:check -->
-
-```ts
-import {writeTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
-
-await writeTileflowBuildArtifacts({
-  config: 'tileflow.config.ts',
-  renderer: 'native',
-  outDir: 'public/tileflow',
-});
-```
-
-This writes `public/tileflow/native/manifest.json`, `build-manifest.json`, `native-build.json` and
-the complete style/asset generation beneath `public/tileflow/native`. The writer adds `native` once
-beneath `outDir`; pass the output parent, not an already renderer-qualified directory. The native
-subdirectory owns a separate inventory. A web build at the parent neither replaces its manifest nor
-collects the native generation, and vice versa.
-
-The runtime manifest remains strict version 1 with the same map/theme shape. No renderer/profile
-field is added to it. Native font declarations live in the native styles, not a web font loader.
-`native-build.json` is a separate strict build record that identifies the renderer, profile, selected
-engines, `validation: 'static-artifacts'` and the canonical `build-manifest.json` SHA-256. Its
-schema version is 2 and its `preparationVersion` is `native-lowering-v1`.
-
-The `transformations` array is sorted uniquely by map/theme. Each entry records input and lowered
-style SHA-256 values, input/output layer counts, projection normalization and, when present, sky
-removal. `layers` lists the
-input ordinal, output start/count and affected properties of each partitioned line layer;
-`symbolOverlap` lists the input ordinal and replaced properties of each symbol layer whose overlap
-modes became `*-allow-overlap` values. Ordinals refer to the complete style layer arrays, including
-unchanged layers. These spans make the deterministic
-physical IDs traceable without duplicating layer definitions in the receipt. The input hash binds shared
-compiler output; the lowered hash includes the rebound layer references and precedes native font
-preparation and generation URL retargeting.
-The build-manifest hash separately binds the final prepared styles and assets. All styles receive
-an entry, including styles for which no lowering was needed. Schema v1 build records do not imply
-this preparation policy and are not parsed as v2.
-
-The existing logical map revision remains based on resolved cartography and source asset identity.
-Representation changes, such as native font mapping, change the style hash rather than inventing
-a second logical map. Transport credentials and device state never enter these artifacts.
-
-File names in an in-memory plan remain relative to the renderer output root. Relative style/font
-URLs remain relative to their owning documents. An explicit absolute or host-relative
-`styleBaseUrl`/`assetBaseUrl`, such as `/tileflow`, receives the `/native` suffix. The pipeline uses
-an inert `.invalid` document base only to check relative URL syntax; it does not publish that base
-or infer the application's real delivery origin.
-
-A served local preview can use an absolute HTTP base, such as `http://127.0.0.1:3333`, only when it
-also passes that exact origin as `developmentOrigin`. Native checks then accept HTTP resource URLs,
-such as the sprite and fonts, with that scheme, host and port. Every other origin still requires
-HTTPS, and browser protocols remain rejected. The option is never inferred from a base URL.
-Web preparation, `target: 'production'` and `writeTileflowBuildArtifacts()` reject it with
-`NATIVE_RENDERER_UNSUPPORTED` at `/developmentOrigin`, so written artifacts never depend on it.
-
-Omitting `renderer`, or specifying `renderer: 'web'`, preserves the existing web artifact bytes and
-output layout. The native record is absent from web plans.
-
-## Retain the last valid generation
-
-`createTileflowArtifactSession({renderer: 'native', watch: true})` uses the existing session lifecycle.
-An incompatible edit publishes an `invalid` state with native diagnostic context. It retains the
-previous valid artifacts but does not publish them again as a new successful generation. Acquiring,
-releasing and disposing a generation follow the existing [artifact lifecycle](artifact-lifecycle.md).
-
-This is artifact watching, not a native preview server. Do not pass these artifacts to browser
-preview/capture as evidence of a native render. Native inspection sidecars, React Native components,
-Hermes execution, iOS/Android qualification, Hosted authorization and deployment are not supplied.
-
-## Audit lowering size and feature order
-
-From the SDK source root after installing and building the pinned workspace:
-
-```sh
-pnpm exec tsx scripts/native-lowering-audit.ts > native-lowering-audit.json
-```
-
-This diagnostic report compiles the unchanged full Streets family through the web preparation
-path, then measures the native representation for **all twelve** themes before applying output
-budget assertions. It writes no native artifact generation and is not a compatibility verdict.
-Each theme includes layer counts, visited JSON nodes, UTF-8 bytes and maximum depth before/after;
-every transformed layer is listed with its ID, physical span, branch count and zoom intervals,
-sort-key expression and paint indicators. Simultaneously active branches are marked as an
-unproven feature-order boundary, not as a claim that their geometry is disjoint.
-
-Subtree accounts separate copied unchanged layer payload from generated filters and input
-cap/dash decisions. They identify whether predicate expansion or repetition of other properties
-dominates; they are not an additive byte decomposition. The counters include array keys, matching
-the profile's existing node convention. Retain the report with the checkout SHA. An over-budget
-result must not be treated as a successful native build or fixed by dropping layers or weakening
-validation. The test suite prints the full theme size summary even when a budget assertion fails.
-
-## Prepare Streets for a directed native check
-
-From a source checkout, install and build the pinned workspace first. The test-only
-`test/fixtures/native-streets.config.ts` exports the unchanged official Streets definition. It
-exists to make artifact generation repeatable without a second compiler, custom map or native
-harness. From the SDK root:
-
-```sh
-pnpm --filter @tileflow/dev exec node ../cli/dist/index.js validate \
-  --config test/fixtures/native-streets.config.ts --renderer native --target local --json
-pnpm --filter @tileflow/dev exec node ../cli/dist/index.js build \
-  --config test/fixtures/native-streets.config.ts --renderer native --target local \
-  --out output/native-streets --json
-pnpm exec tsx scripts/native-lowering-audit.ts > /tmp/native-lowering-audit.json
-```
-
-The output root is `packages/dev/output/native-streets/native`. It contains
-`styles/streets/dark.json`, `styles/streets/light.json`, their shared sprite/font assets, a version-1
-`manifest.json` and the version-2 `native-build.json` receipt. Keep the complete directory together.
-The manifest points to the content-addressed generation; use those URLs for an actual render.
-Do not copy only the two style files and leave their relative assets behind. Record the checkout
-SHA, both prepared style hashes, engine versions and the resource origin used for the check.
-The fixture and output are source-checkout tools, not a published mobile component or a baseline.
-
-Use an existing native test application with the pinned engines and a reachable artifact origin;
-artifact generation starts no server and requests no deployment. Load the same generated manifest
-family independently on iOS and Android. Resolve its style URL against the manifest URL, then each
-relative style resource against that style's URL before passing the style to MapLibre Native. A raw
-style URL does not transfer this ownership to the renderer. The directed artifact check may use a
-test-owned resolver, but that does not qualify a future runtime resolver. A useful starting viewport
-is a dense road/rail junction with visible paths and bridges; select one where the loaded vector data
-actually contains features for the transformed layers listed in
-`/tmp/native-lowering-audit.json`. Use the audit's exact physical IDs, source layers, branch counts
-and zoom intervals rather than assuming that a map location exercises every branch.
-
-Check all themes at the same center, viewport, pitch 0 and bearing 0. Exercise at least one cap
-partition, one dashed/solid partition and an overlap between simultaneously active branches. Pan
-slightly and inspect just below/at/above the relevant audit zoom cuts (for example 15.99/16/16.01
-when a selected interval changes at 16). Check that caps and dash patterns are visible, layers do
-not disappear or double-select a feature, theme replacement preserves the scene, and no resource
-or style errors are reported. Inspect overlapping strokes for the documented composition
-trade-off, not for equality with web drawing order. Keep brief per-platform observations and
-explicitly distinguish an unexercised branch from a passed one.
-
-This check has not been run by the artifact tests. It neither establishes full iOS/Android visual
-qualification nor creates a screenshot baseline. Renderers, native view lifecycle, network
-transport and mobile distribution remain outside these build tools.
-
-## Reproduce the official-map report
-
-From an SDK source checkout after installing and building its pinned workspace:
-
-```sh
-pnpm exec tsx scripts/native-catalog-report.ts > native-catalog-report.json
-```
-
-The report evaluates all ten official maps and each of their themes through the shared pipeline.
-Rows contain either a static-compatible style hash or exact incompatibility diagnostics, sorted by
-map/theme with no timestamp or local path. Each row checks an individual theme; it is not a revision
-receipt for a rewritten single-theme map. Unexpected compilation/tool failures stop report generation
-rather than being relabeled as known incompatibilities. Retain the output together with the checkout
-SHA and lockfile used to produce it. The test suite compares two independent evaluations and requires
-Streets to pass. No unchecked catalog-wide compatibility assertion is implied by the presence of
-this command, and this report is not a device-qualification result.
-
-See the [Core profile contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md)
-for the version intersection, diagnostic codes and unsupported representations.

package/docs/native-icons.md

@@ -1,129 +0,0 @@
-# Author recolorable and adaptable icons
-
-Use SDF for a monochrome silhouette whose fill and halo vary by map. Keep multicolor artwork as
-fixed-color RGBA. Ordinary filenames and icon IDs stay unchanged.
-
-In an icon directory already selected by your map, place `tileflow.icons.json` beside `health.svg`:
-
-```json
-{
-  "schemaVersion": 1,
-  "icons": {
-    "health": {
-      "representation": "sdf",
-      "defaults": {"color": "#c43d35", "haloColor": "#ffffff", "haloWidth": 1, "haloBlur": 0}
-    }
-  }
-}
-```
-
-Only explicitly declared SDF assets are converted. Omitted entries, or `representation: "rgba"`,
-preserve fixed-color rendering. SDF uses the source alpha silhouette; source RGB does not define its
-default color. `defaults.color` is required. Omitted halo fields become transparent, zero width and
-zero blur. Unknown IDs, duplicate JSON keys, unknown fields and invalid colors fail preparation.
-
-The generated cell remains 24 × 24 logical pixels at both densities. Within that cell, the source
-silhouette needs six fully transparent pixels on every side. Tileflow rejects edge-touching,
-empty, or insufficiently defined silhouettes instead of adding padding or shrinking artwork.
-Author opaque silhouettes with antialiased edges; gradients and translucent artwork should remain
-RGBA. Thin shapes without a resolved interior fail verification. Generation rasterizes 1x and 2x
-independently and encodes distance in white-RGB alpha. SDF is for symbol icons, not patterns.
-
-For existing artwork, expand the source canvas explicitly before declaring SDF. A drawing bounded
-by `viewBox="0 0 15 15"` fits the profile when its outer SVG uses `width="24" height="24"`
-and `viewBox="-7.5 -7.5 30 30"`: the drawing occupies at most the central 12px. Review fine details
-at the intended map size; use `icon.size` to choose the displayed size. Keep the original source for
-fixed-color use. A transparent margin does not make an excessively thin silhouette suitable.
-
-## Keep each symbol layer homogeneous
-
-One package may contain RGBA and SDF icons. Every icon selectable by one symbol layer, including
-fallbacks, must use the same representation. Tileflow checks the effective composition after all
-local overrides. It does not split layers or alter collision priority, coupled labels or IDs.
-
-An unbounded selection such as a POI icon read from feature data can select any effective icon ID.
-It therefore requires a homogeneous inventory. To use a mixed package, select one fixed icon or
-an explicit `expr.match`/`expr.case` expression whose possible outputs and fallback are homogeneous.
-Sampling the current feature data does not prove this condition.
-
-`tileflow validate`, `tileflow preview`, `tileflow build`, framework preparation and Capture use the
-same check. `TF_ICON_REPRESENTATION_MIXED` identifies the layer and image-selection path. Replace
-the conflicting override, align all selectable representations, or bound the selection explicitly.
-Compiled SDF admission rejects legacy token templates and function objects with
-`TF_ICON_SELECTION_UNPROVEN`; rebuild using expression-based image selection.
-Development reports an invalid generation and retains its last valid artifact until recovery.
-
-## Style each map independently
-
-Use the existing `styles.<category>.icon` fields: `color`, `haloColor`, `haloWidth`, and `haloBlur`.
-Theme tokens, explicit `fixed(...)` values and supported data, zoom and feature-state expressions
-compile to native MapLibre paint. Feature state is supported in paint, not image selection.
-Keep halo width within 0–2 logical pixels and blur within 0–1. Dynamic halo expressions must prove
-these bounds; use `expr.min`/`expr.max` around unconstrained feature values. Otherwise compilation
-reports `TF_ICON_HALO_BOUNDS`.
-
-An omitted paint property uses that selected icon's declared default, including missing-ID
-fallbacks. An override replaces only its property. It does not edit the shared revision or another
-map. Image IDs remain stable; recoloring does not generate image variants. Existing size, opacity,
-rotation and anchor controls retain their native semantics.
-
-## Fit a background around text
-
-Declare optional `layout` beside the representation. It applies to RGBA and SDF independently.
-For a 24px background whose central region can stretch, use this sidecar entry:
-
-```json
-{
-  "schemaVersion": 1,
-  "icons": {
-    "price": {
-      "representation": "rgba",
-      "layout": {
-        "stretchX": [[9, 15]],
-        "stretchY": [[9, 15]],
-        "content": [7, 7, 17, 17]
-      }
-    }
-  }
-}
-```
-
-Coordinates use the generated logical cell, not the original SVG viewBox. Each stretch interval
-is `[start, end]`; `content` is `[left, top, right, bottom]`. Use positive, ordered, non-overlapping
-integer ranges inside the cell. Each configured axis must overlap its content area. Put corners,
-borders and pointers outside stretch regions. Tileflow scales metadata for the 2x index, verifies
-both densities and rejects layout on patterns. SDF backgrounds still need the six-pixel guard.
-
-Enable the existing map `icon.textFit` control (`width`, `height` or `both`) and set
-`icon.textFitPadding` in top/right/bottom/left order. For centered price labels, also set
-`text.anchor: 'center'` and `text.offset: [0, 0]`; the POI defaults place labels beside icons.
-This style fragment belongs inside the selected category's `styles` entry:
-
-```ts
-{
-  icon: {image: fixed('price', {reason: 'Price background'}), textFit: 'both', textFitPadding: [4, 6, 4, 6]},
-  text: {anchor: 'center', offset: [0, 0]},
-}
-```
-
-Import `fixed` from `@tileflow/core`. The same layer retains label coupling, collision priority and
-interaction identity. Text fitting does not happen merely because an asset has metadata. Explicit
-new local artwork replaces the shared asset's layout; omitted metadata never inherits stale bounds.
-
-## Inspect and distribute the result
-
-Packages with SDF appearance or layout use `tileflow-icon-package-v2`; composition receipts use
-`tileflow-icon-composition-v2` when an effective winner has either capability. Paired sprite JSON entries contain
-`sdf: true` and verified `tileflow` appearance metadata. Defaults and layout participate in revision identity
-and diffs even when pixel hashes match. Metadata-free RGBA packages and receipts keep their v1 identity.
-Old readers reject v2; upgrade every producing and consuming package together.
-
-`tileflow icons list --json` includes `appearances` and `layouts` for effective icons. Diff reports show default appearance;
-downloadable PNGs remain the original distance fields. Bare MapLibre consumes the standard sprite
-and compiled paint without a recoloring adapter. Capture uses the same prepared assets.
-
-Hosted admission, Dashboard and Static Maps require coordinated Platform adoption. Additional
-Static Maps symbols use asset defaults and retain adjacent icon/label layout; base-map symbols use
-compiled map paint and text fitting. Device support
-requires separate Native qualification. This contract does not provide independently parameterized
-multicolor SVG, COLRv1, `textFitWidth`/`textFitHeight` metadata or an icon editor.

package/docs/structured-config-inspection-and-diagnostics.md

@@ -1,39 +0,0 @@
-# Structured config inspection and diagnostics
-
-Start with the [@tileflow/dev guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/README.md) for installation and a complete first example.
-
-Custom Node tooling can use the same deterministic documents as `tileflow validate --json` and
-`tileflow inspect --json`:
-
-```ts
-import {inspectTileflowConfig} from '@tileflow/dev/inspect';
-import {
-  createTileflowCommandFailureDocument,
-  serializeTileflowCommandDocument,
-} from '@tileflow/dev/validation';
-
-try {
-  const inspection = await inspectTileflowConfig({config: 'tileflow.config.ts'});
-  process.stdout.write(serializeTileflowCommandDocument(inspection));
-} catch (error) {
-  const failure = createTileflowCommandFailureDocument('inspect', error, process.cwd(), {
-    code: 'INSPECTION_FAILED',
-    phase: 'config-inspection',
-  });
-  process.stderr.write(serializeTileflowCommandDocument(failure));
-}
-```
-
-The inspection resolves one config load into sorted maps, root-to-leaf lineage, declared paths, and
-leaf-level merge provenance. Its `themeContract` exposes the default/system mapping, shared token
-schema, concrete resolved token values, typography and lighting, differences from the default, and
-stable `THEME_IMPLICIT_FIXED` diagnostics across modules, render stacks, and terrain. Each
-diagnostic carries a semantic scope and, for module values, its owner, plus machine-readable
-severity and remediation. Colors, fonts, and images are followed through
-expression outputs; numeric diagnostics intentionally cover only direct visual scalars, excluding
-expression operands, zoom stops, tuples, placement, priority, and other structural numbers.
-Agents can therefore edit semantic roles without
-reverse-engineering compiler layers or parsing prose. It never returns `inputFiles`, absolute filesystem paths, credentials,
-URL queries, data URLs, or recognized secret formats. Structured summaries and diagnostics use the
-same required schema-version-1 fields and bounded safe suggestions so consumers do not need to
-parse human prose.