Merge FEATURE-v3-source-layout: separate library definitions from headers

Author: etr

.gitignore

@@ -166,3 +166,6 @@ __pycache__/
 !scripts/run-v3-packaged-adapters.py
 !scripts/check-v3-public-http1.py
 !scripts/test-v3-packaged-adapters.py
+
+# v3 source-layout compiled implementation contract checker.
+!scripts/check-v3-compiled-operations.py

CONTRIBUTING.md

@@ -243,3 +243,18 @@ Please open an issue on `etr/libhttpserver` if you have suggestions for new labe
 
 [beginner]:https://github.com/search?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Abeginner+label%3Ahelp-wanted+user%3Aetr+sort%3Acomments-desc
 [help-wanted]:https://github.com/search?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted+user%3Aetr+sort%3Acomments-desc+-label%3Abeginner
+
+## v3 source ownership
+
+On the `v3` branch, public compiled operations live in `src/<logical>.cpp`,
+owned by installed `src/httpserver/<logical>.hpp`. Private implementations and
+shared headers live in `src/detail/` and noninstalled `src/httpserver/detail/`.
+Cohesive split translation units share the actual owning header; do not create
+dummy headers or recombine engines just to match filenames.
+
+Normal library linkage supplies non-template behavior. Keep templates and
+constexpr definitions visible to consumers, along with trivial accessors/value
+operations and justified small byte/arithmetic primitives. Preserve complete
+public representation and required template support in installed headers; an
+installed header must never include a noninstalled private/provider/platform
+header. Record ownership and inline exceptions in `docs/v3-source-layout.md`.

Makefile.am

@@ -278,7 +278,7 @@ check-hygiene:
 # still runs the full test suite plus the header / example / lint gates, but
 # skips the source-only doc gates whose inputs it cannot satisfy. Release runners
 # may provide a verified specs/ tooling bundle; it is not a source checkout.
-check-local: check-headers check-examples lint-warning-suppressions lint-littletest-skip-exit-code lint-fence-balance check-v3-native-linkage
+check-local: check-v3-compiled-operations check-headers check-examples lint-warning-suppressions lint-littletest-skip-exit-code lint-fence-balance check-v3-native-linkage
 	@if test -d "$(top_srcdir)/specs" && test -e "$(top_srcdir)/.git"; then \
 		$(MAKE) $(AM_MAKEFLAGS) check-readme check-release-notes check-doxygen ; \
 	else \
@@ -611,3 +611,10 @@ EXTRA_DIST += test/installed/task199-capabilities.md \
 
 EXTRA_DIST += scripts/lib/v3_examples.py scripts/lib/v3_example_consumers.py \
     specs/architecture/v3/v2-parity-inventory.md
+
+EXTRA_DIST += docs/v3-source-layout.md scripts/check-v3-compiled-operations.py
+
+check-v3-compiled-operations: $(top_builddir)/src/libhttpserver.la
+	python3 $(top_srcdir)/scripts/check-v3-compiled-operations.py $(top_builddir)/src/.libs/libhttpserver.a
+
+.PHONY: check-v3-compiled-operations

docs/v3-source-layout.md

@@ -81,8 +81,10 @@ src/httpserver/websocket/session.hpp
 "
 
 V3CORE_SOURCES="
-src/detail/features.cpp
-src/detail/server_tls_credentials.cpp
+src/detail/tls_psk.cpp
+src/server/tls_psk.cpp
+src/server/tls_credentials.cpp
+src/features.cpp
 src/detail/io_operation.cpp
 src/detail/io_udp_backend.cpp
 src/detail/quic_invariant_header.cpp
@@ -95,26 +97,162 @@ src/detail/io_kqueue_backend.cpp
 src/detail/io_iocp_backend.cpp
 src/detail/io_managed_backend.cpp
 src/detail/io_managed_socket_backend.cpp
+src/detail/io_external_adapter.cpp
+src/detail/io_wake_source.cpp
 src/detail/worker_pool.cpp
 src/detail/connection_engine.cpp
 src/detail/connection_engine_request.cpp
 src/detail/listener_engine.cpp
-src/detail/server.cpp
-src/detail/auth_basic.cpp
-src/detail/auth_digest.cpp
-src/detail/forms_urlencoded.cpp
-src/detail/forms_multipart.cpp
-src/detail/forms_multipart_files.cpp
-src/detail/server_hooks.cpp
+src/detail/drain_scope.cpp
+src/server/server.cpp
+src/auth/basic_auth.cpp
+src/auth/digest_auth.cpp
+src/forms/urlencoded.cpp
+src/forms/multipart.cpp
+src/forms/multipart_files.cpp
+src/server/hooks.cpp
 src/detail/request_lifecycle.cpp
-src/detail/net_address.cpp
+src/net/address.cpp
 src/detail/peer_policy.cpp
-src/detail/http1_websocket_handshake.cpp
-src/detail/connection_engine_websocket.cpp
-src/detail/websocket_driver.cpp
 src/detail/websocket_codec.cpp
+src/detail/websocket_driver.cpp
 src/detail/websocket_session_state.cpp
-src/detail/websocket_session.cpp
+src/websocket/session.cpp
+src/detail/http1_websocket_handshake.cpp
+src/detail/connection_engine_websocket.cpp
+src/detail/http2_frame.cpp
+src/detail/http2_connection.cpp
+src/detail/http2_request_engine.cpp
+src/detail/http2_native_stream.cpp
+src/detail/http2_native_timers.cpp
+src/detail/http2_tcp_owner.cpp
+src/detail/http2_request_head.cpp
+src/detail/http2_body_stream.cpp
+src/detail/http2_response_stream.cpp
+src/detail/http2_stream_flow.cpp
+src/detail/websocket_handshake.cpp
+src/detail/http2_websocket_handshake.cpp
+src/detail/http2_websocket_stream.cpp
+src/detail/quic_varint.cpp
+src/detail/quic_packet.cpp
+src/detail/quic_frame.cpp
+src/detail/quic_frame_write.cpp
+src/detail/quic_transport_parameters.cpp
+src/detail/quic_amplification.cpp
+src/detail/quic_stream_state.cpp
+src/detail/quic_reassembly.cpp
+src/detail/quic_ack_state.cpp
+src/detail/quic_recovery.cpp
+src/detail/quic_recovery_timer.cpp
+src/detail/quic_repacketize.cpp
+src/detail/quic_flow_control.cpp
+src/detail/quic_flow_receive.cpp
+src/detail/quic_flow_send.cpp
+src/detail/quic_storage.cpp
+src/detail/quic_recovery_flow.cpp
+src/detail/quic_congestion.cpp
+src/detail/quic_pacing.cpp
+src/detail/quic_send_schedule.cpp
+src/detail/quic_persistent_congestion.cpp
+src/detail/quic_recovery_emission.cpp
+src/detail/http3_frame.cpp
+src/detail/http3_connection.cpp
+src/detail/http3_settings.cpp
+src/detail/http3_request_head.cpp
+src/detail/http3_request_engine.cpp
+src/detail/http3_body_stream.cpp
+src/detail/http3_response_stream.cpp
+src/detail/quic_connection_identity.cpp
+src/detail/quic_path_mtu.cpp
+src/detail/quic_recovery_mtu.cpp
+src/detail/quic_datagram_sizing.cpp
+src/detail/quic_recovery_datagram.cpp
+src/detail/quic_connection_lifecycle.cpp
+src/detail/http3_qpack.cpp
+src/detail/http3_control_drain.cpp
+src/detail/http3_drain.cpp
+src/detail/http3_websocket_handshake.cpp
+src/detail/http3_websocket_handshake_stream.cpp
+src/detail/http3_websocket_stream.cpp
+src/server/diagnostics.cpp
+src/http/cookie.cpp
+src/detail/http3_native_stream.cpp
+src/detail/http3_semantic_stream.cpp
+src/http/method.cpp
+src/http/fields.cpp
+src/server/budgets.cpp
+src/server/route_sync.cpp
+src/server/routes.cpp
+src/server/options.cpp
+src/detail/net_address.cpp
+src/detail/diagnostics_access.cpp
+src/detail/tls_credentials_access.cpp
+src/detail/tls_psk_access.cpp
+src/detail/hook_bus.cpp
+src/response_definition.cpp
+src/body_reader.cpp
+src/exchange.cpp
+src/response_sources.cpp
+src/response_writer.cpp
+src/server/peer_policy.cpp
+src/detail/io_poll_sys.cpp
+src/detail/hpack_primitives.cpp
+src/detail/qpack_encoder.cpp
+src/detail/lifecycle_sink.cpp
+src/detail/hpack_decoder.cpp
+src/detail/qpack_decoder.cpp
+src/detail/qpack_instructions.cpp
+src/detail/sha1.cpp
+src/detail/secure_compare.cpp
+src/detail/http1_response_mode.cpp
+src/detail/digest_response.cpp
+src/detail/forms_verdict.cpp
+src/detail/resource_charge.cpp
+src/detail/hpack_encoder.cpp
+src/detail/websocket_utf8.cpp
+src/detail/quic_recovery_internal.cpp
+src/detail/request_handler_frames.cpp
+src/detail/http1_error_synth.cpp
+src/detail/md5.cpp
+src/detail/base64.cpp
+src/detail/sha256.cpp
+src/detail/http1_body_decoder.cpp
+src/detail/http1_body_mode.cpp
+src/detail/http1_response_outbox.cpp
+src/detail/exchange_runner.cpp
+src/detail/http1_response_framer.cpp
+src/detail/qpack_field_section.cpp
+src/detail/digest_ledger.cpp
+src/detail/entropy_sys.cpp
+src/detail/digest_nonce.cpp
+src/detail/http1_head_parser.cpp
+src/detail/http1_body_source.cpp
+src/detail/qpack_primitives.cpp
+src/detail/qpack_dynamic_table.cpp
+src/detail/forms_multipart.cpp
+src/detail/digest_hex.cpp
+src/detail/http2_request_state.cpp
+src/detail/io_timer_sweep.cpp
+src/detail/hpack_field_section.cpp
+src/detail/forms_urlencoded.cpp
+src/detail/auth_text.cpp
+src/detail/http1_target.cpp
+src/detail/hpack_dynamic_table.cpp
+src/detail/digest_params.cpp
+src/detail/http3_request_state.cpp
+src/detail/quic_flow_internal.cpp
+src/detail/multiplexed_request_head.cpp
+src/concurrency/cancellation.cpp
+src/concurrency/executor.cpp
+src/concurrency/task.cpp
+src/concurrency/resume_signal.cpp
+src/websocket/options.cpp
+src/detail/unescape_helpers.cpp
+src/detail/http1_host.cpp
+src/detail/io_poll_backend_timers.cpp
+src/detail/http2_dispatch.cpp
+src/detail/connection_engine_config.cpp
+src/detail/io_completion_storage.cpp
 "
 
 # TASK-114: the in-tree codec/hash/entropy primitives the auth TU and

scripts/audit-v3-native-linkage.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Check the installed-library implementation contract for representative operations."""
+import argparse
+import subprocess
+
+# These operations must have a library-owned definition even when no consumer
+# instantiates them. Behavioral suites cover their semantics independently.
+OPERATIONS = (
+    'httpserver::http::fields::append(',
+    'httpserver::server::server_options::validate(',
+    'httpserver::server::resource_budget::reserve(',
+    'httpserver::server::route_pattern::parse(',
+    'httpserver::server::make_sync_route(',
+    'httpserver::manual_executor::run_one(',
+    'httpserver::detail::current_executor_slot(',
+    'httpserver::detail::task_frame_base::finish(',
+    'httpserver::stop_token::cancellation_awaiter::await_suspend(',
+    'httpserver::detail::fire_trigger(',
+    'httpserver::exchange::admit_body(',
+    'httpserver::body_reader::collect(',
+    'httpserver::response_writer::finish(',
+    'httpserver::response_definition::owned_bytes(',
+    'httpserver::send_definition(',
+    'httpserver::detail::send_cursor::pull(',
+    'httpserver::detail::http1_head_parser::',
+    'httpserver::detail::hpack_decoder::',
+    'httpserver::detail::qpack_decoder::',
+    'httpserver::websocket::options::validate(',
+    'httpserver::detail::http2_dispatch::post(',
+    'httpserver::detail::valid_http1_host(',
+    'httpserver::detail::unescape_buf_raw(',
+    'httpserver::detail::owned_completion_storage::claim_read(',
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('library')
+    args = parser.parse_args()
+    result = subprocess.run(['nm', '-C', args.library],
+                            check=True, text=True, capture_output=True)
+    definitions = [line for line in result.stdout.splitlines()
+                   if ' T ' in line]
+    missing = [name for name in OPERATIONS if not any(name in line for line in definitions)]
+    if missing:
+        raise SystemExit('Missing compiled library operations:\n' + '\n'.join(missing))
+    print('PASS representative operations have compiled library definitions')
+
+
+if __name__ == '__main__':
+    main()

scripts/check-v3-compiled-operations.py

@@ -95,6 +95,21 @@ def package_lane(args, source, output, mode, inventory):
             if cell['tls'] == mode and cell['linkage'] == linkage:
                 public[linkage]['cells'].append(traffic(executable, cell, consumer_dir, runtime_env, inventory))
                 (lane / 'public.json').write_text(json.dumps(public, indent=2))
+        compiled_sources = []
+        for name in ('v3_compiled_operations.cpp', 'v3_compiled_operations_worker.cpp'):
+            copied = consumer_dir / name
+            if not copied.exists():
+                shutil.copyfile(source / 'test/installed' / name, copied)
+            compiled_sources.append(copied)
+        compiled_executable = consumer_dir / ('compiled_operations_' + linkage + suffix)
+        compiled_provenance = compile_probe(args.compiler, compiled_sources, cflags, libraries,
+                                           compiled_executable, command, runtime_env, source, build, prefix, False)
+        compiled_graph = audit.dependency_graph([str(compiled_executable)])
+        matrix.check_linkage(compiled_graph, linkage, prefix)
+        command([str(compiled_executable)], consumer_dir, runtime_env)
+        public[linkage]['compiled_operations'] = dict(compile=compiled_provenance, dependencies=compiled_graph)
+        command([sys.executable, str(source / 'scripts/check-v3-compiled-operations.py'),
+                 str(prefix / 'lib/libhttpserver.a')], consumer_dir, runtime_env)
         private_dir = lane / ('integration-' + linkage)
         private_dir.mkdir()
         private_libraries = libraries + (shlex.split(env['V3_TLS_LIBS']) if mode == 'yes' else [])

scripts/check-v3-installed-consumer.py

@@ -93,8 +93,24 @@ PY
     esac
     [ -n "$(find "$build/$target/seeds" -type f -print -quit)" ] || { echo "empty corpus: $target" >&2; exit 1; }
     sources=("$root/test/fuzz/${target}_fuzz.cpp")
-    if [ "$target" = http1_head ]; then sources+=("$root/src/detail/net_address.cpp"); fi
-    if [ "$target" = websocket_codec ]; then sources+=("$root/src/detail/websocket_codec.cpp"); fi
+    if [ "$target" = http1_head ] || [ "$target" = http1_body ] || [ "$target" = hpack ]; then
+        sources+=("$root/src/http/fields.cpp" "$root/src/http/method.cpp"
+            "$root/src/server/budgets.cpp" "$root/src/detail/resource_charge.cpp")
+    fi
+    if [ "$target" = http1_head ] || [ "$target" = http1_body ]; then
+        sources+=("$root/src/net/address.cpp" "$root/src/detail/net_address.cpp"
+            "$root/src/detail/http1_head_parser.cpp" "$root/src/detail/http1_body_mode.cpp" "$root/src/detail/http1_target.cpp"
+            "$root/src/detail/http1_host.cpp" "$root/src/detail/unescape_helpers.cpp")
+    fi
+    if [ "$target" = http1_body ]; then
+        sources+=("$root/src/detail/http1_body_decoder.cpp")
+    fi
+    if [ "$target" = hpack ]; then
+        sources+=("$root/src/detail/hpack_primitives.cpp" "$root/src/detail/hpack_dynamic_table.cpp"
+            "$root/src/detail/hpack_field_section.cpp" "$root/src/detail/hpack_decoder.cpp"
+            "$root/src/detail/hpack_encoder.cpp")
+    fi
+    if [ "$target" = websocket_codec ]; then sources+=("$root/src/detail/websocket_codec.cpp" "$root/src/detail/websocket_utf8.cpp"); fi
     if [ "$target" = quic_parser ]; then
         sources+=("$root/src/detail/quic_invariant_header.cpp" "$root/src/detail/quic_varint.cpp"
             "$root/src/detail/quic_packet.cpp" "$root/src/detail/quic_frame.cpp"

scripts/run-v3-protocol-fuzz.sh

@@ -418,3 +418,23 @@ child receipts, commands, processes, depfiles, link maps, executables, fixtures
 and selected client/tool inputs. Both adapters use exclusive outputs and
 caller-bound run IDs, preserving failed attempts. No general stage registry or
 TASK-185 runner import is introduced. Its exact integration remains TASK-185 owned.
+
+### Source ownership and compiled operations
+
+Public non-template implementation is compiled in `src/<logical>.cpp`, paired
+with installed `src/httpserver/<logical>.hpp`. Private implementation is compiled
+in `src/detail/<logical>.cpp`, paired with noninstalled
+`src/httpserver/detail/<logical>.hpp`. Cohesive engine splits explicitly share
+their actual owning header; matching basenames do not require dummy headers or
+recombined protocol engines. Provider-conditioned implementation stays within
+the private provider target.
+
+Templates and constexpr operations remain visible for instantiation and constant
+evaluation. Trivial accessors, value operations and small byte/arithmetic
+primitives may remain inline with the recorded reason in
+[the complete ownership inventory](../../../docs/v3-source-layout.md). Complete
+public representation and template support remain in installed headers, including
+necessary detail declarations. An installed header never includes a noninstalled
+private header. Normal library linkage supplies compiled operations; standalone
+header compilation does not imply link-free runtime behavior. Extraction preserves
+API, representation, suspension points, resource accounting and protocol behavior.