013: Practices from sibling repositories
Dated design and evidence record. Original wording, line order and historical source identities are preserved; use the current guides for operation.
Record sections
013: Practices from sibling repositories ====================================== Date: 2026-10-16 Status: synthesis and implementation guidance; findings are not all implemented Purpose and evidence -------------------- Carry forward useful practices and the reasons behind them from Magnet, NMRPeak and SECS. The study covered current implementations, regression tests and selected corrective history. Independent read-only reviewers examined each sibling. Reading a regression establishes its intended assertion; these reviews did not rerun the sibling suites or establish current deployed behavior. Use means applicable guidance, with adoption status stated below. Avoid names failure patterns or inappropriate adaptations. Not applicable means outside the current contained baseline and planned label-free coordinate slice; reconsider only when a real consumer appears. This note does not authorize upstream edits, new acquisition, provider integration or a broad foundation refactor. References use repository prefixes and paths at the following inspected commits. The number after a path is a source line, not a test result. Resolve a reference as the repository's GitHub /blob/<commit>/<path>#L<line> URL. Paths through a submodule refer to the separately recorded nested commit, not arbitrary HEAD. N = numpde/nmrnet-repro, ded6d354764d3caa2f80ac798d1b86a8dbe5cc4b https://github.com/numpde/nmrnet-repro/tree/ded6d354764d3caa2f80ac798d1b86a8dbe5cc4b M = numpde/magnet-deploy, c5813ee35cfbb1c98a5cc5d20a94787271f26486 https://github.com/numpde/magnet-deploy/tree/c5813ee35cfbb1c98a5cc5d20a94787271f26486 P = numpde/nmrpeak-repro, 1697dc84dd1d76ae25b04efc8183fd80614000e5 https://github.com/numpde/nmrpeak-repro/tree/1697dc84dd1d76ae25b04efc8183fd80614000e5 S = numpde/secs-repro, 34f5915c1534278bbf61b4c6592afa44cf94ab08 https://github.com/numpde/secs-repro/tree/34f5915c1534278bbf61b4c6592afa44cf94ab08 S:secs/ is pinned to 0414b5f9d65e61a6ba00aa046e24b8e48ce230b1. P:nmrpeak-upstream/ is pinned to d615e193ec84d124dc916eb10b675744d27a79cf. N:NMRNetplusplus/ is pinned to 3ba8b9c2f3d0a390d00685d238618345c6ab24d7. Nested files can be reached through those parent trees and pinned gitlinks. Additional repository and AGENTS.md sources inspected on 2026-10-16: I = numpde/nmr-api-v1, 6a163b7a9cc1e2c7485b681c0b2b969c7c20e6c8 https://github.com/numpde/nmr-api-v1/tree/6a163b7a9cc1e2c7485b681c0b2b969c7c20e6c8 J = numpde/agent-mail, a484c66639ad2a29d23e407b714e8a5c9f828a14 https://github.com/numpde/agent-mail/blob/a484c66639ad2a29d23e407b714e8a5c9f828a14/AGENTS.md Q = numpde/grimace-py, 08e9c166ec1e8daa1c6f4351e05db6c85af4ece5 https://github.com/numpde/grimace-py/blob/08e9c166ec1e8daa1c6f4351e05db6c85af4ece5/AGENTS.md V = numpde/vote-mcp, 6f595850d199e0d97098c1a7e67ddff774171a25 https://github.com/numpde/vote-mcp/blob/6f595850d199e0d97098c1a7e67ddff774171a25/AGENTS.md R = numpde/magnet, 81db52dd6d2edc3a7a426cf9d71b505804342ad1 https://github.com/numpde/magnet/blob/81db52dd6d2edc3a7a426cf9d71b505804342ad1/AGENTS.md These files and M:AGENTS.md were tracked and unchanged at inspection. The rules are policy evidence, not proof that their implementations or tests comply. GitHub origins were identified locally; remote availability was not checked. Sibling instructions do not govern this checkout. Only the explicitly selected guidance below is adopted; unrelated workflow and product rules remain local. Additional consumer source inspected on 2026-10-16: G = numpde/nmr-gui-v1, d432668a137e860e1bf37bf242f792ec07f01533 https://github.com/numpde/nmr-gui-v1/tree/d432668a137e860e1bf37bf242f792ec07f01533 The API contract and GUI assertions below are source/test evidence at these commits, not proof of a live deployment or every recipient's rendered experience. Use === U01. Preserve one scientific implementation beneath thin checkpoint variants. NMRPeak's HF adapter supplies tokenizer choices and materialization to the shared family runtime. SECS calls encode_modality beneath training forward composition. For 002, share tensor preparation and invocation between H/C while keeping each checkpoint/scaler pair explicit. Use the real UniMat head without training task, labels or loss. Planned already; no service framework is needed. Refs: P:models/nmrpeak_hf_v1/runner/runtime.py:20; S:secs/src/secs/models/model.py:46; N:notes/002_label_free_coordinate_prediction_20261014.txt:29. U02. Expose scientific transformations as inspectable ordered steps. SECS resampling averages a piecewise-linear signal over bins, then normalizes; the loaded boundary additionally max-normalizes and reverses the axis. Ordinary point interpolation is a different algorithm. Preserve 002's actual float32 cast, centering, distance, special-token and padding order. Planned already. Refs: S:src/secs_inference/spectra/secs.py:16,38; S:src/secs_inference/model.py:141. U03. Carry identity from the same selection that controls computation. G01 uses one ordered CPU nucleus layout for gathering features and returning atom indices. For 002, derive the upstream mask and original-index crosswalk from one ordered atom traversal. Keep supplied atom order; no reparsing or canonicalization should reconstruct identity after prediction. Planned already. Ref: M:models/g_01_nmr_forward/magnet/stairway/g_01_nmr_forward/dataloader/collator.py:58. U04. Check semantic compatibility as well as tensor compatibility. E02 compares configured normalization buffers before strict loading overwrites them. Matching keys and shapes alone do not prove the intended normalization. Keep dictionary ordering, paired scaler identity, full state compatibility and actual device/dtype checks separate. Existing baseline checks and 002 cover this. Ref: M:models/e_02_ch_nmrexp/magnet/stairway/e_02_ch_nmrexp/inference.py:104,307. U05. Bind verification to the bytes consumed. NMRPeak keeps a verified, rewound checkpoint descriptor through loading; its test replaces the pathname and still reads admitted bytes. Our verified_member hashes and returns a path. Strengthen 002's checkpoint/scaler/dictionary contract, using existing artifact ownership. A held descriptor prevents pathname substitution, not in-place writes to that inode; an immutable verified buffer or enforced nonmutation through consumption is needed for that stronger guarantee. Refs: P:families/nmrpeak/checkpoint_file.py:34; P:tests/unit/test_checkpoint_file.py:23; N:tools/baseline_prepare.py:157. U06. Keep qualification evidence portable and population-complete. NMRPeak publishes reviewed inputs, raw observations, provenance and derived reports with an offline verifier. For 002, retain a compact reviewed evidence bundle supporting published claims beyond ignored working directories. Bind derived oracle fixtures to exact producer bytes as well as source records, and assert the exact historical fixture-key and 64-position sets before iterating. These are narrow qualification refinements, not a new evidence registry. Refs: P:docs/benchmark.md:57; P:benchmark_tools/archive.py:16; S:tests/qualification/test_frontend_reference_lock.py:41; S:tests/input/scenarios/test_cheminfo_jobs.py:18; N:README.md:183. Related SECS corrections: d4ce38c7d3c5a4663fa26222f68f2992e74ac28e and cf8a7511ef5b9ab63c62ee8e1357b425af7635cb. U07. Test the actual boundary as well as its small components. NMRPeak's importer needs Docker stdin attached; a direct importer test cannot establish that handoff. Its recording-stack tests also cannot establish real model capacity. Run 002's contained qualification entrypoint with actual mounts/arguments and exercise 128 atoms -> 130 logical tokens -> 136 padded positions in the model. Keep independent tensor/output oracles alongside wiring and reuse tests. Refs: P:repository_checks/checkpoint.py:523; P:tests/unit/test_chf_checkpoint.py:302; P:tests/unit/test_nmrpeak_runner_runtime.py:110. Importer transport correction: f49b1eef5604a46c8d0c256a520ddb274bc02f4d. U08. Make effects and failure states explicit. NMRPeak distinguishes failure before installation, visible output with durability unconfirmed, and installation followed by cleanup failure. Cover effect states at the qualification or provider publication owner actually introduced or changed. Preserve primary causes and report secondary failures without rewriting what already happened. Priority alignment (2026-10-17): 002 defers the standalone prediction CLI and its product result-publication protocol. This rule preserves safe qualification evidence and provider reporting; it does not require creating another publication owner. See 002's dated priority correction and completion criteria for the active scope. Refs: P:repository_checks/checkpoint_release.py:124; P:tests/unit/test_chf_release.py:116; N:tools/artifacts.py:307; N:tests/test_baseline_run.py:226. Existing mechanisms; new caller needs coverage. U09. Keep description, admission and acquisition separate. SECS validates endpoint settings before materialize loads TLS resources. Pass captured bytes to parsers; keep reads, model loading, writes and process launches visible at their coordinating boundary. Group configuration only by real shared responsibility. Existing explicit keyword arguments remain useful; a universal context/settings bag would conceal dependencies. Refs: S:src/secs_inference/provider/config.py:54,84; M:magnet_provider/local_input.py:49; M:magnet_provider/process_config_v1_5.py:43. U10. Use named values where stable data crosses modules. NMRPeak's admitted peaks and model inputs use named records and tuples. Use a few coherent records for 002's cross-module contracts; leave short local tuples alone. Preserve distinctions such as unavailable evidence versus an observed zero. Frozen dataclasses do not freeze nested lists. For private or large payloads, selectively omit contents from repr at their owning type, keeping useful identity. Refs: P:nmrpeak_provider/product_input.py:292; S:secs/src/secs/elucidation/candidates.py:15; S:src/secs_inference/provider/job_input.py:35. U11. Test invariants, forbidden effects and genuine dependency boundaries. NMRPeak varies settings independently to prove which affect identity. Magnet tests fresh imports with heavy dependencies explicitly unavailable and checks installed origins. Use those techniques where 002 promises lightweight input handling. Test that failed admission never starts expensive work. Small recording fakes suffice; no dependency-injection framework is needed. Permission fixtures must establish actual modes despite umask before interpreting rejection behavior. Refs: P:tests/unit/test_provider_config.py:91; M:tests/unit/test_g01_runner_session.py:43; N:tests/test_baseline_run.py:74; S:tests/deployment/test_templates.py:121. U12. Protect literal Make captures against alias shadowing. Magnet uses override for internal captures. N's exported NMRNET_*_INPUT aliases lack it. A contained probe of the recorded checker image, mounting only this Makefile read-only, ran help with the literal argument below. The sentinel was created in disposable container scratch; no shell expression ran on the host. make -f /input/Makefile help 'NMRNET_ARCHIVE_INPUT=$(shell touch /tmp/alias-expanded)' Observation: alias_expansion_observed=yes; process status 0. Image: sha256:9164d380c00bf0e013d44357cafb03d4b1f64570a93105f74ac4b85b66cf1b49. This confirms a current gap in the literal-input guarantee. Fix existing captures and cover command-line internal-alias replacement; apply the rule to future INPUT. Resolution (2026-10-16): all seven aliases now use `override export` while retaining the `origin`/`value` capture, so a command-line alias cannot replace the gate. Public selectors and future `INPUT` are unexported. The contained `test_make_internal_aliases_keep_captured_values_and_public_inputs_stay_unexported` checks the recipe environment for all seven selectors, command-line alias overrides, `INPUT`, sentinel non-execution, and absence of engine calls. The static classifier admits only the exact optional-`override` gate on Makefiles. Current-tree implementation: `Makefile:12-25`, `repository_checks/test_operator_inputs_port.py:127-164`, `repository_checks/quality/silent_defaults/test_shared_scanner.py:34-42`, and `repository_checks/quality/silent_defaults/test_make_origin.py:35-74`. Upstream rationale: Magnet's captured-variable precedent at https://github.com/numpde/magnet-deploy/blob/2d4ee50b0359e71900fce9289ea01f46d0f41249/Makefile#L74-L78 and its origin-gate check at https://github.com/numpde/magnet-deploy/blob/2d4ee50b0359e71900fce9289ea01f46d0f41249/repository_checks/check-g01-release-inputs.sh#L48-L49. Validation: `make test/repository` passed 480 tests in 440.658 seconds on 2026-10-16 using the recorded checker image above; this includes the named regression and committed-source closure checks. Refs: N:Makefile:12; M:Makefile:30. U13. Account for work while consuming it, including failures. SECS charges failed decompression and detects source growth after inspection. For 002, preserve bounded same-buffer reading and test growth as well as an initially oversized file. Existing extraction already bounds expanded bytes. Apply shared budgets if a later input path reads multiple companions; successful byte counts alone do not bound work. Filesystem faults and consumer bugs remain operational failures rather than malformed-input classifications. Refs: S:tests/input/adversarial/test_nmrium_resources.py:96; S:tests/provider/test_source_access.py:16,79,156; N:tools/artifacts.py:373. U14. Preserve explicit authority over cleanup and owned execution. SECS clears descriptor ownership before close because a failed close can already have released the number; retry could close an unrelated reused descriptor. NMRPeak checks marker identity before removal, preserving replacement objects. Use these patterns where handles or shared names are reused; private exclusive scratch may already provide sufficient authority. For 002 cancellation, prove the engine container's identity and termination: our native helper confirms local process retirement only. This is a plan acceptance obligation, not new daemon work. Refs: S:src/secs_inference/provider/attempt_store.py:99; S:tests/provider/test_journal_failures.py:60; P:nmrpeak_provider/provider_readiness.py:56; N:tools/inference_native.sh:2; N:tools/baseline.sh:251. Maintainer directions adopted after log review --------------------------------------------- The maintainer explicitly selected these recurring directions for this note on 2026-10-16. They govern how to apply the practices above. Private log paths and session details remain outside public history; references below are public repository examples, not substitutes for the maintainer's instructions. U15. Preserve requirements by meaning and intent. Do not weaken a check to obtain a passing result. Establish the requirement it protects, retain that obligation, and remove brittle wording assertions, implementation-shaped tests or ceremonial proof requirements when they add no protection. A failing applicable check is a finding to resolve, not an automatic reason to narrow its scope. Adapt precedent only as much as local ownership and long-term maintainability require. Example: explanation-only annotations retain the detector and placement rules without requiring a mechanically resolved test reference. Ref: N:repository_checks/quality/PORTS.md:29. U16. Record precise sources AND the rationale where they support the work. Every borrowed behavior, scientific assumption and consequential decision needs an identifiable source and an explanation of why it applies here. Put that information beside the relevant code, declaration, result or design decision. Identify the repository and exact revision/path/section, or the paper version, release/member identity or retained run that supports the claim. Explain what the source establishes, what was adapted, and what remains unknown or unverified. Record why the evidence was consulted and why the chosen behavior follows from it; a link alone does not preserve the reasoning. For authored notes and results, state who produced them and their purpose. Keep historical evidence bound to its actual producer and execution; later observations must be dated separately. Precise references must remain usable without reconstructing a chat, locating an unspecified sibling HEAD or guessing which experiment was meant. Keep private operational evidence separately and publish only appropriate attributable facts. Examples: this note's pinned source aliases and per-finding rationale; N:artifacts/SOURCES.md:3; P:docs/benchmark.md:71. U17. Explain purpose and actionable behavior in plain language. Lead with what the reader can do, what happened and the next useful action. Use concrete examples when they clarify a claimed benefit. Explain unfamiliar terms and important limits; include implementation detail where it helps the reader decide. Keep failure reasons useful and specific while excluding sensitive material and unnecessary payload dumps. Privacy must preserve useful diagnosis. Refs: M:notes/030_implementer_tendencies_20261013.txt:46; P:notes/006_maximum_error_transparency_20261014.txt:1. U18. Deliver coherent progress and make its status visible. Commit meaningful, reviewed slices with explicit paths: git add -- FILE... and git commit -m MESSAGE -- FILE.... Preserve unrelated changes. Give useful progress updates, remaining work and evidence-based ETA or uncertainty before repeated status questions become necessary. Distinguish implemented, tested, qualified and deployed outcomes. Commit, push, deployment and notification authority remain task-specific; this guidance does not grant new external actions. Example of bounded delivery reporting: N:notes/002_label_free_coordinate_prediction_20261014.txt:1 distinguishes implemented admission/tensor/orchestration work from pending release-model qualification. U19. Preserve reproducibility and development rationale with a clear purpose. Before tidying, identify what each artifact supports, who still needs it and how long it remains useful. Extract durable findings, decisions, rejected alternatives that explain the design, and lessons from logs into concise maintained notes, with precise references and limits. Preserve the underlying observations needed to reproduce or assess a scientific claim; a prose summary cannot replace them. Keep reusable offline inputs at their maintained paths. Keep unreviewed runs, debug captures and temporary helpers under ignored working storage, grouped by purpose. For published claims, select and publish reviewed, privacy-safe evidence with inputs, producer/runtime identities, methods and necessary raw observations. Keep that evidence immutable and distinguish it from the current rerun commands. Use the existing retention policy: inputs while offline use is needed, evidence while its claims are published, and debug captures until resolution or acceptance of reviewed replacement evidence. Remove superseded scratch only after checking that no unique evidence, useful rationale or active workflow depends on it. Retained working storage needs deliberate cleanup too; being ignored does not make an unstructured accumulation useful. This guidance does not authorize a cleanup now or require committing every run, transcript, download or helper. Refs: N:README.md:183; N:notes/012_repository_check_log_findings_20261014.txt:4; P:docs/benchmark.md:57,78. Further practices selected from sibling AGENTS.md files ------------------------------------------------------ U20. Distinguish deterministic generated artifacts from dependency locks. For an actual checked-in generated artifact, provide explicit write and no-write check lanes that render from the same canonical inputs and compare exact output. Update it through its owner; do not hand-edit generated bytes or recorded hashes. A lock captures a reviewed mutable-index snapshot. Its offline checks establish inventory, format and consumer compatibility, not index freshness. Refresh through an explicit acquisition lane and review the complete package-set diff. Do not add empty generator machinery when no corresponding artifact needs it. Refs: I:AGENTS.md:89,176; V:AGENTS.md:39. U21. Require explicit review when a reference implementation version changes. Version-sensitive expected results must identify the exact reference version. If a new version has no qualified fixture set, fail with that fact rather than silently regenerating or redefining expectations. Preserve the earlier reference and qualify the replacement deliberately. Apply this when such a reference is used; sampled agreement cannot establish an exhaustive equality claim. Ref: Q:AGENTS.md:135. This refines U06; it does not add a new dependency to 002. U22. Keep active guidance current and historical records historical. When implementation establishes a different fact, update the active design, instructions, tests and maintained specifications together. Preserve dated observations and explain supersession; do not rewrite an old record to imply that today's behavior was observed then. State unresolved product or scientific questions explicitly instead of filling them with defaults or placeholders. Refs: I:AGENTS.md:60; M:AGENTS.md:44. This complements U16/U19. U23. Carry safe causes to the recipient through the channel they use. Keep failure classification, causal evidence and retry/final disposition distinct: a status or code alone is insufficient when a safe specific cause is known. Add owned context across catches and publication without replacing the established cause with a generic message. Then trace each actual recipient and renderer. A developer may need a phase and source location; an operator/deployer needs the attempt or service effect and a safe recovery action; an analysis commissioner needs to know whether the request was rejected, delayed or failed and what they can change; a receiver needs to know whether a result exists and what its stated limits are. These roles may use different channels and need different detail; terminal stderr is only one possible sink. Keep authorized operational evidence available even when a public/API surface carries only a condition or bounded explanation. Magnet keeps operational unavailability separate from caller rejection and applies retry policy within the Attempt; NMRPeak retains route detail for its operator while sending a progress condition to the API; SECS publishes a bounded Attempt explanation and retains structured cause evidence; the GUI presents an Attempt's failure code and message in the job workspace. These boundaries matter because they determine who must act next, and raw exception text may contain protected scientific input. A retry policy is a disposition, not proof that the underlying cause is transient. At each disclosure boundary, apply the recipient's authorization and privacy rules: remove secrets and scientific or host facts that recipient may not receive, while retaining adjacent safe diagnosis. Check the actual recipient-visible rendering for causal detail, effect state, next action and redaction; a sanitized outer message can still expose private input through a cause or traceback. For consequential ambiguous wording, use independent source review and a context-isolated reader's explanation. Refs: M:magnet_provider/interpreter.py:295,421,443,470; M:magnet_provider/analysis_execution.py:360; M:magnet_provider/attempt_outcome.py:527; M:models/e_01_jvae_nmrexp/provider/magnet_provider_bindings/e_01_jvae_nmrexp/analysis_failure_policy.toml:1; P:nmrpeak_provider/attempt_lifecycle.py:890,933; P:nmrpeak_provider/provider_main.py:235; S:src/secs_inference/provider/execution.py:127; S:src/secs_inference/provider/job_api.py:186; S:src/secs_inference/provider/diagnostics.py:14,66; I:tests/repo-checks/test_error_transparency.py:55,81,87,100; G:app/src/features/workspace/ColumnExecutionAttempt.tsx:44; G:tests/unit/normative/column-workspace.test.tsx:1614,1619; M:AGENTS.md:29; V:AGENTS.md:268. This refines U17/A03. U24. Keep intentionally accepted risks visible and executable. For a concrete limitation deliberately left unfixed, retain a focused test of current behavior and explain its consequence and accepted scope. Keep it active; do not hide stale tests in quarantine or turn a known defect into a desired permanent contract. Revisit the record and test when the behavior changes. Refs: J:AGENTS.md:129,130; V:AGENTS.md:272. No new test taxonomy is required here. U25. Separate routine correctness from costly diagnostics and performance. Keep useful bounded correctness checks in normal discovery. Put expensive exhaustive witnesses and timing assertions in explicit named lanes, while still running them when the claim being qualified needs them. A small default check does not replace exhaustive evidence for an exhaustive claim. Ref: Q:AGENTS.md:129. Reuse existing contained lanes; no new runner is proposed. U26. Structure tests by both scope and behavioral purpose. Added 2026-10-18 following the maintainer's explicit layout direction. Use the established unit/normative and unit/adversarial split, alongside contract, integration and scenarios suites where applicable. Normative tests specify required behavior, including refusal, ordering and atomicity; they are not just happy paths. Adversarial tests challenge boundaries with malformed inputs, tampering, resource exhaustion and interrupted effects. Contract tests check external compatibility; integration tests exercise actual connections between owners. Scenarios tell recognizable multi-step consumer stories, such as a lost publication reply followed by restart and exact reconciliation without repeating analysis. These are complementary distinctions, not a mandatory Cartesian directory tree. Place each test by its primary purpose; do not duplicate assertions across suites or create empty scaffolding. Add normative/adversarial subgroups within other suites when useful. Keep fixture provenance beside its owning suite and share only needed fakes/helpers. Keep repository checks, model-behavior and live/system/e2e qualification visibly separate; a worker scenario does not prove an API/GUI flow. Expose focused hierarchical contained targets for the meaningful suites. Refs: I:tests/unit/{normative,adversarial}/ and I:integration_tests/{normative,adversarial}/; G:tests/unit/{normative,adversarial}/; S:tests/input/README.md, tests/input/{normative,adversarial,scenarios,adapters}/, tests/input/adversarial/test_source_boundaries.py and tests/input/scenarios/test_scientific_jobs.py; M:tests/{unit,contract,integration}/ and Makefile; P:tests/{unit,contract,integration,repository,fakes,live,model_behavior}/ and Makefile. These sources use the exact repository revisions above. Their rationale is to make required behavior, hostile boundary challenges and composed workflow evidence independently discoverable and runnable. Note 017 adopts this structure for the planned provider-core package; this record does not claim implementation or tests have run, and does not require unrelated existing suites to be moved now. U27. Recover from routine disruption without operator intervention. Added 2026-10-22 following the maintainer's explicit requirement for resilience and minimal baby-sitting. A persistent provider should resume useful work after temporary dependency outages without manual restart, record repair or repeated configuration changes. Retry only operations whose semantics permit it, at their existing owner, using configurable capped backoff and request deadlines. Include jitter where independent clients could synchronize. Waiting remains responsive to shutdown; account for retries in the applicable work and resource budgets. A bounded Job budget can end an Attempt without ending the provider service. Classify failure from evidence: an unknown response or HTTP status alone does not prove transience. Preserve uncertain mutations and use contract-authorized exact replay or reconciliation; never repeat scientific work because publication failed. Resume only after required ownership, identity and retirement facts are established. Invalid credentials/configuration, permanent rejection and unresolved effects need distinct dispositions, safe diagnosis and escalation when automatic recovery is not justified. Report delay, recovery and any required operator action through the supported recipient channels; retrying must not erase the underlying cause. Normal successful throughput must not require repeatedly raising history limits or replacing installation roots. State the intended unattended operating envelope and give finite history, disk and allocation resources an owned retention, rotation or renewal policy that preserves unresolved obligations and required evidence. Hard limits still stop unsafe admission; merely increasing a limit or documenting the stop does not establish unattended operation. Assess a recognizable outage-and-recovery sequence and sustained ordinary use: work resumes without duplicate scientific effects or manual repair, shutdown stays bounded, and irrecoverable cases explain who must act. Reuse focused existing scenarios; no mandatory new harness, exhaustive fault matrix or live-model rerun. Sources: maintainer direction, 2026-10-22; S at 7356c354368f2355d3ab5cef00cf48c67cea9c2c, src/secs_inference/provider/runtime.py::run_execution demonstrates capped outage backoff and retained pending state. U08/U13/U14 constrain effects, budgets and ownership; U23 governs recipient reporting. The unattended envelope and resource renewal requirement are local product requirements, not claims about SECS behavior. 2026-10-23 refinement, jointly reviewed with the Magnet owner at the maintainer's request: an explicitly pure native computation can have ONE bounded replacement execution within the same Attempt after complete retirement of the original allocation. Preserve scientific request bytes/model selection and use a new worker-local token; do not re-enter interpretation, coordinate generation or API publication. Generic worker failure may include admission/protocol refusal; the native operation owner must distinguish actual entered-computation failure from those exclusions. Caller cancellation, result assembly and failed API publication do not permit this retry. First/later faults belong to the existing protected recipient diagnostics, including when recovery succeeds. Do not append an unreserved traceback graph after expensive science or add another journal. EOF is response uncertainty, not an OOM diagnosis. A synthetic kernel-OOM proof needs actual cgroup/reap evidence plus retirement and unchanged-input witnesses; it is not model-capacity, GPU or numerical-equivalence qualification. Refs: Magnet9374f1a79a5b689bfb41a9da771a536006831538, notes/033_bounded_generation_recovery_20261022.txt, sections Contract, Retirement authority, Portable recovery rules and diagnostic follow-up; NMRNet8c3206e4ae015c86fc60fb836988356e79deb497, nmrnet_provider/session.py::_predict/_replace_prediction/retire; NMRNetde09db7be2f29c2c6e99897ead3db95634ebfe12, tools/prediction_recovery_qualification.sh and tests/integration/provider_worker/prediction_recovery_probe.py. Note017 records the actual local synthetic proof and its private evidence hashes. Avoid ===== A01. Do not equate a healthy process, successful invocation or receipt with scientific qualification or public-workflow completion. Keep tensor equivalence, historical output overlap, complete output coverage, chemical accuracy and speed as separately evidenced claims. Synthetic coverage cases prove their declared coverage, not numerical truth. Preserve failed optimization results as failed. Refs: M:notes/030_implementer_tendencies_20261013.txt:30; S:tests/input/README.md:139; S:qualification/tensorrt-diagnostic/20260830T230605Z-UNcoNd6B/nonqualifying-probe-report.json:839. A02. Do not tune a tolerance to the observed failure, copy an unrelated allowance, or relax atom/token/index identity with a floating-point tolerance. Qualify actual constructed and reloaded state: SECS explicitly checks FAISS storage metric as well as the requested metric. Different storage, parameter, compute and output precisions are separate facts. Planned scientific discipline in 002 already. Refs: S:tools/build_candidate_index.py:89; S:tools/qualify_candidate_index.py:572; S:src/secs_inference/model.py:118; M:models/g_01_nmr_forward/magnet/stairway/g_01_nmr_forward/data/molecules.py:102. A03. Do not erase useful rejection reasons for privacy or let oversized reasons turn normal rejection into execution failure. Retain bounded actionable facts without whole-input dumps. Never translate every ValueError into user error. Ref: M:notes/030_implementer_tendencies_20261013.txt:88; S:tests/provider/test_source_access.py:79,156. A04. Do not trust hashes to establish closure completeness. E02 once omitted an imported state_dict.py from its authenticated projection. Admit exact inventories, then construct and execute from the actual granted files without incidental workspace imports. Fix unnecessary training imports at their owner instead of copying an expanding support tree. Upstream edits still require discussion. Refs: M:models/e_02_ch_nmrexp/magnet/stairway/e_02_ch_nmrexp/model/model.py:35; M:notes/003_e01_runner_closure_audit_20260713.txt:78. Closure correction: e19853ce68f6e459b068ed14c23f14aac5af7fc5. The import simplification is documented in the referenced closure-audit note. A05. Do not add parallel caches, launchers, schemas, proof registries or compatibility paths merely because a sibling has them. Our verified wheelhouse and offline build already meet the cache requirement. Add a protocol only for real substitute implementations; preserve obsolete inputs only for a demonstrated external need. Explanation-only repo-check annotations should remain explanation-only. Refs: N:tools/wheelhouse.py:100; N:containers/inference/Dockerfile:15; S:secs/src/secs/elucidation/candidates.py:39; P:nmrpeak_provider/provider_config.py:164; M:notes/030_g01_departures_from_peer_deployments_20261012.txt:362; N:repository_checks/quality/PORTS.md:29. A06. Do not universalize another model's input or output semantics. G01 projects hydrogens and emits result-local atom maps; 002 preserves supplied atoms/indices. G01 rejects an explicitly requested absent nucleus; 002 skips its model entirely. G01's J candidates have no identified coupling partners and its count probabilities are uncalibrated. Name outputs by what the model supplies, not a stronger claim. Refs: M:models/g_01_nmr_forward/magnet/stairway/g_01_nmr_forward/predict.py:43,201; N:notes/002_label_free_coordinate_prediction_20261014.txt:112,132. A07. Do not imply that coordinate input supplies every chemical feature. In the selected NMRNet path, atom tokens and pairwise distances drive the encoder; direct coordinates feed an auxiliary reconstruction branch that prediction bypasses. Our baseline disables atom descriptors. Equal token/distance tensors therefore drive the same prediction computation, including reflected configurations with identical distance tensors. This is source-level reasoning, not a rerun proving rotation/reflection invariance or broad stereochemical performance. Refs: N:NMRNetplusplus/uninmr/models/unimat.py:223; N:tools/baseline_model.py:24. A08. Do not infer units from plausible magnitudes or treat a conversion convention as established scientific referencing. SECS explicitly distinguishes bare Hz/MHz conversion from supplied shift-reference metadata. Close 002's producer-to-release coordinate-unit gate before external-input qualification; parity alone cannot. Refs: S:src/secs_inference/spectra/jcamp.py:311; N:notes/002_label_free_coordinate_prediction_20261014.txt:272-286. A09. Do not confuse lightweight admission tests with real capacity. NMRPeak's test admits 511 tokenizer tokens; its wrapper adds special tokens/padding while the upstream constructor sets 256 positional embeddings. This is a source-visible inconsistency, not a reproduced runtime defect. It motivates U07's real maximum case rather than importing that limit or claiming all sibling tests are weak. Refs: P:tests/unit/test_hf_runtime.py:27; P:families/nmrpeak/runner_runtime.py:118; P:nmrpeak-upstream/nmrpeak/models/spec_trans_mol.py:44,111. A10. Do not use preservation as a reason to retain repository clutter or obsolete runtime structure. Keep enduring rationale in the owning code or a maintained note, and keep scientific evidence in an identified reviewed bundle. Avoid duplicated summaries, abandoned helper entrypoints and raw session dumps in the maintained tree. Retire obsolete operational trees after extracting useful knowledge instead of keeping them solely as historical evidence. Preserve useful knowledge before deletion; do not remove the only supporting observations merely because a summary or a new successful run exists. Refs: U16/U19; N:README.md:183; P:docs/benchmark.md:93. A11. Do not substitute safe stopping or transparent reporting for resilience. Conservative refusal protects effect truth but does not by itself satisfy a persistent service's availability requirement. Avoid process-fatal handling of routine recoverable outages, blind whole-workflow retries, automatic science reruns after lost API/publication replies, and infinite busy retry loops. U27's explicitly pure native replacement is a separate operation-owned contract. Do not make manual restart, record deletion, limit increases or fresh installation roots the normal throughput mechanism. A documented limitation remains a gap against U27 until resolved or explicitly accepted for the stated operating envelope. This does not authorize weakening admission, deleting obligations, hiding errors or adding a parallel supervisor/recovery framework. Reuse the existing operation and resource owners. Source: maintainer direction, 2026-10-22; U27, U08/U14/U23 and A05. Not applicable to the current slice =================================== X01. Persistent provider protocols, terminal journals, deployment readiness and replay reconciliation. Preserve the lessons for a future provider: ambiguous delivery cannot be replayed casually; complete invalid replies differ from lost replies; event batches have no chronology and need explicit outcome precedence. Do not install those frameworks in the offline one-shot adapter. Refs: M:notes/030_g01_departures_from_peer_deployments_20261012.txt:118; P:nmrpeak_provider/owner_session_supervisor.py:94; P:tests/unit/test_owner_session_supervisor.py:54. X02. Concurrent request admission, stochastic sampling and daemon scheduling. A single-worker executor still queues requests; Magnet rejects concurrent admission explicitly. RNG restoration is not concurrent isolation. 002 is sequential CPU evaluation with no random cropping, so it needs neither queue nor seed framework. Its resource ceilings are per invocation; simultaneous commands multiply them. Refs: M:magnet_provider/runner_session.py:157; M:models/e_01_jvae_nmrexp/magnet/stairway/e_01_jvae_nmrexp/inference.py:722; M:notes/030_g01_departures_from_peer_deployments_20261012.txt:299. X03. Persistent capacity reservation and recovery markers. NMRPeak budgets future record growth and temporary old/new coexistence before admitting new obligations. Use this if a bounded durable queue appears. Free-space checks do not physically reserve space, and the one-replacement allowance assumes serialized writes. Do not add journal machinery for a fresh one-shot result directory or generic recovery that deletes unrecognized residue. Preserve failed attempts. Refs: P:nmrpeak_provider/attempt_journal_store.py:510; P:tests/unit/test_attempt_journal_store.py:88; P:docker/checkpoint_volume.py:25. X04. Additional network/HTTP infrastructure. Per-read timeouts may permit endless trickle progress; SECS bounds the whole exchange and joins its interrupter before socket reuse. NMRPeak addresses the underlying stream when a wrapper's closed flag does not establish release. Our proxy already uses an absolute header budget. Apply such fixes only at an actual owned transport boundary; offline prediction does not need a transport or an invented scientific deadline. Refs: S:src/secs_inference/provider/socket_deadline.py:14; S:tests/provider/test_http.py:251; P:nmrpeak_provider/http_response.py:14; P:tests/unit/test_openai_chat_interpreter.py:634; N:tools/bound_http_proxy.py:70. X05. SMILES, conformers, RDKit, candidate retrieval and optimization. SECS retrieves neighbours before formula filtering, so no candidates does not mean chemical impossibility. NMRPeak's native-library closure also requires actual final-image use proof beyond wheel resolution. Revisit these when those capabilities enter scope. If real fixture bytes are redistributed, establish their own provenance and notices; software licensing and hashes do not establish data licensing. Scope update, 2026-10-18: 003 now explicitly requires SMILES + N conformers and multi-format supplied geometries. RDKit preparation, final-image use and fixture provenance guidance therefore apply to 003; this entry's earlier deferral is historical. Candidate retrieval and force-field optimization remain outside scope. Refs: S:secs/src/secs/elucidation/candidates.py:120; P:models/nmrpeak_chf_v1/runner/Dockerfile.runner:10; S:tests/fixtures/bruker/cheminfo/README.md:36; N:artifacts/SOURCES.md:15. X06. Ensembles, GPU/reduced precision and performance campaigns. G01's measured CPU advantage does not select a device for another model. Compare actual intended workloads, separate software/hardware changes, synchronize accelerator timing, and keep numerical/scientific acceptance independent of speed. Table 2 ensemble accuracy remains distinct from 002's fold-0 CPU computation qualification. Refs: M:notes/032_runner_device_comparison_20261015.txt:4,35; P:docs/benchmark.md:125; N:notes/002_label_free_coordinate_prediction_20261014.txt:20. X07. Repository-specific AGENTS.md conventions remain local. Magnet's Python test examples, detached training, external coordination and stage-local output policy do not authorize changes to this contained adapter's workflow. Grimace's domain-specific ban on oracle names and its default output-commit restriction do not replace U06/U19's qualification terminology and selected-evidence policy. Agent Mail's edit delegation, test taxonomy and empty generated-target conventions do not replace this task's workflow or create absent capabilities. Preserve the general lessons without copying those implementations or granting external actions. Refs: R:AGENTS.md:91,98,137,148; Q:AGENTS.md:76,180; J:AGENTS.md:49,62,120. Immediate disposition --------------------- U12 is resolved in the current tree and independently reviewed. For remaining 002 work, retain exact verification/consumption (U05), portable evidence, oracle producer and exact populations (U06), maximum capacity and owned-container termination (U07/U14). Apply U08 to actual qualification evidence and later provider publication, as scoped in 002's priority correction of 2026-10-17; standalone prediction CLI/publication work is deferred. Other Use items guide implementation and do not require retrofitting every existing type or test. CI remains deferred.