@nimiplatform/nimi-coding 0.3.0 → 0.4.0

package/spec/authority-audit.yaml

@@ -0,0 +1,85 @@
+version: 1
+spec:
+  id: nimicoding.authority-audit.v1
+  owner: nimi-coding
+  status: active
+product_claim: complete_admitted_snapshot_and_explicit_project_binding_produce_deterministic_governance_bound_observations_findings_and_gaps
+runtime:
+  function: auditAuthorityPath(authorityPath_bindingsPath_budgets)
+  source: one_complete_package_private_AuthorityIR_SourceMap_and_one_closed_binding_document
+binding:
+  format: nimicoding.authority-verifier-bindings/v1
+  authority: package://@nimiplatform/nimi-coding/contracts/authority-verifier-bindings.schema.yaml
+  top_level_fields: [format, required_bindings, bindings]
+  required_bindings: non_empty_so_an_accidentally_emptied_CI_policy_is_refused
+  binding_fields: [id, detector, premise, targets, minimum, policy]
+  missing_required_binding: completed_gap
+  malformed_unknown_detector_or_invalid_authority_ref: refused_with_null_audit
+  tracked_project_governance: required_before_portable_blocking_adoption_but_not_inferred_or_verified_by_runtime
+detector:
+  id: minimum-independent-incoming-reference/v1
+  premise: exact_active_rule_selected_by_binding
+  targets: non_empty_unique_exact_active_definitions_selected_by_binding
+  attachment: premise_must_have_direct_applies_to_each_target
+  measurement: distinct_other_active_rule_sources_with_direct_applies_to_target
+  minimum: positive_safe_integer_from_binding
+  prose_ID_pattern_owner_scope_inference: forbidden
+  project_semantics: owner_admitted_governance_verifier_not_package_universal_invariant
+result:
+  format: nimicoding.authority-audit/v1
+  top_level_fields: [format, operationStatus, policyStatus, complete, observations, findings, gaps, counts, budgets]
+  operation_status: [completed]
+  policy_status:
+    blocked: at_least_one_blocking_finding
+    indeterminate: no_blocking_finding_and_at_least_one_required_binding_gap
+    passed: no_blocking_finding_or_gap
+  complete: false_only_when_required_binding_gap_exists
+  common_item_fields: [code, fingerprint, detector, binding, premise, basis, message, policy, authorityRefs, primaryLocation, relatedLocations, witness]
+  location_fields: [file, range, sourcePointer]
+  related_location_fields: [role, location]
+  basis:
+    governance_bound: configured_detector_observation_or_finding
+    required_coverage: required_binding_declaration_without_configured_detector_execution
+  required_binding_gap_fields:
+    detector: null
+    premise: null
+    basis: required_coverage
+    policy: required
+  observation: exactly_one_governance_bound_structural_observation_per_evaluated_binding
+  findings:
+    - premise_target_direct_attachment_missing
+    - minimum_independent_incoming_reference_not_met
+  finding_additional_fields: [target]
+  ordering:
+    observations: binding_ID
+    findings: [binding_ID, target_ID, code]
+    gaps: binding_ID
+  fingerprint:
+    algorithm: SHA-256_with_sha256_colon_prefix
+    inputs: [fingerprint_format, code, detector_when_present, binding_ID, premise_ID_when_present, target_ID_when_present, minimum_when_present]
+    excluded: [file, range, sourcePointer, policy, message, corpus_digest, run_identity]
+  counts:
+    fields: [bindings, returned, traversal]
+    binding_fields: [required, configured, evaluated]
+    returned_fields: [observations, findings, gaps]
+    traversal_fields: [units, edges]
+budgets:
+  required: [maxUnits, maxEdges, maxBytes]
+  values: positive_safe_integers
+  units_and_edges: complete_distinct_inspected_set_including_all_premise_outgoing_and_target_incoming_candidates_before_eligibility_filtering
+  bytes: UTF-8_bytes_of_compact_JSON.stringify_audit
+  overflow: AUTH_AUDIT_BUDGET_with_null_audit_and_partial_false
+outcomes:
+  completed: audit_present_even_when_blocked_or_gap_exists
+  refused: invalid_corpus_binding_authority_reference_or_budget_with_null_audit
+  partial: forbidden
+boundaries:
+  writes_authority: false
+  binding_is_canonical_product_authority: false
+  canonical_rule_ref_proves_predicate_equivalence: false
+  detector_plugin_DSL_exception_filter_or_dynamic_execution: forbidden
+  Git_tracking_CI_SARIF_UI_AI_host_or_remediation: not_owned_by_runtime
+  public_JS_exports: none
+summary:
+  result_unitCount: full_compiled_corpus_units
+  proof_traversal_counts: audit.counts.traversal

package/spec/authority-authoring.yaml

@@ -0,0 +1,150 @@
+version: 1
+spec:
+  id: nimicoding.authority-authoring.v2
+  owner: nimi-coding
+  status: active
+product_claim: installed_package_deterministically_formats_checks_and_compiles_canonical_authority
+source_authority: downstream_project_.nimi/spec_containing_only_canonical_authority_profiles
+profiles:
+  file_suffixes: [.authority.yaml, .authority.md]
+  yaml:
+    document: closed_top_level_mapping_with_exact_format_and_non_empty_units_sequence_using_YAML_1.2_core_values
+    container_fields: [format, owner, scope, units]
+    container_defaults:
+      owner: applies_to_every_unit_that_omits_owner
+      scope: one_scope_value_applied_to_every_active_rule_that_omits_scope
+      definitions_do_not_inherit_scope: true
+    unit_omission_defaults:
+      lifecycle: active
+      relations: []
+    both_levels_absent: fail_closed_no_inference
+    units_per_file: 1_to_N
+    unit_identity: explicit_ID_independent_of_file_name_source_index_move_order_or_regroup
+    source_order: preserved_for_author_reading_but_non_semantic
+    formatter_inputs: [block_collections, syntax_clear_flow_collections, syntax_clear_block_scalars]
+    rejected: [legacy_top_level_single_unit_mapping, empty_units, invalid_utf8, duplicate_keys, aliases, anchors, merge_keys, explicit_tags, directives, complex_keys, comments]
+  markdown:
+    units_per_file: 1
+    shared_with_yaml: restricted_lexical_and_syntax_rules_only_not_document_fields
+    front_matter_fields: [format, id, kind, owner, lifecycle, modality, scope, relations]
+    forbidden_front_matter_fields: [units]
+    title: one_plain_level_one_line_required_for_admission_but_omittable_during_fmt
+    active_definition_sections: [Meaning]
+    active_rule_sections: [Statement, Condition, Failure]
+    removed_sections: [Removal reason]
+    section_body: exactly_one_plain_text_line
+    rejected: [extra_or_duplicate_headings, prose_outside_slots, lists, blockquotes, thematic_breaks, fences, html, links, references, emphasis, comments, trailing_content]
+fields:
+  yaml_document_required: [format, units]
+  yaml_document_optional: [owner, scope]
+  unit_common_required: [id, kind, title]
+  unit_common_resolved_from_container_or_unit: [owner, lifecycle, relations]
+  markdown_frontmatter_also_requires: [format]
+  format: nimicoding.authority/v2
+  migration_inputs:
+    format: nimicoding.authority/v1
+    admitted_by: [fmt --upgrade, check, compile, diff, impact]
+    rationale: history_snapshots_and_migration_inputs_are_read_not_authored
+    compatibility_authoring_surface: none
+  identifier: dot_separated_lowercase_segments_start_and_end_alphanumeric
+  kinds: [rule, definition]
+  lifecycles: [active, removed]
+  active_definition:
+    required: [meaning]
+    forbidden: [modality, scope, statement, condition, failure, reason]
+  active_rule:
+    required: [modality, scope, statement, condition, failure]
+    modalities: [must, must_not]
+    forbidden: [meaning, reason]
+  removed:
+    required: [reason]
+    forbidden: [meaning, modality, scope, statement, condition, failure]
+text_values:
+  fields: [title, meaning, statement, condition, failure, reason]
+  unicode: non_empty_trimmed_well_formed_scalar_sequence
+  forbidden_line_break_code_points: [U+000A, U+000B, U+000C, U+000D, U+0085, U+2028, U+2029]
+  yaml_escaped_values: validated_after_parse_by_check_and_compile
+  fmt_semantics: value_preserving_and_not_evaluated
+field_classes:
+  normative_governance: [id, kind, owner, lifecycle]
+  normative_definition: [meaning]
+  normative_rule: [modality, scope, statement, condition, failure]
+  normative_graph: [relations, type, target]
+  non_normative_metadata: [title, reason]
+relations:
+  container: may_be_missing_only_during_draft_formatting
+  item_shape: exactly_non_empty_string_type_and_target
+  formatting: deterministic_type_then_target_sort_preserving_duplicates_and_unknown_string_types
+  applies_to: active_rule_to_active_definition_at_least_one_per_active_rule
+  supersedes: active_or_removed_to_removed_same_kind_max_one_incoming_and_outgoing_acyclic
+  semantic_failures: [unknown_type, duplicate_edge, self_edge, dangling_target, type_mismatch, cardinality, cycle]
+commands:
+  fmt:
+    syntax: nimicoding authority fmt <file> [--check] [--upgrade] [--json]
+    semantic_status: not_evaluated
+    writes: one_source_file_atomically_unless_check
+    structural_discriminants: [format, kind, lifecycle]
+    invention: forbidden
+    upgrade:
+      admits: nimicoding.authority/v1
+      emits: nimicoding.authority/v2
+      lifting: uniform_container_owner_and_single_valued_scope_plus_omission_of_defaulted_unit_fields
+      semantic_change: none_the_compiled_IR_is_identical_before_and_after
+  check:
+    syntax: nimicoding authority check <path> [--scope-bindings <file>] [--require-format <format>] [--json]
+    writes: none
+    no_scope_bindings_flag: exact_existing_check_behavior
+    require_format:
+      admitted_values: [nimicoding.authority/v2, nimicoding.authority/v1]
+      enforcement: every_container_must_declare_the_exact_requested_format
+      default: absent_preserves_history_and_migration_compatibility
+    scope_bindings:
+      format: nimicoding.scope-bindings/v1
+      document: closed_mapping_with_exact_format_and_non_empty_scopes_sequence
+      scope_entry: closed_mapping_with_one_non_empty_single_line_scope_and_non_empty_bindings_sequence
+      binding_entry: closed_mapping_with_kind_and_non_empty_single_line_value
+      binding_kinds: [path_glob, module, command]
+      duplicate_scope: rejected
+      enforcement: exact_bidirectional_set_equality_between_registered_scopes_and_active_rule_scope_use
+      unregistered_use_diagnostic: every_scope_and_using_unit_ID
+      dead_registration_diagnostic: every_registered_scope_without_active_rule_use
+      repository_path_resolution: forbidden
+      partial_result: forbidden
+  compile:
+    syntax: nimicoding authority compile <path> [--json]
+    writes: none
+    ir_visibility: package_private
+    public_json: operation_counts_and_diagnostics_only
+  anchors:
+    syntax: nimicoding authority anchors <repository-path> --spec <corpus-path> [--scope-bindings <file>] [--embedded-paths] --max-units <positive-safe-integer> --max-anchors <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]
+    writes_and_execution: none
+    active_fields: [meaning, statement, condition, failure]
+    grammar: closed_maximal_non_whitespace_path_and_pnpm_script_tokens_defined_by_nimicoding.authority-anchors.v1
+    resolution: exact_Git_tracked_file_or_root_package_script_membership_without_inference
+    scope_path_globs: every_path_glob_matches_at_least_one_Git_tracked_file
+    module_and_command_bindings: structurally_admitted_but_not_resolved
+    budgets: complete_active_units_anchor_occurrences_and_compact_UTF-8_product_bytes
+    partial_result: forbidden
+compiler:
+  ordering: [unit_id, scope_lexical, relation_type_then_target]
+  output: [AuthorityIR, SourceMap]
+  source_map: every_AuthorityIR_leaf_uses_its_actual_IR_JSON_pointer_and_exact_source_file_range_and_YAML_source_pointer_under_/units/source_index
+  non_ir_source_entries: forbidden
+  partial_success: forbidden
+diagnostics:
+  range: one_based_unicode_scalar_half_open
+  missing_field: canonical_insertion_point_in_containing_mapping_or_section
+  conflicts: primary_location_plus_sorted_related_locations
+  repair: decision_category_only_never_product_semantic_value
+runtime_authority:
+  contracts: installed_package_only
+  downstream_projection_cannot_change_compiler: true
+  historical_document_compatibility_or_inference: forbidden
+  sole_downstream_conformance_gate: authority_check_on_complete_canonical_root
+admitted_downstream_consumers: [bounded_lexical_candidate_discovery, exact_query, bounded_context, bounded_graph_navigation, static_lexical_anchor_validation, embedded_repository_path_anchor_validation, corpus_consumer_and_gate_wiring_report, corpus_term_index_and_code_cross_reference, closed_vocabulary_pairing_report, project_bound_deterministic_audit, SARIF_projection, semantic_diff, declared_impact]
+report_product_contracts:
+  consumers: nimicoding.authority-consumers.v1
+  terms: nimicoding.authority-terms.v1
+  closed-sets: nimicoding.authority-closed-sets.v1
+  anchors: nimicoding.authority-anchors.v1
+not_admitted: [historical_format_reconstruction, profile_specific_validation, multi_unit_markdown, sqlite, cache, incremental, semantic_search, embedding, visualization, ai_execution, Atlas, qualification, final_cutover]

package/spec/authority-closed-sets.yaml

@@ -0,0 +1,65 @@
+version: 1
+spec:
+  id: nimicoding.authority-closed-sets.v1
+  owner: nimi-coding
+  status: active
+product_claim: bounded_static_pairing_of_closed_vocabularies_stated_in_active_authority_text_against_proto_enums_and_plain_scalar_sequences_in_tracked_YAML_implementation_sources
+command: nimicoding authority closed-sets <repository-path> --spec <corpus-path> --max-units <positive-safe-integer> --max-sets <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]
+surface:
+  report_format: nimicoding.authority-closed-sets/v1
+  corpus_root: repository_authority_corpus_only
+  boolean_flags: [json]
+  value_flags: [spec]
+  integer_flags: [max-units, max-sets, max-bytes]
+  repeatable_flags: []
+  findings_change_exit_code: false
+inputs:
+  repository:
+    shape: exact_non_symlink_Git_worktree_root
+    tracked_files: one_complete_git_ls_files_cached_NUL_inventory
+    writes_or_execution: forbidden
+  corpus:
+    root: exact_repository_relative_.nimi/spec_resolved_realpath
+    units: active_only
+    fields:
+      shared_lexicon: normative_field_set_is_one_shared_definition_across_report_products
+      scanned: [meaning, statement, condition, failure]
+      rationale: a_rule_states_its_closed_vocabulary_in_the_condition_or_failure_as_often_as_in_the_statement
+canonical_extraction:
+  shape: comma_run_enumeration_with_optional_and_or_tail
+  minimum_members: 3
+  minimum_commas: 1
+  rejected: multi_word_items_and_runs_continuing_into_prose
+implementation_extraction:
+  proto_enums:
+    scope: all_tracked_.proto_files
+    values: value_names_with_their_longest_underscore_boundary_prefix_stripped
+  config_yaml_sequences:
+    scope: all_tracked_.yaml_and_.yml_files_excluding_the_authority_corpus
+    values: at_least_three_plain_scalar_tokens
+inventory:
+  shape: implementation_kind_inventory_v1
+  tracked_files: complete_git_inventory_count
+  scanned_files: counts_by_proto_and_yaml_kind
+  exclusions:
+    every_excluded_file_reported: true
+    reasons: [authority-corpus, binary-content, not-utf8, not-a-scanned-kind]
+  accounting: tracked_files_equals_proto_scanned_plus_yaml_scanned_plus_excluded_files
+pairing:
+  basis: member_overlap_inference_with_no_supplied_mapping
+  suppressed: pairs_whose_canonical_group_is_a_pure_subset_of_another_pair_for_the_same_set
+  unpaired: reported_as_a_first_class_inventory_never_as_silence
+budgets:
+  max_units: complete_active_unit_set_must_fit
+  max_sets: complete_implementation_set_inventory_must_fit
+  max_bytes: inputBytes_complete_decoded_authority_and_implementation_input_must_fit
+  exceeded: refuse_with_one_diagnostic_and_no_partial_inventory_or_pairing
+result:
+  trackedPathSetDigest: sha256_hex_of_nimicoding.repository-inventory/v1_canonical_tracked_path_set_preimage
+  complete: true_only_when_every_admitted_input_was_read_and_paired
+  byte_counts:
+    scannedBytes: normative_authority_fields_plus_decoded_proto_and_YAML_extractor_inputs
+    inputBytes: complete_decoded_authority_corpus_plus_decoded_proto_and_YAML_extractor_inputs
+  partial: never
+  findings_change_exit_code: false
+  determinism: identical_inputs_produce_byte_identical_output

package/spec/authority-consumers.yaml

@@ -0,0 +1,70 @@
+version: 1
+spec:
+  id: nimicoding.authority-consumers.v1
+  owner: nimi-coding
+  status: active
+product_claim: bounded_static_report_of_which_tracked_files_reference_the_repository_authority_corpus_and_which_package_script_gates_any_workflow_can_reach
+command: nimicoding authority consumers <repository-path> --spec <corpus-path> [--external-root <scheme>=<path>]... --max-files <positive-safe-integer> --max-refs <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]
+surface:
+  report_format: nimicoding.authority-consumers/v1
+  corpus_root: repository_authority_corpus_only
+  boolean_flags: [json]
+  value_flags: [spec]
+  integer_flags: [max-files, max-refs, max-bytes]
+  repeatable_flags: [external-root]
+  findings_change_exit_code: false
+inputs:
+  repository:
+    shape: exact_non_symlink_Git_worktree_root
+    tracked_files: one_complete_git_ls_files_cached_NUL_inventory
+    scan_selection: every_tracked_non_corpus_file_classified_by_NUL_and_fresh_UTF-8_probe_regardless_of_extension_plus_root_package.json
+    exclusions: every_authority_corpus_binary_content_and_non_UTF-8_file_named_with_reason_in_fileInventory
+    writes_or_execution: forbidden
+  corpus:
+    root: exact_repository_relative_.nimi/spec_resolved_realpath
+    rationale: a_fixture_directory_must_not_be_able_to_stand_in_as_the_canonical_corpus
+  external_roots:
+    shape: repeatable_<scheme>=<path>_with_lowercase_scheme_and_one_directory
+    scheme_knowledge: none_this_tool_knows_no_particular_project_scheme
+    absent_scheme: reference_is_externalUnresolved_never_dead
+reference_grammar:
+  local_literal:
+    shape: .nimi<separator_run>spec_optionally_followed_by_further_segments
+    separators: forward_or_back_slash_runs_because_source_literals_escape_backslashes
+    bare_root_admitted: true
+    excluded: glob_star_or_angle_bracket_placeholder
+  local_constructor:
+    shape: adjacent_string_literals_beginning_with_.nimi_then_spec
+    reconstruction: only_while_every_further_segment_is_a_string_literal
+    non_literal_continuation: reported_as_unresolved_never_dropped
+  external:
+    shape: <scheme>:spec/<path>[#<unit-id>]
+    unit_id: dotted_lowercase_authority_identifier
+    canonical_path: dot_and_dot-dot_segments_forbidden_and_realpath_must_remain_within_the_declared_root
+    fragment_resolution: when_a_scheme_root_is_supplied_the_named_YAML_container_must_hold_a_unit_with_the_exact_fragment_ID
+    non_canonical_path: unresolved_with_reason_non-canonical-external-path
+classification:
+  canonical: local_target_exists_in_the_tracked_inventory
+  canonicalDead: local_target_absent_from_the_tracked_inventory
+  externalAuthority: scheme_root_supplied_and_file_exists_and_any_supplied_fragment_names_a_unit_in_that_container
+  externalDead: scheme_root_supplied_and_file_is_absent_or_any_supplied_fragment_is_absent_with_fragment_named_in_the_report_row
+  externalUnresolved: no_root_supplied_for_the_scheme
+  unresolved: path_constructed_from_a_non_literal_segment
+  host_specific_exemptions: forbidden_historical_identity_strings_stay_visible_for_the_host_to_interpret
+gate_wiring:
+  workflow_files: .github/workflows/*.yml_and_*.yaml
+  reachability: direct_workflow_mention_or_transitive_package_script_reference
+  orphan: no_workflow_and_no_referencing_script_and_not_a_lifecycle_script
+budgets:
+  max_files: complete_scanned_file_set_must_fit
+  max_refs: complete_reference_set_including_unresolved_must_fit_and_the_refusal_names_that_compared_total
+  max_bytes: complete_decoded_input_must_fit
+  exceeded: refuse_with_one_diagnostic_and_no_partial_report
+result:
+  trackedPathSetDigest: sha256_hex_of_nimicoding.repository-inventory/v1_canonical_tracked_path_set_preimage
+  complete: true_only_when_every_admitted_input_was_read_and_classified
+  partial: never
+  counts: [total, canonical, canonicalDead, externalAuthority, externalDead, externalUnresolved, unresolved]
+  file_inventory: tracked_text_inventory_v1
+  findings_change_exit_code: false
+  determinism: identical_inputs_produce_byte_identical_output

package/spec/authority-context.yaml

@@ -0,0 +1,50 @@
+version: 1
+spec:
+  id: nimicoding.authority-context.v1
+  owner: nimi-coding
+  status: active
+product_claim: exact_ID_returns_one_unit_or_complete_bounded_declared_outgoing_interpretation_closure_or_fails
+source: admitted_package_private_AuthorityIR_and_SourceMap_only
+commands:
+  query:
+    syntax: nimicoding authority query <path> <id> --max-bytes <positive-integer> [--json]
+    result: exactly_one_unit_packet
+    budget: explicit_UTF-8_packet_bytes_required
+  context:
+    syntax: nimicoding authority context <path> <id> --max-units <positive-integer> --max-bytes <positive-integer> [--json]
+    budget: explicit_unit_and_UTF-8_packet_bytes_required
+packet:
+  format: nimicoding.authority-context/v1
+  fields: [root, closure, units, sourceMap]
+  unit_order: lexical_ID
+  source_paths: relative_to_input_root_when_inside_it
+  schemas_included: false
+  unrelated_units_outside_closure_included: false
+  corpus_note: A legitimate closure may coincidentally include every corpus unit; no unit outside the closure is attached.
+  task_context: not_claimed
+closure:
+  direction: outgoing_recursive
+  relation_categories: [applies_to, supersedes]
+  rationale:
+    applies_to: Include definitions explicitly required to interpret a rule.
+    supersedes: Include the declared older lineage required to interpret lifecycle relations.
+  incoming_relations: excluded_as_unrelated_to_the_root_declared_dependencies
+fail_closed:
+  unknown_exact_ID: AUTH_QUERY_NOT_FOUND
+  ambiguous_ID: compiler_identity_diagnostic
+  invalid_source_or_graph: compiler_diagnostic
+  unit_or_UTF-8_packet_byte_budget_overflow: AUTH_CONTEXT_BUDGET_without_packet
+  partial_packet: forbidden
+determinism:
+  repeated_semantic_output: identical
+  packet_units: lexical_ID
+  canonical_packet_bytes: UTF-8_byte_length_of_compact_JSON.stringify_packet_without_trailing_newline
+  tokenizer_dependency: forbidden
+  source_map: every_packet_unit_leaf_traceable
+boundaries:
+  writes_authority: false
+  durable_artifacts: none
+  exposes_AuthorityIR_as_package_export: false
+  reads_projected_contracts: false
+  complete_task_context: not_admitted
+  storage_search_embedding_visualization_AI_execution_Atlas: not_admitted

package/spec/authority-discovery.yaml

@@ -0,0 +1,119 @@
+version: 2
+spec:
+  id: nimicoding.authority-discovery.v2
+  owner: nimi-coding
+  status: active
+product_claim: bounded_deterministic_filtered_lexical_candidates_with_field_snippets_and_optional_direct_authored_relation_preview_for_callers_without_an_exact_authority_ID
+source: complete_admitted_package_private_AuthorityIR_SourceMap_and_existing_M1_direct_authored_graph_only
+command:
+  syntax: nimicoding authority discover <path> <query> [--kind <rule|definition>] [--owner <exact-owner>] [--scope <exact-scope>] [--lifecycle <active|removed>] --max-candidates <positive-safe-integer> --max-snippet-terms <positive-safe-integer> --max-bytes <positive-safe-integer> [--preview-direction <incoming|outgoing|both> --relations <comma-separated-relation-types> --max-edges <positive-safe-integer>] [--json]
+  continuity: same_purpose_specific_discover_command_with_a_hard_cut_payload_from_v1_to_v2
+normalization:
+  order: [Unicode_NFKC, split_camelCase_boundary, deterministic_lowercase, Unicode_Letter_or_Number_runs, deduplicate_query_terms]
+  snippet_stream: preserve_normalized_field_term_occurrence_order
+  excluded: [language_stopwords, stemming, synonyms, translation, fuzzy_typo_matching, model_inference]
+filters:
+  cardinality: each_filter_is_optional_singular_and_exact
+  kind: exact_rule_or_definition
+  owner: exact_known_unit_owner_equality
+  scope: exact_known_membership_in_the_unit_scope_sequence
+  lifecycle: exact_active_or_removed
+  execution: filter_the_complete_admitted_unit_universe_before_lexical_candidate_matching
+  effect_on_rank: none_other_than_removing_ineligible_units
+  unknown_owner_or_scope: AUTH_DISCOVERY_FILTER_UNKNOWN_with_null_discovery
+  structurally_impossible_or_empty_intersection: AUTH_DISCOVERY_FILTER_CONTRADICTORY_with_null_discovery
+  zero_lexical_match_in_nonempty_eligible_universe: AUTH_DISCOVERY_NOT_FOUND_without_absence_proof
+fields:
+  included: [id, title, owner, scope, meaning, statement, condition, failure, reason]
+  excluded: [relations, container_or_file_name, SourceMap_path_text, derived_context, implementation_evidence, test_evidence]
+  match: normalized_token_equality
+  admission: at_least_one_query_term_matches_one_included_field_of_an_eligible_unit
+ranking:
+  public_score: none
+  tuple:
+    - distinct_query_terms_in_id_or_title_descending
+    - distinct_query_terms_in_meaning_or_statement_descending
+    - distinct_query_terms_in_all_fields_descending
+    - distinct_query_terms_in_scope_descending
+    - distinct_query_terms_in_failure_descending
+    - distinct_query_terms_in_condition_descending
+    - distinct_query_terms_in_reason_descending
+    - distinct_query_terms_in_owner_descending
+    - unit_ID_lexical_ascending
+  invariants:
+    - filters_only_remove_ineligible_units_and_do_not_change_the_tuple
+    - max_snippet_terms_never_changes_matching_or_rank
+    - preview_configuration_and_graph_content_never_change_matching_or_rank
+snippets:
+  per_match: one_deterministic_window_over_the_exact_matched_field_value
+  normalization: NFKC_camel_boundary_lowercase_Unicode_Letter_Number_terms
+  terms: at_most_max_snippet_terms_normalized_terms_in_original_field_occurrence_order
+  width: minimum_of_maxSnippetTerms_and_complete_normalized_field_term_count
+  selection: maximize_distinct_matched_query_terms_then_choose_the_earliest_window_start
+  anchor: first_matched_term_in_the_window_with_exact_normalized_term_and_zero_based_fieldTermIndex_in_the_complete_normalized_field_term_stream
+  matched_terms: query_terms_present_in_the_returned_window_in_normalized_query_order
+  omissions: exact_nonnegative_omittedBeforeTerms_and_omittedAfterTerms_counts
+  complete: true_only_when_no_normalized_field_term_is_omitted
+  traceability: exact_portable_field_SourceMap_location_on_every_match
+  boundary: snippet_is_lexical_evidence_not_source_prose_context_or_an_explanation
+preview:
+  option_group: preview_direction_relations_and_max_edges_must_be_all_present_or_all_absent
+  source: existing_M1_direct_authored_graph_over_the_same_complete_compiler_snapshot
+  seeds: returned_candidate_IDs_only
+  direction: incoming_outgoing_or_both_incidence_selection_around_each_seed
+  relations: explicit_nonempty_unique_subset_of_applies_to_and_supersedes
+  topology: direct_authored_edges_only_no_transitive_expansion_or_context_assembly
+  authored_direction: preserved_even_when_selected_by_incoming_or_both_incidence
+  composition: deterministic_unique_nodes_and_unique_authored_edges_across_all_returned_candidates
+  nodes: every_returned_candidate_root_plus_every_selected_edge_endpoint_once
+  traceability: reuse_M1_node_primary_locations_and_authored_edge_SourceMap_locations
+  ordering:
+    roots: candidate_rank_order
+    relations_and_nodes: lexical_ascending
+    edges: source_then_type_then_target_lexical_ascending
+  completeness: every_matching_direct_edge_for_every_returned_candidate_or_refuse_the_whole_discovery
+  rank_effect: none
+payload:
+  format: nimicoding.authority-discovery/v2
+  fields: [format, query, filters, counts, truncated, absenceProven, candidates, relationPreview, budgets]
+  query_fields: [text, normalizedTerms]
+  filter_fields: [kind, owner, scope, lifecycle]
+  absent_filters: explicit_null
+  count_fields: [corpusUnits, eligibleUnits, matchedUnits, returnedCandidates]
+  absenceProven: always_false
+  candidate_fields: [rank, id, kind, lifecycle, owner, title, scope, matchedTerms, matches, primaryIdLocation]
+  match_fields: [field, terms, location, snippet]
+  snippet_fields: [normalization, terms, anchor, matchedTerms, omittedBeforeTerms, omittedAfterTerms, complete]
+  relationPreview: null_when_the_preview_option_group_is_absent
+  preview_fields: [direction, relations, complete, roots, nodes, edges, counts, budgets, policy]
+  preview_count_fields: [roots, units, edges]
+  preview_budget_fields: [maxEdges]
+  preview_policy_fields: [selection, edgeRepresentation, duplicateNodesAndEdges, rankingEffect]
+  budget_fields: [maxCandidates, maxSnippetTerms, maxEdges, maxBytes]
+  absent_preview_maxEdges: explicit_null
+  excluded: [complete_AuthorityIR_unit, inferred_relation, transitive_relation_closure, inferred_explanation, selected_authority, implementation_or_test_information]
+bounds:
+  max_candidates: required_explicit_positive_safe_integer_top_k_after_filters
+  max_snippet_terms: required_explicit_positive_safe_integer_per_match_window
+  max_edges: required_explicit_positive_safe_integer_only_when_preview_is_requested
+  truncation: explicitly_reports_matchedUnits_returnedCandidates_and_truncated_without_claiming_complete_recall
+  max_bytes: required_explicit_positive_safe_integer_over_UTF-8_bytes_of_compact_JSON.stringify_complete_v2_discovery_payload
+  edge_overflow: AUTH_DISCOVERY_PREVIEW_BUDGET_with_null_discovery_and_no_partial_preview_or_silent_edge_reduction
+  byte_overflow: AUTH_DISCOVERY_BUDGET_with_null_discovery_and_no_silent_candidate_snippet_or_preview_reduction
+fail_closed:
+  CLI_usage_error: missing_repeated_unknown_or_syntactically_invalid_CLI_argument_exits_2_without_a_discovery_product
+  runtime_guard: package_private_runtime_invalid_filter_or_preview_options_return_the_corresponding_diagnostic_with_null_discovery
+  invalid_query: AUTH_DISCOVERY_QUERY_INVALID
+  invalid_filter: [AUTH_DISCOVERY_FILTER_INVALID, AUTH_DISCOVERY_FILTER_UNKNOWN, AUTH_DISCOVERY_FILTER_CONTRADICTORY]
+  invalid_preview_configuration: AUTH_DISCOVERY_PREVIEW_INVALID
+  zero_match: AUTH_DISCOVERY_NOT_FOUND_does_not_prove_authority_absence
+  invalid_corpus: preserve_complete_compiler_diagnostics
+  partial_discovery: forbidden
+boundaries:
+  read_only: true
+  writes_or_durable_artifacts: none
+  reads_projected_contracts: false
+  exports_private_AuthorityIR: false
+  semantic_search_model_reranking_or_final_selection: not_claimed
+  relation_preview: bounded_direct_authored_topology_not_context_or_semantic_inference
+  caller_next_step: caller_owned_candidate_selection_followed_by_explicit_exact_query_or_context