Add deterministic, native-verified schema examples (S3)

AGENTS.md

@@ -4,8 +4,10 @@ Swift-JSON requires Swift tools/compiler 6.4+, Swift language mode 6 and
 macOS/SDK 27+. Read README.md, CONTRIBUTING.md and the relevant contracts in
 Documentation/Architecture before changing behavior.
 
-- Keep eight public products: JSON, JSONSchema, JSONStreaming, JSONPatch, JSONHTML,
-  JSONBridges, JSONNavigation and the swift-json executable. JSONFilterRuntime and JSONCLIEngine are package-private.
+- Keep nine public products: JSON, JSONSchema, JSONSchemaExamples, JSONStreaming,
+  JSONPatch, JSONHTML, JSONBridges, JSONNavigation and the swift-json executable.
+  JSONSchemaExamples is opt-in and depends on JSON and JSONSchema only.
+  JSONFilterRuntime and JSONCLIEngine are package-private.
   JSONHTML and opt-in JSONBridges depend on JSON only; core never re-exports the bridges.
   The approved CLI and E2 additions preserve historical product contracts.
   JSONNavigation is an opt-in product candidate depending on JSON only; merge/release remain human-gated.

Documentation/Architecture/API.md

@@ -1,7 +1,7 @@
 # Public API contract
 
 This document describes the implemented public interface. Native compiler symbol
-graphs supply the complete declarations in the seven DocC catalogs. Examples
+graphs supply the complete declarations in the eight DocC catalogs. Examples
 in the [README](../../README.md) are compiled and executed by the public consumer.
 
 ## Products and ownership
@@ -18,7 +18,8 @@ in the [README](../../README.md) are compiled and executed by the public consume
 | JSONHTML | JSONHTMLRenderer, JSONHTMLRenderingOptions, JSONHTMLLimits, JSONHTMLRenderReport, JSONHTMLAnnotation, JSONExportDocument, JSONExportOptions, JSONExportReport | Structured forms/cards and bounded native previews, exact HTML, native Apple transfer, immutable prepared JSON/text/Markdown/static HTML/opt-in styled RTF and cumulative budgets |
 
 JSON imports no siblings. JSONSchema depends on JSON and package-private
-JSONRegexRuntime. Streaming, Patch, HTML and Bridges depend on JSON. There are eight candidate public products: seven libraries and the swift-json executable,
+JSONRegexRuntime. Streaming, Patch, HTML, Bridges and Navigation depend on JSON.
+JSONSchemaExamples depends only on JSON and JSONSchema. There are nine public products: eight libraries and the swift-json executable,
 and no external root-package dependencies. No HTTP, MCP or documentation-tool dependency is introduced. JSONHTML conditionally
 uses Apple SDK frameworks for explicit native transfer/PDF preparation; the portable
 value, schema, Patch and streaming contracts do not acquire UI semantics.
@@ -233,13 +234,53 @@ is neither native validation of an instance nor a service-acceptance guarantee.
 and all phase accounting are specified in [Providers](Release1.4/Providers.md) and the frozen
 [profile table](Release1.4/ProviderProfiles.json). No new product, SDK client or Apple type is added.
 
-## Best-effort diagnostics and versioned CLI identity
-
-With best-effort schema output, an optional diagnostic-byte refusal returns ordinary
-invalidity with `diagnosticsComplete == false`; it does not poison the active work
-ledger. Work, retention, annotation exhaustion and cancellation remain operational
-errors. Strict diagnostic output still throws on the same byte bound.
-
+## Schema examples (1.6 G4 development)
+
+The optional JSONSchemaExamples product prepares an immutable document/explicit
+registry/compiled-plan snapshot. `JSONSchemaExampleGenerator(document:registry:options:)`
+and `generate(seed:profile:)` offer exact declared candidates and compiler-qualified
+static reference targets. Every success contains the actual native valid verdict
+for the original root. Minimal scans stable exact declarations; demonstration
+uses metered SplitMix64 rejection sampling and circular scans. An immutable exact
+`JSONSchemaExampleCorpus` supplies candidates for true/empty schemas. Returned
+objects/numbers use scalar order and normalized exact spelling. Conservative
+typed construction covers the qualified foundational subset. G4 adds conservative
+contains minima and a small anchored ASCII pattern-proposal grammar. Native
+validation retains conditional, dependency, regex and evaluated-location semantics.
+General constraint
+solving, arbitrary regex inversion and dynamic construction remain incomplete.
+
+`JSONSchemaExampleFailure` distinguishes unsupported construction, searchExhausted,
+reviewed trivial provenUnsatisfiable and invalidConfiguration. Core operational
+failures and cancellation propagate without retries. Preparation accounting is
+separate from the shared per-generation ledger, which includes all completed
+invalid checks. Discarded validation ownership is released without refunding work. Logical
+retention is not process RSS.
+The result binds the versioned snapshot, ordered corpus, all generation/compiler/
+evaluator caps and flags, and complete abstract trace with SHA-256 digests. Trace
+bytes share diagnosticBytes with native diagnostics; exhaustion never truncates a
+success. See [the G3 constructive subset](Release1.6/G3Construction.md),
+[the G4 advanced boundary](Release1.6/G4Construction.md),
+[the capability ledger](Release1.6/Capabilities.json), [the G2 byte transports](Release1.6/G2Determinism.md), the historical
+[G1 API decision](Release1.6/G1API.md), and the
+[compiled public consumer](../../Examples/SchemaExamplesConsumer/README.md).
+
+## Optional verified schema examples (1.6 development)
+
+JSONSchemaExamples adds an immutable prepared generator over admitted documents and
+explicit offline registries. Every returned value has a completed native root verdict,
+with exact JSON semantics, cumulative generation statistics and versioned provenance.
+It does not alter JSON/JSONSchema APIs, policies, products or dependencies.
+
+See the [current public declarations and failures](Release1.6/API.md),
+[supported construction subset](../../Sources/JSONSchemaExamples/Documentation.docc/TypedConstruction.md),
+[resource scope](Release1.6/SchemaExamplesLimits.md) and
+[compiled public consumer](../../Examples/SchemaExamplesConsumer/README.md).
+Preparation and generation use separate finite ledgers. All attempts within a generation
+share one ledger; false verdicts consume work, operational errors/cancellation terminate
+without a candidate or successful report, and search exhaustion is not a proof.
+The [combined-source G8 record](Release1.6/G8Qualification.md) describes qualification,
+review and platform limits. Merge and release approval remain separate.
 The CLI's human version reports the candidate/release source version. JSON metadata
 includes `revisionKind: "source-sha256"` and `revision: "sha256:<hex>"`. This is the
 SHA-256 of the ordered Package.swift plus Sources content manifest, excluding only

Documentation/Architecture/ExtractionManifest.json

@@ -249,6 +249,28 @@
         "Scripts/qualify_schema_providers.py",
         "Tools/CLIQualification/Sources/ProviderConsumer"
       ]
+    },
+    {
+      "repository": "SwiftJSON-SchemaExamples-S3-Codex-Wave-v1.0 briefing packet",
+      "archive_sha256": "f67ec2f5d0bfd223f54a3577f93c03951a7992ecab524910ba44f6bc8621c4a1",
+      "original_path": "Reference/SplitMix64.swift and Reference/SplitMix64Check.swift",
+      "destination": "Sources/JSONSchemaExamples/SchemaExampleDeterminism.swift",
+      "disposition": "SplitMix64 constants, wrapping steps and rejection threshold adapted into invocation-owned noncopyable state with cumulative native metering; standalone shims not used. Sixteen golden draws retained in real-engine tests.",
+      "attribution": "Apache-2.0 SPDX header retained; original Swift-JSON integration code Apache-2.0.",
+      "validation": "Tests/JSONSchemaExamplesTests/DeterminismTests.swift; independent stdlib transport oracle and public consumer",
+      "evidence": "Release1.6 G2 qualification; actual native/safety/docs receipts"
+    },
+    {
+      "repository": "SwiftJSON-SchemaExamples-S3-Codex-Wave-v1.0 briefing packet",
+      "archive_sha256": "f67ec2f5d0bfd223f54a3577f93c03951a7992ecab524910ba44f6bc8621c4a1",
+      "original_path": "Fixtures/cases.json",
+      "original_sha256": "6f2bfd4fdb7c7e206b6570c2156ca8e248831840733b0258aa8cd5938b35649f",
+      "destination": "Tests/Fixtures/SchemaExamples",
+      "disposition": "Original 44-case input retained byte-for-byte alongside the independently reviewed G0 integral-number correction (155 witnesses). G3 selects exactly 24 must-generate IDs plus two sound proofs; 18 G4 cases remain separate. No fixture expected verdict was lowered for the generator.",
+      "amended_sha256": "5b3e6e40e83439a810d0eb7ac412ce158a4e582f36b9d36d6e313c159654ddd3",
+      "attribution": "User-authored packet fixture input; original integration/tests Apache-2.0. Packet source/provenance retained separately.",
+      "validation": "TypedConstructionTests.swift and public G3Acceptance consumer; strict native compiler/evaluator authority",
+      "evidence": "Release1.6/G3 qualification and materialized per-case receipts"
     }
   ],
   "original_implementation_notes": [
@@ -271,7 +293,10 @@
     "1.4 C4 immutable IR/function/pattern metadata, invocation closures/thunks, continuations, scalar string and format helpers, root-provenance paths and transactional mutation are original Apache-2.0 code. No eager upstream evaluator, Foundation regex or approximate arithmetic was copied.",
     "1.4 C5 stream/offline-schema adapters, checked sink handoff, command help and consumers are original Apache-2.0 code. Five NewInputs fixtures are copied byte-for-byte from the maintainer CLI briefing pack 43f8819c57e3d93bc6f7cf561d2d111442e089f2973cb7c62e16e3bd3fd73d0d; these authored data fixtures introduce no runtime dependency. Missing provider helper prerequisites remain blocked rather than adapted or silently rewritten.",
     "1.4 checked schema resource lookup and its missing/quota/cancellation/install regressions are original Apache-2.0 code. Supported app/framework/command layouts retain all nine official resource pins; no unbounded directory scan, fallback engine or external dependency is introduced.",
+    "1.6 S3 G4 contains-minimum proposals and the small anchored ASCII proposal scanner are original Apache-2.0 Swift code. Native compiler-qualified references and complete native regex/schema evaluation remain authoritative; no matcher, resolver, engine source or dependency is adapted. The original/amended S3 fixtures retain their pinned byte identities.",
     "1.5.1 restores 126 original Apache-2.0 test functions and qualification tools from Swift-JSON 1.2.1 (e8b687f822c577311156b13bf1d15c2d5620b84e), with file hashes and stable function identities in Qualification/Release1.5.1/Restoration.json. The diagnostic omission and Git-free provenance repairs are restored original code; current seven-product harness reconciliation and deterministic CLI identity are original contributions. No new upstream adaptation or dependency.",
+    "1.6 S3 G7 seeded grammar, scalar-key permutation tests, public replay consumer and strict cardinality/matrix harness are original Apache-2.0 contributions. The 64-schema authored fixture has SHA-256 cb55604183a6db7df5fa968db283e7abeae794277d2b0cef033b0bdb92e615cb. Independent python-jsonschema 4.26.0 is research qualification only, with exact numeric binding; no Python runtime dependency or copied validator/engine is distributed.",
+    "1.6 S3 G8 materializes the unchanged synthetic corpus per caller access, replacing process-lifetime stored JSON payloads exposed by Linux ASan/LSan. The public process-lifetime consumer and strengthened exact/value-copy test are original Apache-2.0 qualification code; no suppression, runtime fallback, new dependency or corpus/digest change is introduced.",
     "Composition reference-load fixtures, serial descriptor staging, public-only adapter, capacity/terminal tests and strict CI receipt checks are original Apache-2.0 code. Generated JSON graphs introduce no upstream protocol fixtures, engine or dependency. Core public APIs, finite profiles and accounting weights are unchanged."
   ],
   "jsonhtml_export_original_contributions": {

Documentation/Architecture/Release1.6/API.md

@@ -0,0 +1,112 @@
+# JSONSchemaExamples current public contract
+
+This is the current S3 interface through G6, superseding the provisional G1 API
+notes where later accepted increments differ. Historical decisions and receipts
+are preserved. It is an opt-in 1.6 development product; G7/G8 and main repair
+integration remain open. Native compiler symbol graphs and source declarations
+are the API authority. There is no public mutable plan, evaluator, meter or result
+initializer, and no new root-package dependency.
+
+## Prepare, generate and inspect
+
+| API | Actual role and defaults |
+| --- | --- |
+| `JSONSchemaExampleGenerator(document:registry:options:) throws` | Admitted JSONSchemaDocument, explicit registry default `.empty`, options default `.init()`; compile/normalize/hash once under one preparation ledger |
+| `generate(seed:profile:) throws -> JSONSchemaExampleResult` | Seed UInt64 default 0; profile default `.minimal`; independent cumulative invocation; returns only after native valid verdict and complete trace/hash |
+| `document`, `registry`, `options` | Immutable original preparation inputs/policies; no inferred format/default/registry behavior |
+| `preparationStatistics` | Separate compilation-domain counts, including snapshot/corpus/policy work; not part of the generation report |
+| `sourceSnapshotDigest`, `corpusDigest`, `policyDigest` | Lowercase SHA-256 identities of the documented separate transports |
+
+The generator is checked Sendable. Mutable construction frames, PRNG, trace and
+validation state belong to one synchronous call. The compiled root is private and
+retained immutable. Caller document/registry/corpus construction precedes preparation.
+Returned values have normalized exact numbers, scalar-sorted object insertion order
+and preserved array nesting; mathematical/scalar semantics are those of JSON.
+
+## Options and profiles
+
+`JSONSchemaExampleOptions(limits:maximumAttempts:corpus:compilationOptions:validationOptions:)`
+uses balanced generation limits, maximumAttempts **16**, corpus **.synthetic** and
+native JSONSchemaOptions defaults for both compilation and validation. Options are
+values checked when preparing a generator. Changing a caller's options afterward
+does not mutate an existing preparation.
+
+* Generation limits intersect validation limits per metric. All 49 entries remain
+  finite and contribute to policy identity. See [limits](SchemaExamplesLimits.md).
+* Compilation options remain separate, including any format assertion selected at
+  compilation. Validation output, diagnostic policy, annotations and assertion
+  settings are forwarded unchanged. Required vocabulary assertions still apply.
+* `maximumAttempts` must be positive and strictly below UInt64.max. It bounds
+  completed candidate validations, including false verdicts, without promising
+  that every search reaches the limit or finds an existing witness.
+* `.minimal` uses stable declared order and conservative small typed proposals,
+  with no random draws. It is not a global minimization guarantee.
+* `.demonstration` uses seeded SplitMix64 candidate/corpus choices. Some inputs
+  produce the same value for every seed. Every raw rejected draw is charged.
+* `JSONSchemaExampleCorpus(values:)` stores exact ordered caller JSON without
+  admission; preparation checks/normalizes it and rejects an empty corpus. The
+  synthetic ordered values are null, false, 0, "example", [], {}. The read-only
+  `synthetic` property materializes these values per access; caller lifetime owns
+  their storage, before checked preparation. Corpora are hints.
+
+Candidate role order is **const, default, enum, examples** (ASCII keyword order).
+Array order is semantic. Discovery follows qualified alternatives/static edges;
+typed construction then offers bounded variations. Defaults and examples can be
+invalid; nothing is inserted or repaired. Complete original-root validation alone
+establishes success. See [supported subset](../../../Sources/JSONSchemaExamples/Documentation.docc/TypedConstruction.md)
+and [all 59 keyword classifications](Capabilities.json). General satisfiability,
+regex inversion, triggered dependency/key synthesis and constructive dynamic scope
+are incomplete. No boundary profile, AI, online resolver or interop converter is added.
+
+## Result and provenance
+
+JSONSchemaExampleResult exposes immutable `value`, actual native `validation`,
+`seed`, `profile`, `attempts`, `statistics`, `validationOptions` and
+`compilationOptions`, plus these identities:
+
+| Properties | Current identity |
+| --- | --- |
+| generatorVersion | s3-candidates-v4 |
+| schemaDigestAlgorithm / sourceSnapshotDigest | swift-json-schema-snapshot-v1 / source and ordered registry hash |
+| corpusDigestAlgorithm / corpusDigest | swift-json-example-corpus-v1 / admitted ordered corpus hash |
+| policyDigestAlgorithm / policyDigest | swift-json-example-policy-v1 / all three 49-cap profiles, attempt ceiling and policy flags |
+| rngAlgorithm / randomDraws | splitmix64-v1 / every raw draw, including rejection |
+| traceDigestAlgorithm / traceDigest / traceEventCount | swift-json-example-trace-v2 / complete abstract decision hash and event count |
+
+Transports exclude source maps, unavailable original source bytes and caller time.
+They are not RFC8785/JCS. Registry order contributes to source identity. Seed alone
+cannot bind a result; retain implementation commit, versions and all input identities.
+[G2 transports](G2Determinism.md), [G3 trace additions](G3Construction.md) and the
+[G5 accounting correction](G5Resources.md) preserve historical versions separately.
+Statistics snapshot certification and conservative staging ownership, before transfer;
+logical retained bytes/peaks are not heap size or RSS. WorkUnits includes subsystem work.
+
+## Failures and semantic authority
+
+| Failure | Meaning |
+| --- | --- |
+| unsupportedFeature(candidateConstruction / dynamicReference / cyclicReference) | Current constructor lacks a proposal or reached unsupported scope/active cycle; no validity conclusion |
+| searchExhausted(attempts:) | All offered candidates rejected or finite ceiling reached; not an unsatisfiability proof |
+| provenUnsatisfiable(falseSchema / notTrue) | Only reviewed trivial root false or active root `not` of true/empty schema |
+| invalidConfiguration(attemptLimit / emptyCorpus) | Invalid generator configuration before preparation/search |
+| Native compilation/evaluation/resource error or CancellationError | Operational failure; terminal, never ordinary false validation or accepted incompleteness |
+
+No failed call publishes a value, complete trace or successful work report. A caught
+operational error cannot resume its internal invocation; a later public call is an
+independent operation. Immutable preparation remains reusable. Public consumers must
+not invent failed-work statistics when composing separate calls.
+
+## Compiled examples and integration
+
+[README examples](../../../README.md#generate-verified-schema-examples-16-development)
+compile in the seven-library consumer. Every Swift block in all five S3 DocC guides
+is synchronized with DocumentationExamples.swift and runs twice in the separate
+[public consumer](../../../Examples/SchemaExamplesConsumer/README.md), alongside
+15 preserved cases and two compiler negatives. Drift/missing snippets fail the lane.
+Both packages import public products only; neither is a root runtime dependency.
+
+JSONSchemaDSL is absent from the inspected S3 Package.swift and main base. Its
+independent train is untouched. A DSL equality example is deferred until a real
+product is available during integration. An admitted document from any authoring
+source can use this API under the same native dialect; no foreign notation is
+implicitly converted. CLI, JSONHTML, AI and schema interop gain no S3 dependency.