@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/spec/authority-authoring.yaml

@@ -0,0 +1,137 @@
+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
+  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] [--json]
+    semantic_status: not_evaluated
+    writes: one_source_file_atomically_unless_check
+    structural_discriminants: [format, kind, lifecycle]
+    invention: forbidden
+  check:
+    syntax: nimicoding authority check <path> [--scope-bindings <file>] [--json]
+    writes: none
+    no_scope_bindings_flag: exact_existing_check_behavior
+    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
+    source_format: exact_nimicoding.authority/v2_only
+    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-change-candidates.yaml

@@ -0,0 +1,146 @@
+version: 1
+spec:
+  id: nimicoding.authority-change-candidates.v1
+  owner: nimi-coding
+  status: active
+product_claim: complete_deterministic_change_derived_recall_of_current_active_non_root_authority_candidates_over_caller_requested_explicit_exact_channels
+source:
+  before: one_complete_independently_admitted_package_private_AuthorityIR_and_SourceMap
+  after: one_complete_independently_admitted_package_private_AuthorityIR_and_SourceMap
+  changes: complete_semantic_diff_between_the_two_admitted_inputs
+command:
+  syntax: nimicoding authority change-candidates <before-path> <after-path> --channels <comma-separated-closed-set> --max-candidates <positive-safe-integer> --max-reasons <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]
+channel_selection:
+  required: one_non_empty_array
+  admitted: [owner, scope, changed_term, direct_relation, definition_identity, definition_title]
+  unknown_duplicate_non_string_or_empty: AUTH_CHANGE_CANDIDATES_CHANNELS_with_null_product
+  input_order: non_semantic
+  output_order: canonical_admitted_channel_order
+  completeness_scope: exact_union_of_requested_channels_only
+  unrequested_channels: not_evaluated_and_do_not_recall_or_emit_reasons
+roots:
+  selection: every_exact_unit_ID_named_by_at_least_one_complete_semantic_diff_change
+  included_operations: [unit_added, modified, added, removed]
+  metadata_only_changes: included_because_owner_and_title_rename_context_are_product_relevant_recall_inputs
+  formatting_profile_file_move_container_regroup_and_source_order_only_change: no_root
+  root_record_fields: [id, changes, before, after]
+  change_fields: [operation, pointer]
+  side_fields: [kind, owner, lifecycle, title, location]
+  absent_side: explicit_null
+candidate_universe:
+  source: after_only
+  lifecycle: active_only
+  roots: excluded
+  removed_tombstones: excluded
+  admission: at_least_one_exact_recall_reason_from_one_declared_channel
+  ordering: lexical_unit_ID
+recall_channels:
+  owner:
+    match: exact_owner_equality_between_candidate_and_each_before_or_after_root
+    reason_witness: exact_raw_owner_and_both_SourceMap_locations
+  scope:
+    match: exact_scope_membership_shared_by_an_active_rule_candidate_and_each_before_or_after_active_rule_root
+    reason_witness: exact_raw_scope_and_both_SourceMap_locations
+  changed_term:
+    root_fields: [title, meaning, statement, condition, failure]
+    root_values: only_normalized_terms_present_on_one_changed_field_side_and_absent_from_the_other_side_plus_every_after_term_of_a_unit_added_root
+    candidate_fields: [title, meaning, statement, condition, failure]
+    normalization: [Unicode_NFKC, split_camelCase_boundary, deterministic_lowercase, Unicode_Letter_or_Number_runs, deduplicate_terms]
+    match: one_or_more_exact_normalized_terms_shared_by_one_changed_root_field_and_one_candidate_field
+    excluded: [unchanged_root_text, owner, scope, lifecycle, relations, removal_reason, fuzzy_matching, stopwords, synonyms, translation, embedding, model_inference]
+    unchanged_terms_within_a_changed_field: excluded
+    reason_witness: complete_shared_changed_term_set_plus_both_raw_fields_and_both_SourceMap_locations
+  direct_relation:
+    source: complete_before_and_after_authored_applies_to_or_supersedes_edges
+    match: candidate_is_the_exact_source_or_target_endpoint_of_an_edge_incident_to_a_root
+    direction: incoming_or_outgoing_relative_to_the_root_while_preserving_authored_source_and_target
+    reason_witness: complete_authored_edge_with_source_relation_target_locations_plus_root_and_candidate_ID_locations
+  definition_identity:
+    anchors:
+      - a_definition_root_on_the_same_side
+      - an_exact_definition_target_of_a_relation_authored_by_a_root_on_the_same_side
+    match:
+      - candidate_authors_a_relation_to_the_exact_same_definition_ID
+      - candidate_raw_text_contains_the_exact_NFKC_definition_ID_with_identifier_token_boundaries
+    reason_witness: exact_definition_ID_title_and_locations_root_reference_and_candidate_field_or_relation
+  definition_title:
+    anchors: same_as_definition_identity
+    match: candidate_raw_text_contains_the_complete_exact_NFKC_case_sensitive_definition_title_with_Unicode_Letter_Number_boundaries
+    excluded: [partial_title, case_fold, fuzzy_phrase, synonym, translation]
+    reason_witness: exact_definition_ID_title_and_locations_root_reference_and_candidate_raw_field
+composition:
+  selection: set_union_of_every_candidate_admitted_by_any_requested_channel_on_either_side
+  reasons: every_unique_exact_requested_channel_side_root_and_witness_tuple
+  duplicate_candidates_and_reasons: suppressed
+  ranking_top_k_stopwords_frequency_cutoff_or_heuristic_reduction: forbidden
+  zero_candidates: successful_complete_empty_union
+  semantic_judgment: none
+candidate:
+  fields: [id, kind, owner, lifecycle, title, modality, scope, rawFields, relations, primaryIdLocation, reasons]
+  modality: exact_must_or_must_not_for_rules_and_explicit_null_for_definitions
+  scope: exact_after_scope_for_rules_and_empty_for_definitions
+  raw_fields: [meaning, statement, condition, failure]
+  absent_raw_fields: explicit_null
+  relations: complete_after_authored_relation_records
+  reason_fields: [channel, side, rootId, witness]
+  reason_channels: [owner, scope, changed_term, direct_relation, definition_identity, definition_title]
+  side: before_or_after
+  locations:
+    fields: [file, range, sourcePointer]
+    paths: relative_to_the_corresponding_input_root_when_inside_it
+payload:
+  format: nimicoding.authority-change-candidates/v1
+  fields: [format, complete, requestedChannels, roots, candidates, counts, budgets, policy]
+  requestedChannels: canonical_ordered_exact_caller_set
+  complete: true_only_when_the_entire_requested_channel_union_and_every_requested_channel_reason_are_returned
+  count_fields: [beforeUnits, afterUnits, changedRoots, eligibleAfterUnits, candidates, reasons]
+  budget_fields: [maxCandidates, maxReasons, maxBytes]
+  policy_fields: [roots, candidateUniverse, recall, changedTerms, ordering, interpretation]
+  excluded:
+    - score_or_rank
+    - truncated_or_partial_candidates
+    - inferred_relation
+    - conflict_or_consistency_finding
+    - retirement_or_replacement_recommendation
+    - authority_pass_or_fail
+    - implementation_or_test_conformance
+budgets:
+  max_candidates: required_explicit_positive_safe_integer_over_the_complete_requested_channel_candidate_union
+  max_reasons: required_explicit_positive_safe_integer_over_all_unique_exact_requested_channel_reasons
+  max_bytes: required_explicit_positive_safe_integer_over_UTF-8_bytes_of_compact_JSON_stringify_complete_payload
+  candidate_or_reason_overflow: AUTH_CHANGE_CANDIDATES_BUDGET_with_null_product_and_partial_false
+  byte_overflow: AUTH_CHANGE_CANDIDATES_BUDGET_with_null_product_and_partial_false
+  silent_reduction: forbidden
+  evaluation_stages:
+    - exact_candidate_ID_union_using_only_light_indexes_and_match_descriptors
+    - exact_unique_logical_reason_count_without_global_reason_key_storage_or_SourceMap_witness_objects
+    - full_reason_candidate_root_and_payload_materialization_only_after_candidate_and_reason_budgets_pass
+  candidate_overflow: return_exact_required_candidate_count_without_reason_witness_candidate_record_or_payload_materialization
+  reason_overflow: return_exact_required_reason_count_without_reason_witness_candidate_record_or_payload_materialization
+  duplicate_match_occurrences: collapsed_by_each_channel_visitor_before_reason_counting
+indexing:
+  snapshot_indexes: [by_ID, by_owner, by_scope, incoming_relations, outgoing_relations, by_container]
+  changed_terms: one_precomputed_candidate_field_term_set_plus_exact_term_to_candidate_field_inverted_index_per_side
+  definition_patterns:
+    normalization: each_candidate_text_field_and_each_unique_definition_identity_or_title_pattern_is_NFKC_normalized_once_per_index_build
+    matching: one_deterministic_Aho_Corasick_multi_pattern_scan_per_candidate_field_and_stage
+    boundaries: exact_identity_or_Unicode_Letter_Number_title_boundaries_are_checked_on_each_match
+  direct_relations: snapshot_adjacency_indexes_without_candidate_linear_search
+  persistence: none_indexes_are_transient_and_derived_from_the_two_immutable_compiler_snapshots
+fail_closed:
+  invalid_before_or_after_authority: preserve_complete_side_qualified_diff_or_compiler_diagnostics
+  invalid_transition: preserve_AUTH_DIFF_TRANSITION_INVALID
+  invalid_channels: AUTH_CHANGE_CANDIDATES_CHANNELS
+  invalid_runtime_budget: AUTH_CHANGE_CANDIDATES_BUDGET_with_null_product
+  partial_product: forbidden
+boundaries:
+  read_only: true
+  writes_or_durable_artifacts: none
+  public_JS_exports: none
+  authority_or_product_semantic_decision: not_claimed
+  natural_language_contradiction_detection: not_admitted
+  relation_generation_or_repair: not_admitted
+  hard_cut_workflow_or_report: host_owned_not_admitted
+  implementation_code_test_or_gate_location: separate_product_not_included
+  source_container_proximity_annotation: not_included_because_it_is_non_semantic_unbounded_and_derivable_from_returned_locations
+  cache_SQLite_embedding_or_persistent_index: none

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,77 @@
+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:
+  escaped_line_continuation: exact_backslash_LF_or_backslash_CRLF_is_removed_for_matching_while_locations_use_the_original_source_line
+  source_string_escape_boundary: one_backslash_followed_by_a_common_escape_starter_ends_the_local_path_while_two_or_more_backslashes_remain_a_Windows_separator_run
+  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
+    terminal_period_disambiguation:
+      raw_target_or_prefix_exists: preserve_raw_target
+      raw_absent_and_removing_exactly_one_period_resolves: classify_the_single_period_as_sentence_punctuation
+      raw_and_single_period_stripped_both_absent: preserve_raw_target_and_report_dead
+      raw_and_single_period_stripped_both_exist: preserve_raw_target
+    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_artifacts, test_artifacts]
+  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_a_lexical_match_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

package/spec/authority-graph.yaml

@@ -0,0 +1,59 @@
+version: 1
+spec:
+  id: nimicoding.authority-graph.v1
+  owner: nimi-coding
+  status: active
+product_claim: complete_admitted_private_compiler_snapshot_supports_bounded_direct_refs_exact_path_and_local_subgraph
+source: one_complete_package_private_AuthorityIR_and_SourceMap_compile_per_command
+commands:
+  refs: nimicoding authority refs <path> <id> --direction <incoming|outgoing|both> --relations <closed-set> --max-units <positive-safe-integer> --max-edges <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]
+  path: nimicoding authority path <path> <from-id> <to-id> --traversal <directed|incidence> --relations <closed-set> --max-hops <positive-safe-integer> --max-units <positive-safe-integer> --max-edges <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]
+  subgraph: nimicoding authority subgraph <path> <id> --direction <incoming|outgoing|both> --relations <closed-set> --depth <positive-safe-integer> --max-units <positive-safe-integer> --max-edges <positive-safe-integer> --max-bytes <positive-safe-integer> [--json]
+relations:
+  admitted: [applies_to, supersedes]
+  request: explicit_non_empty_unique_closed_set
+  defaults_or_all_alias: forbidden
+product:
+  format: nimicoding.authority-graph/v1
+  shared_fields: [format, operation, query, complete, nodes, edges, policy, counts, budgets]
+  path_fields: [found, steps]
+  node_fields: [id, kind, owner, lifecycle, scope, location]
+  definition_or_removed_scope: []
+  edge_fields: [source, type, target, sourceLocation, relationLocation, targetLocation]
+  location_fields: [file, range, sourcePointer]
+  semantic_prose_or_raw_AuthorityIR: excluded
+ordering:
+  nodes: lexical_ID
+  edges: [source, type, target]
+  comparator: portable_lexical_comparator
+traversal:
+  refs: direct_only_with_each_authored_edge_once
+  path_directed: authored_source_to_target_only
+  path_incidence: forward_or_reverse_steps_while_edges_remain_canonical_authored_source_to_target
+  reverse_step_claim: topology_incidence_only_not_semantic_dependency
+  path_selection: minimum_hops_then_lexical_minimum_complete_step_tuple_sequence
+  path_step_tuple: [relation_type, traversal, authored_source, authored_target]
+  subgraph: deterministic_cycle_safe_BFS_returning_complete_selected_graph_within_depth
+budgets:
+  required_all: [max_units, max_edges, max_bytes]
+  path_also_requires: max_hops
+  subgraph_also_requires: depth
+  units_and_edges: constrain_complete_traversal_accounting_not_only_returned_witness
+  bytes: UTF-8_bytes_of_compact_JSON.stringify_graph
+  overflow: AUTH_GRAPH_BUDGET_with_null_graph_and_partial_false
+outcomes:
+  completed: includes_complete_no_path_with_found_false
+  usage_error: invalid_or_missing_CLI_arguments_exit_2_without_graph_product
+  refused: parsed_invocation_with_invalid_corpus_unknown_ID_or_insufficient_budget
+  failed: IO_resource_or_internal_failure
+  unknown_ID: AUTH_QUERY_NOT_FOUND
+  partial_or_truncated_graph: forbidden
+locations:
+  paths: input_root_relative_portable_paths_when_inside_input_root
+  semantics: preserve_SourceMap_range_and_sourcePointer
+  relocation: equivalent_relocated_corpus_has_stable_logical_graph_and_relative_locations
+boundaries:
+  read_only: true
+  durable_graph_cache_or_database: none
+  public_JS_exports: none
+  new_grammar_relation_or_inferred_prose_relation: forbidden