Appendix A — Open Questions: The Inquiry Ledger

This ledger records what the design guidance does not yet settle: hypotheses resting on sparse evidence, version-sensitive mechanics, and tensions for which either choice can fail. Its purpose is movement, not accumulation. Questions graduate into doctrine when public documentation, source, tests, or reproducible released-version probes support a bounded recommendation. They retreat when counterexamples expose a missing condition, and the affected doctrine should then be amended rather than silently defended.

Every entry should preserve the competing risks. More metadata can align projections but make authoring and startup expensive. A richer semantic model can enable analysis but duplicate a foreign authority. Strict admission can protect invariants but destroy unknown content needed for round trips. The ledger is useful only if it asks what evidence distinguishes those losses, not merely whether a favored technique can be made to work.

A.1 Scale of property metadata

rtemis shows contract-as-data driving validation, defaults, schema output, interfaces, and contextual preparation. The unresolved question is when that machinery pays for itself.

Evidence needed: maintenance histories comparing handwritten and metadata-driven properties; contributor cost for adding or debugging a property; alignment tests across releases; and examples where such a system was simplified or removed.

A.2 Promotion from reusable property to semantic class

A shared property names a contract cheaply; a class lets the value travel independently and participate in dispatch. The boundary remains judgment-dependent when a concept is meaningful but has no operation of its own.

Evidence needed: cases where early promotion prevented ambiguity or rework; cases where it only added wrapping overhead; and criteria based on extraction, independent persistence, or operation vocabulary.

A.3 Direct adaptation versus semantic IR

A pairwise adapter is simpler for one source and target. An IR may reduce duplication across several sources and targets, but an “uber-schema” can merely accumulate incidental fields.

Evidence needed: multiple real inputs or outputs sharing stable semantics; operations that consume shared meaning independently of serialization; preservation and loss matrices; and migration experience showing whether an IR reduces or relocates complexity.

The competing risks are premature generalization and adapter proliferation. An IR introduced before stable shared meaning is visible becomes another schema to migrate. Waiting too long leaves every pairwise adapter to rediscover normalization, equality, and loss policy. Graduation therefore requires evidence from independent consumers, not the size of the class graph.

A.4 Typed expression catalogs

Opaque expressions preserve engine authority and version flexibility. Typed nodes enable analysis, safer construction, and multi-target compilation. The point at which analysis justifies the catalog remains domain-specific.

Evidence needed: a substantive consumer beyond serialization; measured versioning cost; a policy for unknown operators; and evidence that combinators are insufficient but a full AST is maintainable.

A.5 Deep value semantics with references

An S7 value may contain an environment, R6 object, external pointer, connection, or cache. Replacing the outer value does not make referenced internals independent, and inner mutation does not automatically re-run outer validation.

Open questions include which payloads should be forbidden, snapshotted, or excluded from equality and serialization; whether external memo tables keyed by semantic content are reliable; and how APIs should state shallow versus deep guarantees.

A.6 Method coverage for open families

Abstract parents and fallback methods do not seal a family. Registries and tests can check known variants, but extensions may add classes after those checks run.

Open questions: whether coverage belongs at test time, registration, or first use; how optional generics differ from missing methods; and how third parties run reusable conformance suites. Native sealed-family or exhaustiveness support would change the guidance.

A.7 Explicit null, omission, and defaults

R’s NULL, absent arguments, empty vectors, NA, and absent wire keys can represent different states. Preserving every needed distinction remains difficult, especially for generated constructors.

Evidence needed: released-version probes for omitted arguments versus explicit NULL; public formats where omission changes behavior; ergonomic constructor patterns; and serializer laws for omitted, null, empty, and defaulted states.

A.8 Survival of unknown extensions

A pass-through bag promises fidelity only if every supported transformation and serialization cycle preserves it. Typed and raw state can collide when a specification promotes a formerly unknown field.

Open questions: whether extensions survive repeated read-modify-write cycles; how upgrades detect collisions; whether preservation is byte-level, structural, or normalized; and whether untrusted extensions create security or resource risks. Corpus-based round-trip tests across released format versions are needed.

A.9 Persistence and class evolution

Persisted S7 values may outlive the package version that created them. Current guidance prefers durable wire representations parsed by current code, but compatibility policy is under-specified.

Open questions: explicit schema versions; migration registration and composition; cross-release compatibility promises; serialized validator environments; and S7 mechanics for revalidation after loading. Version-pinned cross-release probes and public persistence policies are needed. RDS compatibility should be stated narrowly rather than assumed.

A.10 Equality relations

Exact identical() representation, canonical equality, domain equality, and observational equivalence answer different questions. Packages often need several, especially for reflected or normalized documents.

Open questions: which relation powers user comparison; whether canonicalization is stored or computed; how extensions participate; and how diagnostics suppress incidental noise. sqlr supplies one model; recurrence elsewhere would clarify reusable patterns.

A.11 Strict parsing and tolerant admission

Strict known construction can coexist with a tolerant parser preserving unknown or partial variants plus diagnostics. The unresolved issue is when tolerance becomes unsafe or misleading.

Evidence needed: security boundaries requiring rejection; tools that preserve partial documents but refuse compilation; policies for diagnostics and revalidation; and issue histories showing whether partial values clarify or defer failures.

A.12 Aggregate-root granularity

Deep documents resist a simple “one document, one validator” rule. A single root can enforce cross-reference invariants in one place, but it also makes a small edit pay for traversal of an entire graph and can turn unrelated subtrees into one consistency boundary. Nested roots localize construction, replacement, and diagnostics, but delegation can miss invariants that cross their boundaries or duplicate checks at several levels.

Evidence needed: real document models with cross-references at multiple depths; mutation traces showing which edits require global knowledge; failure reports comparing one root with delegated roots; and examples where aggregate boundaries remained stable as the format evolved. The question should graduate only as a decision rule for choosing a boundary, not as a fixed maximum tree depth.

A.13 Diagnostic duplication threshold

The guidance permits a cheap, documented duplicate check when it catches a bad input at a boundary with a materially better message. “Cheap” remains undefined. One duplicate can improve locality; several can drift, disagree on edge cases, and obscure which rule is authoritative.

Evidence needed: maintenance histories where duplicate checks did or did not drift; tests that prove equivalence to the authoritative rule; measurements for checks on realistic payloads; and user evidence that the earlier diagnostic changes recovery. A candidate threshold is that a duplicate must have one named authority, an explicit equivalence test, negligible cost on the boundary’s expected payload, and no independent evolution. A duplicate that needs its own exceptions or release policy has become a second authority and should retreat.

A.14 S7 version watch list

Recheck these mechanics against publication versions:

• constructor defaults and omitted versus explicit NULL;
• validator order, invocation count, and character-vector diagnostics;
• grouped replacement and deferred validation;
• getter output validation behavior;
• multiple dispatch specificity and S7::super();
• environment, R6, and external-pointer properties;
• serialization across class-definition changes;
• package hooks relevant to validation or migration.

A.15 Focused benchmark agenda

The useful question is not whether S7 is “fast.” Measurements should compare design alternatives at the points where the guidance makes a choice, with R and S7 versions, payload shape, garbage-collection policy, and warm-up stated.

Bulk construction. Compare constructor-per-node construction with documented deferred-validation or batching mechanisms across realistic flat and nested values. Record allocations and validation work as well as elapsed time; a fast path that weakens the certification boundary is not equivalent.

Grouped versus sequential replacement. Compare S7::set_props() with sequential @<- updates for several property counts and validator costs. Measure intermediate copies and validator invocations, and include a case where only the final grouped state is valid.

Nested copy cost. Vary top-level width, nesting depth, and shared payload size to determine what replacement copies and what remains shared. Include two-binding divergence checks so an optimization is not mistaken for a semantic change.

Hot-loop dispatch. Compare direct calls, S3 dispatch, and S7 single and multiple dispatch in representative compiler or tree-walk loops. Report the fraction of total pass time attributable to dispatch; isolated nanoseconds do not establish architectural significance.

Metamodel startup. Measure package load and class-definition cost as the number and richness of property factories increase, including declaration validation and generated projections. This tests the author-safety benefit against interactive and worker-startup latency.

Serialized-corpus overhead. Compare many small S7 objects, aggregate serialization, and durable wire forms across corpus sizes. Separate payload bytes from repeated class or validator metadata, and test cross-version load behavior rather than treating successful deserialization as compatibility.

These benchmarks should graduate guidance only when they reproduce across released versions and realistic graphs. Surprising results should first narrow the recommendation; they should not become a universal performance claim.

A.16 Evidence tripwires

Revise the guidance if S7 adds sealed classes, exhaustiveness checks, or load-time migration; several packages sustain generated native graphs from owned semantic specifications; property metadata is removed as uneconomic; a typed AST is collapsed; an open bag beats a semantic model on long-term correctness; or public round-trip corpora reveal systematic extension loss.

The ledger should also collect counterexamples: designs that violate current defaults and work well, migrations away from S7 with stated reasons, and duplicated checks that remain aligned because their diagnostic value is worth the cost.

A counterexample entry should name the pressure the current guidance missed, the competing risk that dominated, and the smallest exception that explains the result. Repeated retreats are evidence that the doctrine’s boundary is wrong; an isolated exception is not permission to erase the boundary.