fix(ack)!: make preserveBoundary a detached JSON-object wire view

CHANGELOG.md

@@ -6,6 +6,12 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 ## 2.0.0-alpha.2
 
+### Breaking
+
+* Restrict `Ack.preserveBoundary` to JSON-object schemas and return detached,
+  unmodifiable copies of the input map. Generated preserved map fields infer
+  JSON numbers as `num`.
+
 ### Fixed
 
 * Reject generator aliases whose final passthrough policy makes an inherited
@@ -30,6 +36,8 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 * Resolve same-build value-model and getter references, nullable nested Sets,
   generated-name collisions, and application-generic nullability correctly.
 * Substitute nested and recursive type bounds when resolving type-owned schemas.
+* Infer native JSON `Ack.anyOf(...)` fields without a wire-view wrapper, and
+  validate wire views with parse semantics and no encoders.
 
 ### Documentation and release preparation
 

docs/api-reference/index.mdx

@@ -382,10 +382,10 @@ constructors remain responsible for defensively copying direct inputs.
 
 **Target**: Public, constructable classes
 
-**Generates**: A public `<ClassName>Schema` facade backed by a private raw
-`wireSchema` and typed codec (`_<className>Schema`), plus the `_$ClassAck` mixin
-for `toJson`, `safeToJson`, `copyWith`, and deep collection-aware `==` /
-`hashCode` / `toString`
+**Generates**: A public `<ClassName>Schema` facade backed by a private typed
+codec (`_<className>Schema`) and a `wireSchema` that validates like it but
+returns the JSON map, plus the `_$ClassAck` mixin for `toJson`, `safeToJson`,
+`copyWith`, and deep collection-aware `==` / `hashCode` / `toString`
 
 Ack infers schema fields from constructor-backed fields (including Dart 3.12+
 primary constructors). Required parameters, nullable types, optional parameters,

docs/core-concepts/typesafe-schemas.mdx

@@ -197,7 +197,8 @@ Ack generates a library-private `_profileSchema` codec variable and a public
 - `ProfileSchema.toJsonSchema()` exports the boundary JSON Schema;
 - `ProfileSchema.toSchemaModel()` exports Ack's canonical schema model;
 - `ProfileSchema.schema` is the typed model codec (`_profileSchema`) used for composition;
-- `ProfileSchema.wireSchema` is the raw structural `Map` schema.
+- `ProfileSchema.wireSchema` validates like `schema` and returns the JSON map
+  instead of the model.
 
 Every instantiable `@Schemable` class and implicit sealed-union branch must
 be declared `final class`, initialize its fields through an unnamed generative

packages/ack/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## 2.0.0-alpha.2
 
+### Breaking
+
+* Restrict `Ack.preserveBoundary` to JSON-object schemas
+  (`AckSchema<JsonMap, R>`), such as objects, maps, discriminated unions, and
+  lazy, default, or codec wrappers over them. `BoundarySchema` no longer takes
+  a type argument. Compose list wire views as `Ack.list(X.wireSchema)`, and use
+  a codec's input schema, such as `Ack.string().datetime()`, for a scalar.
+* Return a detached, recursively unmodifiable copy of the input map from
+  `BoundarySchema` parse, runtime validation, and encode instead of the
+  caller's map instance.
+
 ### Fixed
 
 * Accept union-owned discriminators in strict map-backed codec outputs while
@@ -25,6 +36,16 @@
 * Discover selected custom dialects bundled beneath their own active schema
   keywords, without interpreting inactive keyword payloads or annotation data
   as schemas.
+* Return the same JSON from `BoundarySchema` for every string-keyed map
+  container, including `jsonDecode` output, without running an encoder. Nested
+  codec values keep their wire form, one-way transforms no longer reject valid
+  input, and wrapped defaults are not injected.
+* Validate `BoundarySchema` values with parse semantics during encode and
+  runtime validation, so encode no longer accepts a value that parse rejects.
+* Return a schema that is already a wire view from `Ack.preserveBoundary`
+  unchanged instead of validating its values twice.
+* Export a wrapper's non-null restriction as `allOf: [{not: {type: null}}]`
+  only when the narrowed schema can still accept `null`.
 
 ## 2.0.0-alpha.1
 

packages/ack/lib/src/ack.dart

@@ -109,16 +109,21 @@ final class Ack {
   /// snapshot of the input.
   static AnySchema any() => const AnySchema();
 
-  /// Validates with [schema] while returning the original boundary value.
+  /// Creates a wire view of a JSON object [schema]: it validates like
+  /// [schema] and returns the JSON map instead of the runtime value.
   ///
-  /// Nested codecs still run for validation, but their decoded runtime values
-  /// are discarded. This keeps wire data composable with a later typed parse.
-  static BoundarySchema<Boundary> preserveBoundary<
-    Boundary extends Object,
-    Runtime extends Object
-  >(AckSchema<Boundary, Runtime> schema) {
-    return BoundarySchema<Boundary>(schema);
-  }
+  /// Nested models, codecs, defaults, and refinements still run for
+  /// validation, but their decoded runtime values are discarded and no encoder
+  /// runs. Parse and encode return a detached, recursively unmodifiable copy
+  /// of the input map. This keeps wire data composable with a later typed
+  /// parse. Put `withDefault` outside the wire view; a default inside it does
+  /// not apply. A [schema] that is already a wire view is returned unchanged.
+  static BoundarySchema preserveBoundary<Runtime extends Object>(
+    AckSchema<JsonMap, Runtime> schema,
+  ) => switch (schema) {
+    final BoundarySchema wire => wire,
+    _ => BoundarySchema(schema),
+  };
 
   /// Creates a schema reference that is resolved lazily on first use.
   ///

packages/ack/lib/src/schema_model/ack_schema_model_builder.dart

@@ -113,7 +113,9 @@ final class _SchemaModelBuilder {
       var layered = base
           .withDescription(schema.description ?? base.description)
           .withNullable(schema.isNullable);
-      if (schema.excludesInnerNull) layered = _excludeNull(layered);
+      if (schema.excludesInnerNull && _admitsNull(layered)) {
+        layered = _excludeNull(layered);
+      }
       // `DefaultSchema.constraints` is a passthrough to `inner.constraints`,
       // which `_build(schema.inner)` already applied. Re-running them here
       // would emit duplicate warnings (e.g. datetime range under a default).
@@ -617,6 +619,21 @@ final class _SchemaModelBuilder {
   }
 }
 
+/// Whether [model] can still accept `null` after its own nullable flag.
+///
+/// References, imported resources, and extension keywords are opaque here, so
+/// they count as accepting `null`.
+bool _admitsNull(AckSchemaModel model) {
+  if (model.nullable || model.extensions.isNotEmpty) return true;
+  return switch (model) {
+    AckRefSchemaModel() || AckRawSchemaModel() || AckNullSchemaModel() => true,
+    AckAnyOfSchemaModel(:final schemas) ||
+    AckOneOfSchemaModel(:final schemas) => schemas.any(_admitsNull),
+    AckAllOfSchemaModel(:final schemas) => schemas.every(_admitsNull),
+    _ => false,
+  };
+}
+
 AckSchemaModel _excludeNull(AckSchemaModel model) => model.withExtensions({
   ...model.extensions,
   'allOf': [

packages/ack/lib/src/schemas/boundary_schema.dart

@@ -1,18 +1,26 @@
 part of 'schema.dart';
 
-/// Schema wrapper that validates with [inner] while preserving the original
-/// boundary value.
+/// Wire view of a JSON object schema: validates with [inner] and returns the
+/// JSON instead of the runtime value.
 ///
-/// This is useful when callers need a composable schema for validating wire
-/// data without retaining any runtime values produced by nested codecs.
+/// Parse, runtime validation, and encode all run the full parse of [inner]
+/// (nested models, codecs, defaults, and refinements), never an encoder. Each
+/// returns a detached, recursively unmodifiable copy of the validated input
+/// map, so the result never depends on the input's container type and never
+/// aliases the caller's map. Each wire view copies its whole subtree, so
+/// compose wire views inside a plain `Ack.object(...)` rather than inside
+/// another wire view.
+///
+/// The wrapper's own nullability decides whether `null` is accepted; `null`
+/// never reaches [inner]. A default inside [inner] therefore does not apply.
+/// Put `withDefault` outside the wrapper instead.
 @immutable
-final class BoundarySchema<Boundary extends Object>
-    extends AckSchema<Boundary, Boundary>
+final class BoundarySchema extends AckSchema<JsonMap, JsonMap>
     with
-        FluentSchema<Boundary, Boundary, BoundarySchema<Boundary>>,
-        WrapperSchema<Boundary, Boundary, BoundarySchema<Boundary>> {
+        FluentSchema<JsonMap, JsonMap, BoundarySchema>,
+        WrapperSchema<JsonMap, JsonMap, BoundarySchema> {
   @override
-  final AckSchema<Boundary, Object> inner;
+  final AckSchema<JsonMap, Object> inner;
 
   BoundarySchema(
     this.inner, {
@@ -27,64 +35,67 @@ final class BoundarySchema<Boundary extends Object>
          description: description ?? inner.description,
        );
 
-  SchemaResult<Boundary> _validateBoundary(
+  SchemaResult<JsonMap> _validateBoundary(
     Object? value,
     SchemaContext context,
   ) {
     final nullResult = handleNullInput(value, context);
     if (nullResult != null) return nullResult;
 
-    final result = inner.parseWithContext(value, context);
+    // Encode leniency (for example, omitted defaults) must not let the wire
+    // view accept a value that its parse would reject.
+    final parseContext = context.operation == SchemaOperation.parse
+        ? context
+        : context.createChild(
+            name: context.name,
+            schema: inner,
+            value: value,
+            pathSegment: '',
+            operation: SchemaOperation.parse,
+          );
+    final result = inner.parseWithContext(value, parseContext);
     if (result.isFail) return SchemaResult.fail(result.getError());
 
-    final Boundary boundary;
-    final normalizedMap = jsonMapOrNull(value);
-    if (value is Boundary) {
-      boundary = value;
-    } else if (normalizedMap is Boundary) {
-      boundary = normalizedMap as Boundary;
-    } else {
-      final runtime = result.getOrNull()!;
-      final encodeContext = context.createChild(
-        name: context.name,
-        schema: inner,
-        value: runtime,
-        pathSegment: '',
-        operation: SchemaOperation.encode,
+    // Copying also canonicalizes any string-keyed map to a JsonMap.
+    final copy = deepUnmodifiableCopy(value);
+    if (copy is! JsonMap) {
+      return SchemaResult.fail(
+        _buildTypeMismatch(
+          expectedType: schemaType,
+          actualValue: value,
+          context: context,
+        ),
       );
-      final encoded = inner.encodeWithContext(runtime, encodeContext);
-      if (encoded.isFail) return SchemaResult.fail(encoded.getError());
-      boundary = encoded.getOrNull()!;
     }
 
-    return applyConstraintsAndRefinements(boundary, context);
+    return applyConstraintsAndRefinements(copy, context);
   }
 
   @override
   @protected
-  SchemaResult<Boundary> parseWithContext(
+  SchemaResult<JsonMap> parseWithContext(
     Object? value,
     SchemaContext context,
   ) => _validateBoundary(value, context);
 
   @override
   @protected
-  SchemaResult<Boundary> validateRuntimeWithContext(
+  SchemaResult<JsonMap> validateRuntimeWithContext(
     Object? value,
     SchemaContext context,
   ) => _validateBoundary(value, context);
 
   @override
   @protected
-  SchemaResult<Boundary> encodeWithContext(
-    Boundary value,
+  SchemaResult<JsonMap> encodeWithContext(
+    JsonMap value,
     SchemaContext context,
   ) => _validateBoundary(value, context);
 
   @override
-  BoundarySchema<Boundary> copyWithInner(AnyAckSchema newInner) {
-    return BoundarySchema<Boundary>(
-      newInner as AckSchema<Boundary, Object>,
+  BoundarySchema copyWithInner(AnyAckSchema newInner) {
+    return BoundarySchema(
+      newInner as AckSchema<JsonMap, Object>,
       isNullable: isNullable,
       isOptional: isOptional,
       description: description,
@@ -94,14 +105,14 @@ final class BoundarySchema<Boundary extends Object>
   }
 
   @override
-  BoundarySchema<Boundary> copyWith({
+  BoundarySchema copyWith({
     bool? isNullable,
     bool? isOptional,
     String? description,
-    List<Constraint<Boundary>>? constraints,
-    List<Refinement<Boundary>>? refinements,
+    List<Constraint<JsonMap>>? constraints,
+    List<Refinement<JsonMap>>? refinements,
   }) {
-    return BoundarySchema<Boundary>(
+    return BoundarySchema(
       inner,
       isNullable: isNullable ?? this.isNullable,
       isOptional: isOptional ?? this.isOptional,
@@ -114,7 +125,7 @@ final class BoundarySchema<Boundary extends Object>
   @override
   bool operator ==(Object other) {
     if (identical(this, other)) return true;
-    if (other is! BoundarySchema<Boundary>) return false;
+    if (other is! BoundarySchema) return false;
 
     return baseFieldsEqual(other) && inner == other.inner;
   }

packages/ack/test/json_schema_vocabulary_contract_test.dart

@@ -260,9 +260,9 @@ void main() {
   test('fluent null policies use operators from an active dialect', () {
     final widened = _import({'type': 'string'}).nullable();
     final narrowed = _import({}, vocabularies: []).nullable(value: false);
-    final wrapped = Ack.preserveBoundary(
-      _import({}, vocabularies: []),
-    ).nullable(value: false);
+    final wrapped = _import({}, vocabularies: [])
+        .codec<Object>(decode: (value) => value, encode: (value) => value)
+        .nullable(value: false);
     final defaulted = _import({
       'type': ['string', 'null'],
     }).withDefault('fallback');

packages/ack/test/schema_model/ack_schema_model_builder_test.dart

@@ -453,15 +453,22 @@ void main() {
           .withDefault('ack')
           .toSchemaModel();
       final boundary = Ack.preserveBoundary(
-        Ack.string().minLength(2),
+        Ack.object({'name': Ack.string().minLength(2)}),
       ).toSchemaModel();
 
       expect(withDefault.toJsonSchema(), {
         'type': 'string',
         'minLength': 2,
         'default': 'ack',
       });
-      expect(boundary.toJsonSchema(), {'type': 'string', 'minLength': 2});
+      expect(boundary.toJsonSchema(), {
+        'type': 'object',
+        'properties': {
+          'name': {'type': 'string', 'minLength': 2},
+        },
+        'required': ['name'],
+        'additionalProperties': false,
+      });
       expect(withDefault.warnings, isEmpty);
       expect(boundary.warnings, isEmpty);
     });