agentera 3.0.0-dev.23 → 3.0.0-dev.26

package/bundle/references/artifacts/state-storage-authority.yaml

@@ -1,12 +1,10 @@
 schema_version: agentera.stateStorageAuthority.v1
 status: active_authority
 purpose: >-
-  Define the public bounded-retrieval vocabulary for every state collection
-  while keeping each collection's storage authority explicit. It also defines
-  the lossless numbered-archive, project path, direct state API, compatibility,
-  projection, and serialized-output contracts for progress, decisions, and
-  health, plus objective-scoped immutable archival for newly published
-  experiments.
+  Define both the implemented bounded-retrieval contracts for current state and
+  the Decision 94 target entity and cutover contracts. The target declaration is
+  authoritative before its storage, writer, retrieval, and migration behavior is
+  implemented; implementation status is explicit at each boundary.
 authority:
   source: references/artifacts/state-storage-authority.yaml
   single_source_rule: >-
@@ -16,10 +14,721 @@ authority:
     amendment revision paths, legacy label coexistence rules, failure classes,
     or byte limits.
   implementation_boundary: >-
-    This contract does not migrate legacy state or change existing plan and
-    vision archive behavior. The maintenance-only Git backfill surface declared
-    by api.backfill may inventory reachable local history and publish only an
-    exact immutable archive record after explicit apply intent.
+    Shared entity storage plus the progress, decisions, health, plan, objective,
+    experiment, TODO-item, and documentation-inventory family writers and retrieval,
+    plus one-way forward import, are implemented but activate entity authority only
+    from the durable cutover marker. The preserved
+    singleton families remain legacy files. The
+    current numbered archive and retrieval groups remain migration input while
+    that marker is absent; no independent legacy repair mutation remains.
+
+entity_target:
+  status: progress_decisions_health_plan_objective_experiment_todo_and_docs_implemented_other_families_declared
+  decision: 94
+  activation: >-
+    This target becomes active persisted and structured state authority only
+    after entity_migration publishes a validated entity graph and writes the marker
+    last. Before then, legacy aggregates
+    remain migration input and explicitly labelled migration-evidence writer state;
+    ordinary public reads fail with migration_required instead of exposing them.
+  implementation_status:
+    progress: implemented
+    decisions: implemented
+    health: implemented
+    plan: implemented
+    objective: implemented
+    experiments: implemented
+    todo: implemented
+    docs: implemented
+    remaining_families: declared_not_implemented
+    rule: >-
+      Every implemented family selects entity behavior only when the durable
+      cutover marker is valid. Marker-absent ordinary consumers fail with
+      migration_required; the read-only migration preview and readiness checks do
+      not create entity state or write both authorities.
+  public_schema:
+    canonical_identity_field: id
+    canonical_classification_field: artifact
+    identity_and_classification_fields: [id, artifact]
+    entity_envelope:
+      required_fields: [id, artifact, record]
+      additional_identity_or_classification_fields: forbidden
+    forbidden_canonical_aliases:
+      - stable_id
+      - artifact_id
+      - entry_number
+      - number
+      - task_number
+      - experiment_number
+      - plan_id
+      - objective_id
+      - type_prefixed_id
+    exemptions:
+      - historical prose and immutable historical evidence
+      - internal TypeScript variable names that are not persisted or public structured output
+      - current pre-cutover contracts explicitly marked as implemented legacy authority
+  public_retrieval:
+    schema_version: agentera.entityPublicRetrieval.v1
+    status: final
+    commands:
+      progress:
+        list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state progress get --id ID --format json
+      decisions:
+        list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state decisions get --id ID --format json
+      health:
+        list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state health get --id ID --format json
+      plans:
+        list: agentera state plan list [--status open|complete|archived] [--limit N] [--cursor TOKEN] --format json
+        get: agentera state plan get --id ID --format json
+      plan_tasks:
+        list: agentera state plan tasks list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state plan tasks get --id ID --format json
+      objective:
+        list: agentera state objective list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state objective get --id ID --format json
+      experiments:
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] --format json
+        get: agentera state experiments get --id ID --format json
+      todo:
+        list: agentera state todo list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state todo get --id ID --format json
+      docs:
+        list: agentera state docs list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state docs get --id ID --format json
+    collections:
+      - { artifact: progress, identity: id, classification: artifact }
+      - { artifact: decisions, identity: id, classification: artifact }
+      - { artifact: health, identity: id, classification: artifact }
+      - { artifact: plan, boundary: plan, identity: id, classification: artifact }
+      - { artifact: plan, boundary: plan_task, identity: id, classification: artifact }
+      - { artifact: objective, identity: id, classification: artifact }
+      - { artifact: experiments, identity: id, classification: artifact }
+      - { artifact: todo, identity: id, classification: artifact }
+      - { artifact: docs, identity: id, classification: artifact }
+  identity:
+    scope: project_wide_across_all_entity_artifacts
+    alphabet: abcdefghijklmnopqrstuvwxyz
+    length: 10
+    accepted_pattern: '^[a-z]{10}$'
+    example: qjtrmnpvka
+    allocation: random_from_declared_alphabet
+    collision_rule: retry before publication; an existing ID is never reassigned or overwritten
+    prohibited_components: [prefix, sequence, timestamp, branch, writer, git_reference]
+    meaning_rule: >-
+      The ID is opaque and carries no artifact or entity-boundary information;
+      artifact is the sole public classification field.
+  storage_boundary:
+    rule: one independently mutable entity per writer-owned canonical file
+    aggregate_authority: forbidden
+    shared_primitives:
+      status: implemented
+      canonical_root: .agentera/entities
+      canonical_path_template: .agentera/entities/<artifact>/<boundary>/<id>.yaml
+      path_components: [artifact, boundary, id]
+      extension: .yaml
+      publication: exclusive_immutable_file
+      publication_context:
+        scope: shared_by_all_entity_families
+        binding: validated_project_root_and_exact_cutover_marker_snapshot
+        lifetime: mode_detection_through_writer_lock_and_final_publication_validation
+        pathname_race_contract: >-
+          Entity publication is rooted through held directory descriptors. The
+          root and exact valid marker identity and bytes are revalidated before
+          each directory, stage, and immutable-link boundary and after durable
+          publication before success. Because Node cannot make pathname
+          validation and mutation one kernel operation, a detected substitution
+          rolls back only attempt-owned links, stages, and empty directories by
+          pinned identity; final failure retains no attempt-owned entity state.
+        marker_change_after_detection: conflict_without_legacy_fallback
+        successor_preservation: never_remove_unmatched_or_unrelated_identity
+      allocation: provisional_candidate_until_publication
+      project_wide_id_claim:
+        synchronization: .agentera/.writer.lock
+        critical_section: final_project_wide_scan_through_durable_publication
+        interrupted_writer_recovery: dead_process_lock_reclamation
+        persistent_reservation: none
+      identical_replay: idempotent
+      replay_equality: recursive_key_sorted_logical_content_with_array_order_preserved
+      divergent_same_id: reject_without_overwrite
+      state_validation:
+        canonical_command: agentera check validate state
+        mutates: false
+        failure_exit: nonzero
+        diagnostics: bounded_structured_with_exact_recovery
+    same_entity_conflict: >-
+      Concurrent divergent edits to one entity remain an ordinary explicit file
+      conflict or validation conflict; no runtime silently selects a winner.
+    unrelated_entity_merge: >-
+      Independently created or changed entities occupy distinct canonical files
+      so ordinary Git can preserve both changes.
+  entities:
+    - boundary: progress_cycle
+      artifact: progress
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      record:
+        required_fields: [timestamp, type, phase, what, context]
+        required_paths: [context.intent]
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+        temporal_fields: [timestamp]
+        timestamp_format: 'YYYY-MM-DD HH:MM'
+      retrieval:
+        exact: agentera state progress get --id ID --format json
+        list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+        ordering: timestamp_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: decision
+      artifact: decisions
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      record:
+        required_fields: [date, question, context, alternatives, choice, reasoning, confidence]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, satisfaction]
+      retrieval:
+        exact: agentera state decisions get --id ID --format json
+        list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+        ordering: date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: decision_satisfaction
+      artifact: decisions
+      independently_mutable: true
+      relationships: [decision]
+      implementation: implemented
+      publication: replace_owned_entity
+      ownership: { fields: [decision], cardinality: zero_or_one }
+      record:
+        required_fields: [decision, state]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+    - boundary: decision_revision
+      artifact: decisions
+      independently_mutable: true
+      includes: [amendment]
+      relationships: [decision]
+      implementation: implemented
+      publication: immutable
+      ownership: { fields: [decision, base_sha256], cardinality: zero_or_one }
+      record:
+        required_fields: [decision, date, provenance, base_sha256, changes]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, satisfaction]
+    - boundary: health_audit
+      artifact: health
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      record:
+        required_fields: [date, dimensions, findings_summary, trajectory, grades]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+      retrieval:
+        exact: agentera state health get --id ID --format json
+        list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+        ordering: date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+      repair: >-
+        Canonical health audit entities are immutable and cannot be row-deduplicated.
+        Malformed envelopes, duplicate IDs, or conflicting ownership fail before effects
+        and recover through agentera check validate state; no repair event is fabricated.
+    - boundary: plan
+      artifact: plan
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [header, what, why, scope]
+        required_paths: [header.title, header.created, header.status]
+        forbidden_fields: [id, artifact, stable_id, plan_id, tasks, previous_plan_archived]
+        field_shapes:
+          scope:
+            type: mapping
+            required_fields:
+              included: string_list
+              excluded: string_list
+            optional_fields:
+              deferred: string_list
+            additional_fields: forbidden
+            legacy_source_normalization: >-
+              A block-style, non-flow, exactly-one-pair mapping used directly as
+              an included, excluded, or deferred sequence item is the historical
+              block-colon string encoding and normalizes to one `key: value`
+              string only when both source nodes are string scalars. Explicit
+              flow mapping syntax never normalizes and remains invalid under the
+              canonical validator. A deliberate block single-pair mapping is
+              syntactically indistinguishable from the legacy encoding and falls
+              under this source-form rule; no semantic intent is inferred.
+      retrieval:
+        exact: agentera state plan get --id ID --format json
+        list: agentera state plan list [--limit N] [--cursor TOKEN] --format json
+        ordering: created_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: plan_task
+      artifact: plan
+      independently_mutable: true
+      relationships: [plan, depends_on_tasks]
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [plan, name, status, depends_on, acceptance]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, task_number, stable_id, plan_id]
+    - boundary: objective
+      artifact: objective
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [header, objective, metric, baseline, scope]
+        required_paths: [header.title, header.status, objective.description, objective.measurement]
+        forbidden_fields: [id, artifact, stable_id, objective_id]
+      retrieval:
+        exact: agentera state objective get --id ID --format json
+        list: agentera state objective list [--limit N] [--cursor TOKEN] --format json
+        ordering: created_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: experiment
+      artifact: experiments
+      independently_mutable: true
+      relationships: [objective]
+      implementation: implemented
+      publication: immutable
+      baseline:
+        field: status
+        value: baseline
+        cardinality: exactly_one_when_experiments_exist
+      record:
+        required_fields: [objective, date, label, hypothesis, method, change, metric, regression, status, conclusion]
+        required_paths: [objective, date, label, status]
+        forbidden_fields: [id, artifact, number, experiment_number, stable_id, objective_id]
+      retrieval:
+        exact: agentera state experiments get --id ID --format json
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] --format json
+        ordering: date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: todo_item
+      artifact: todo
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [severity, status, description]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, path]
+      retrieval:
+        exact: agentera state todo get --id ID --format json
+        list: agentera state todo list [--limit N] [--cursor TOKEN] --format json
+        ordering: severity_then_status_then_id
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: documentation_inventory_entry
+      artifact: docs
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [document, path, last_updated, status]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+      retrieval:
+        exact: agentera state docs get --id ID --format json
+        list: agentera state docs list [--limit N] [--cursor TOKEN] --format json
+        ordering: path_then_id
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+  relationships:
+    representation: bare target entity ID in the named record field
+    integrity: every non-null target must resolve to exactly one entity with the declared target boundary
+    unresolved_behavior: whole-state validation and migration cutover fail without creating a target
+    declarations:
+      - source: decision_satisfaction
+        field: decision
+        target: decision
+        cardinality: exactly_one
+      - source: decision_revision
+        field: decision
+        target: decision
+        cardinality: exactly_one
+      - source: plan_task
+        field: plan
+        target: plan
+        cardinality: exactly_one
+      - source: plan_task
+        field: depends_on
+        target: plan_task
+        cardinality: zero_or_many_same_plan
+      - source: experiment
+        field: objective
+        target: objective
+        cardinality: exactly_one
+  views:
+    authority: non_authoritative_cli_rendering
+    mutation: forbidden
+    source: canonical entity files only after cutover
+    requirements:
+      - bounded lists expose id and artifact and provide exact get by id
+      - ordering and cursors bind to an explicit snapshot and never imply identity
+      - omissions expose counts, reasons, and exact retrieval commands
+      - nested plan/task and objective/experiment views are relationship projections
+      - startup views use the same entities and may omit detail only under declared budgets
+  intentional_singletons:
+    exhaustive: true
+    additions_require_authority_amendment: true
+    boundaries:
+      - boundary: vision
+        reason: one project north star; excluded from execution-cycle mutation
+      - boundary: design
+        reason: one project visual identity editorial artifact
+      - boundary: changelog
+        reason: one ordered release-history editorial artifact
+      - boundary: profile
+        reason: one reusable decision-profile document per selected profile
+      - boundary: runtime_local_session_state
+        reason: runtime-local and not canonical project entity state
+      - boundary: docs_mapping
+        reason: one project path and documentation-policy mapping, distinct from documentation inventory entries
+    conflict_rule: concurrent edits remain explicit whole-document conflicts
+  excluded_from_entity_migration:
+    - all intentional_singletons
+    - immutable historical prose and evidence, except structured references explicitly declared for rewrite
+    - genuinely singleton editorial artifacts added by an authority amendment
+  measurement_contract:
+    status: implemented
+    environment: Linux, Node.js 22 or newer, one cold CLI process per sample
+    fixtures:
+      small: 100 valid entities distributed across every declared entity boundary
+      large: 1000 valid entities distributed across every declared entity boundary
+      relationship_rule: every declared relationship has at least one valid fixture edge
+    sampling:
+      repetitions: 5
+      pass_rule: every repetition stays within every applicable limit
+      elapsed: wall-clock milliseconds from process start through complete serialized output
+      heap: process heapUsed peak minus heapUsed before fixture discovery
+      bytes: UTF-8 byte length of stdout including the trailing newline
+    targets:
+      exact_get:
+        max_latency_ms: 1000
+        max_heap_delta_bytes: 67108864
+        max_utf8_bytes: 1048576
+      bounded_list_small:
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+        max_utf8_bytes: 32768
+      bounded_list_large:
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+        max_utf8_bytes: 32768
+      startup_small:
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+        serialized_limits: budgets.startup.surfaces
+      startup_large:
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+        serialized_limits: budgets.startup.surfaces
+    failure_rule: >-
+      Over-budget results fail the target gate. They may return a measured
+      degraded envelope only where the referenced budget permits omission; they
+      never truncate bytes, omit required identity, or fabricate detail.
+
+entity_migration:
+  status: one_way_forward_import_implemented
+  decision: 94
+  kind: single_full_upgrade_cutover
+  cutover_marker:
+    path: .agentera/state-mode.yaml
+    schema_version: agentera.stateMode.v1
+    entity_mode:
+      schemaVersion: agentera.stateMode.v1
+      mode: entities
+    absent_mode: legacy
+    invalid_behavior: fail_without_fallback
+    detection: read_only
+    publication_owner: development_channel_v2_to_v3_upgrade
+    selection: >-
+      Project state and CLI installation state are independent dimensions. A v3
+      CLI selects this cutover for recognized marker-absent v2 aggregate state
+      whether the CLI runs from a self-contained npm package or a source
+      checkout. Pending v1 Markdown state and marker-absent state with no
+      recognized v2 entity input are rejected with manual recovery instructions.
+  invocation:
+    explicit_apply: full_upgrade_yes_only
+    dry_run: optional_read_only_preview
+    ordinary_reads_migrate: false
+    ordinary_writes_migrate: false
+    apply_invokes_git: true
+    read_only_command: >-
+      npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+    apply_command: >-
+      npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+    apply_boundary: >-
+      Full upgrade serializes through the project writer lock, validates the
+      deterministic conversion, writes each missing canonical entity or accepts
+      an exact existing match, validates the complete graph, and writes the
+      authority marker last. There is no direct
+      entity apply, public operation ID, resume, rollback, or cross-major restore.
+    git_preflight:
+      required: true
+      project_root: exact_worktree_root
+      source: HEAD_commit
+      checkout: no_staged_modified_renamed_or_untracked_paths_except_exact_cutover_outputs
+      migration_inputs: regular_tracked_files_whose_bytes_and_executable_mode_match_HEAD
+      absent_input: absent_from_HEAD_and_worktree
+      ignored_or_untracked_input: refuse
+      verification: >-
+        Planning and apply resolve the current HEAD commit and prove every present
+        migration input is a safe regular tracked path whose bytes and executable
+        mode match that commit. Apply repeats the proof under the writer lock
+        before its first effect. Non-Git projects and dirty or unsupported source
+        state are refused before any selected upgrade effect.
+    upgrade_composition:
+      owner: development_channel_v2_to_v3_upgrade
+      selected_with: [full]
+      apply_consent: >-
+        The upgrade --yes consent derives all source and target bindings in
+        process. Users provide no hashes, approval files, migration IDs, --force,
+        or additional cutover consent. Any --only apply is rejected at this
+        cross-major boundary.
+      interruption: >-
+        A rerun recomputes the deterministic conversion from unchanged Git-bound
+        source, accepts existing canonical targets only when their bytes match,
+        writes the first missing target, validates the complete graph, and finishes
+        the marker forward. It never deletes or replaces canonical entities.
+      completed: >-
+        A valid entity marker makes legacy authority permanently inactive.
+        Repeated upgrade validates current entity state and reports a no-op;
+        normal entity writes may evolve records without reopening cutover.
+      preflight: >-
+        Upgrade plans artifact normalization, entity readiness, runtime work,
+        and cleanup read-only before any selected apply function runs. A detect,
+        artifact, or entity blocker prevents entity publication and activation.
+        Runtime or cleanup blockers do not prevent valid entity activation; their
+        resources remain untouched and are reported after the marker as
+        action-required work.
+      phase_filters: >-
+        Every --only apply is invalid during a v2-to-v3 boundary. Read-only
+        filtered preview may remain available.
+      legacy_projection: >-
+        Canonical v2 YAML and already-resolved v1 conversions are inventoried
+        directly. A pending v1 Markdown conversion is not projected through a
+        prerequisite write during planning and therefore blocks the composed
+        apply before effects.
+      lifecycle_normalization: >-
+        Deterministic legacy plan lifecycle normalization is part of entity
+        projection during cutover. Upgrade retains the original legacy YAML as
+        source and recovery evidence instead of rewriting it first.
+      empty_state: unsupported_unknown_source_with_manual_handoff
+      existing_entity_state: validate_then_no_op
+  source_scope:
+    included_entities: entity_target.entities
+    included_structured_relationships: entity_target.relationships.declarations
+    preserved_singletons: entity_target.intentional_singletons.boundaries
+    sources: >-
+      Current canonical files, verified immutable archives, overlays, revisions,
+      and validated source evidence are inventoried together without changing
+      their pre-cutover authority. Every present input must be recoverable from
+      the pinned Git commit.
+    recovered_projection_correlation: >-
+      Every archive carrying recovery_provenance must match the immutable
+      .agentera/archive/recovery/projection-correlation.yaml recovery set by
+      identity, archive bytes, final record SHA-256, parent/child Git proof or
+      legacy converter/source proof, current projection bytes, and overlay.
+      Missing, changed, new, replaced, or unlisted recovery evidence blocks.
+  internal_migration_diagnostic: true
+  read_only_preview:
+    implementation: implemented
+    ordering: artifact_then_boundary_then_source_identity_then_source_path
+    filter: complete_declared_inventory
+    source_fingerprint: >-
+      SHA-256 over canonical JSON containing every declared source path's
+      project-relative name, presence, byte length, byte SHA-256, permission
+      mode, regular-file type, device, and inode from one verified open
+      descriptor. Missing declared roots are represented explicitly with null
+      identity. No mtime, Git value, or cache participates.
+    project_root: >-
+      The selected root must exist, be a directory, and resolve without a
+      symbolic-link root or symbolic-link traversal. Failure is structured and
+      occurs before inventory or effects.
+    recursive_roots: >-
+      Every declared archive and objective inventory root is lstat-validated
+      before traversal and again when recursion enters it. Existing symbolic
+      links and non-directories are project-bound inventory failures; their
+      targets are never inventoried.
+    authority_binding: >-
+      The preview records the active state-storage authority schema version and
+      byte SHA-256. The complete preview digest includes both values, so any
+      authority-only change invalidates approval before an apply effect.
+    proposed_id: >-
+      Preview-only ten-letter candidates are deterministically allocated from a
+      domain-separated SHA-256 of the complete source fingerprint and canonical
+      source key. This is allocation of a new opaque target candidate, not
+      reconstruction of a missing source ID. A collision is a blocker. Apply
+       preserves the deterministic mapping in each canonical target path.
+    preview_digest: >-
+      SHA-256 over canonical JSON of the complete unbounded inventory, proposed
+      mapping, authority-validated final envelope byte SHA-256 values,
+      relationship rewrite map, counts, blockers, and source
+      fingerprint plus the project selector, complete-source filter, declared
+      order, and migration-authority binding before output omission.
+    target_validation: >-
+      Before preview can be ready or produce an approvable digest, every proposed
+      final envelope, record, public field vocabulary, and relationship graph is
+      validated through the same authority-backed canonical target validator used
+       defensively by upgrade apply and forward retry. A target failure is a corrupt blocker tied
+      to its source identity and recovery action; preserved nonentity residues are
+      excluded from target validation and publication.
+    output:
+      max_utf8_bytes: 32768
+      default_limit: 100
+      maximum_limit: 1000
+      omission: whole entries and diagnostics only
+      scalar_truncation: forbidden
+      required_omission_fields: [omitted, omitted_count, omission_reason, retrieval]
+      recovery: >-
+        --after SOURCE_IDENTITY advances from the last whole logical identity
+        returned only when accompanied by that page's --source-fingerprint and
+        --preview-digest. The digest binds the project selector, complete-source
+        filter, authority-declared order, migration authority, and complete
+        source snapshot. Any mismatch refuses continuation with a command that
+        omits --after and restarts from the current snapshot. Diagnostics travel
+        with their owning entry, so repeated use of retrieval.command recovers
+        every later omitted entry and diagnostic.
+    counts:
+      physical_records: every observed record before identity grouping
+      logical_identities: every source identity after grouping
+      mirrors: excess canonical-identical physical records grouped under one logical identity
+      duplicates: excess divergent physical records claiming one logical identity
+      conflicts: logical identities with divergent candidates plus proposed-target collisions
+    zero_write: >-
+      Inventory, preview, malformed-input handling, and source-binding checks
+      open no writer or upgrade lock and create no directory, temporary file,
+      mapping, snapshot, journal, cache, or state file.
+    binding: >-
+       Before any apply effect, recompute the complete preview and require its
+       source fingerprint and preview digest to match the Git-pinned preparation.
+       A mismatch refuses every selected effect.
+  source_outcomes:
+    valid_full:
+      outcome: ready
+      rule: map one complete validated source entity and every relationship exactly once
+    canonical_mirror:
+      outcome: ready_with_mirrored_provenance
+      rule: group canonical-identical physical records as one logical identity and retain every provenance class
+    degraded_recoverable:
+      outcome: ready_with_provenance
+      rule: admit only independently validated full detail and record its recovery provenance
+    summary_only_or_missing_detail:
+      outcome: blocked
+      rule: retain evidence and stop before publication; never reconstruct omitted fields
+    ambiguous_or_duplicate_identity:
+      outcome: blocked
+      rule: retain every candidate and require explicit disposition; never choose by order or recency
+    proposed_target_conflict:
+      outcome: blocked
+      rule: retain every colliding logical identity and allocate no winner
+    corrupt_or_unresolved_relationship:
+      outcome: blocked
+      rule: report the exact source and recovery action; never publish a partial graph
+    unsupported:
+      outcome: blocked
+      rule: preserve bytes and report the unsupported source contract
+  non_fabrication:
+    forbidden:
+      - synthetic entities for missing source detail
+      - inferred IDs from order, numbers, paths, timestamps, branches, writers, or Git references
+      - guessed relationship targets
+      - silent dropping, deduplication, or winner selection
+    partial_cutover_success: forbidden
+  forward_state:
+    persisted_recovery_state: none
+    publication_order: exact_or_missing_entities_then_graph_validation_then_marker
+    retry_rule: accept_exact_targets_and_continue_at_first_missing_path
+    divergent_target: stop_without_replacement_and_name_first_unresolved_path
+    forbidden_fields: [operation_id, migration_id, snapshots, source_bytes, inode_receipts, rollback_state]
+    historical_evidence: >-
+      Already committed .agentera/migrations content is inert and remains
+      byte-for-byte untouched. Read-only legacy manifest parsing is retained only
+      for public validation of entity markers created by the former cutover.
+    fault_test_hook: >-
+      Tests may set NODE_ENV=test and
+      AGENTERA_FAULT_INJECT_ENTITY_MIGRATION_AFTER_PHASE to one declared publication
+      phase. Other environments ignore the variable.
+  lifecycle:
+    - phase: inventory
+      mutates: false
+      exit: every source entity and relationship is classified
+    - phase: preview
+      mutates: false
+      exit: proposed graph, mapping, outcomes, blockers, and digest are complete
+    - phase: git_preflight
+      mutates: false
+      exit: project root, HEAD, clean checkout, source bytes, types, and modes match
+    - phase: publishing_entities
+      mutates: true
+      exit: every canonical target is an exact match or is published once
+    - phase: entities_published
+      mutates: false
+      exit: canonical source-to-target parity, uniqueness, ownership, relationships, and budgets pass
+    - phase: marker
+      mutates: true
+      exit: one durable marker activates entity_target and retires writable legacy authority
 
 scope:
   supported_artifacts:
@@ -422,7 +1131,7 @@ consumer_matrix:
   access_contract:
     startup: agentera prime --context <capability> --format json
     list: agentera state <artifact-id> list --limit 20 --format json
-    get: agentera state <artifact-id> get --number N --format json
+    get: agentera state <artifact> get --id ID --format json
     policy: >-
       Use the bounded prime context first, then the bounded state list for
       discovery and exact state get for requested detail. Raw artifact or Git
@@ -601,7 +1310,7 @@ identity:
     accepted_pattern: '^(progress|decisions|health):[1-9][0-9]*$'
     example: decisions:53
   components:
-    artifact_id: one of scope.supported_artifacts.artifact_id
+    artifact_id: one of the supported artifact values declared by scope
     entry_number: positive integer from the artifact's entry_number_field
   uniqueness: stable_id is unique within one project archive
   ordering:
@@ -879,10 +1588,12 @@ api:
     empty_result: status=ok with entries=[] and counts.total=0; absence is not an error
   durability:
     command: agentera check durability [--project PATH] [--artifact ARTIFACT] [--number N] [--limit N] --format json
+    entity_command: agentera check durability --project PATH --artifact ARTIFACT --id ID --format json
     formats: [text, json, yaml]
     selectors:
       artifact: optional supported numbered archive artifact ID
       number: optional positive entry number; requires artifact
+      id: entity-mode bare entity ID; requires artifact and replaces number after cutover
       limit: optional bounded result count
     default_limit: 100
     maximum_limit: 100
@@ -902,406 +1613,12 @@ api:
       deterministic: >-
         With unchanged local files and reachable refs, repeated checks emit the
         same ordered result and do not create state or contact a remote.
-  backfill:
-    command: >-
-      agentera state backfill [--project PATH] [--artifact ARTIFACT]
-      [--number N] [--commit HASH] [--path PATH] [--limit N]
-      [--dry-run|--apply --force] --format {text,json,yaml}
-    formats: [text, json, yaml]
-    default_limit: 100
-    maximum_limit: 100
-    maximum_commits: 500
-    maximum_history_bytes: 16777216
-    supported_artifacts: [progress, decisions, health]
-    reachable_refs: [HEAD, refs/heads, refs/tags]
-    excluded_refs: [refs/remotes, custom_refs]
-    apply_requires: [--apply, --force, --project PATH, --artifact ARTIFACT, --number N]
-    status_values: [complete, degraded, blocked, unavailable]
-    response:
-      required_fields: [command, mode, status, project, read_only, remote_contact, head, scan, counts, active_projections_unchanged, active_projection_hashes, omitted, omitted_count, omission_reason, continuation, entries, diagnostics, source_contract]
-      entry_fields: [entry_id, artifact_id, entry_number, commit, path, blob_id, content_hash, ambiguity_reason, eligible, reachable, provenance, operation, refusal]
-    modes:
-      inventory: >-
-        The default read-only mode reports up to maximum_limit final rows after
-        combining reachable and rewritten-history occurrences. Omitted rows
-        carry explicit omission metadata; returned rows include commit, path,
-        blob identity, stable entry ID, canonical content hash, and an explicit
-        ambiguity reason.
-      preview: >-
-        --dry-run is read-only and shows proposed immutable archive bytes only
-        for a returned exact unique candidate, together with every matching
-        provenance.
-      apply: >-
-         --apply --force is the only mutation mode. It requires one project,
-         artifact, and entry number. A prior --dry-run is optional. Apply
-         independently revalidates the selected project, current HEAD, allowed
-         ref reachability, candidate path/blob/content, and immutable archive
-         target immediately before publication, and never overwrites conflicts.
-    ambiguity_reasons:
-      - none
-      - conflicting_versions
-      - shallow_history
-      - history_rewritten
-      - missing_history
-      - corrupt_history
-      - changed_head
-      - scan_bounded
-      - git_unavailable
-      - immutable_conflict
-      - candidate_changed
-      - no_matching_pin
-    guarantees:
-      read_only_inventory_and_preview: true
-      apply_requires_force: true
-      preview_optional: true
-      apply_revalidation: >-
-        Apply repeats project, HEAD, allowed-ref reachability, candidate
-        provenance/content, and immutable-target checks immediately before
-        publication; a failed check preserves active projections and archives.
-      remote_contact: forbidden
-      custom_refs: forbidden
-      commit_fields_in_archive_records: forbidden
-      projection_writes: forbidden
-      immutable_conflicts: refuse_without_overwrite
-      retry: identical_publication_is_idempotent
-      failure_projection_rule: active_projections_remain_byte_identical
-    omission:
-      fields: [omitted, omitted_count, omission_reason, continuation]
-      complete_reason: none
-      bounded_reason: result_limit
-      continuation: >-
-        No cursor is issued. Use --artifact ARTIFACT --number N to retrieve an
-        omitted entry because --limit cannot exceed maximum_limit (100).
-    traceability:
-      provenance_fields: [commit, path, blob_id, entry_id, content_hash, reachable]
-      archive_record_forbids: [commit, commit_hash, git_commit, git_ref]
-    recovery: >-
-      Resolve the reported ambiguity, unavailable Git state, changed candidate,
-      or immutable conflict and retry the same exact selectors. A refused
-      operation leaves active projections and existing archives unchanged;
-      identical publication is an idempotent replay.
-  migrate:
-    namespace: agentera state migrate
-    command: >-
-      agentera state migrate [--project PATH] [--artifact ARTIFACT]
-      [--number N] [--path PATH] [--limit N]
-      [--dry-run|--apply --force] --format {text,json,yaml}
-    purpose: >-
-      Inventory bounded, project-local legacy state and define the only
-      authority for a later non-Git migration apply. This surface does not
-      infer missing records, contact Git, contact a remote, or remove legacy
-      source files.
-    implementation_boundary: >-
-      The runtime owns bounded, project-local candidate inventory and the
-      explicit archive, backup, projection, and mutation flow described here.
-      Inventory never reads Git or writes archives, backups, or projections;
-      migration remains independent of the optional Git backfill surface.
-    formats: [text, json, yaml]
-    default_limit: 20
-    maximum_limit: 100
-    supported_artifacts: [progress, decisions, health]
-    selectors:
-      project:
-        flag: --project PATH
-        default: current_working_directory
-        resolution: >-
-          Resolve the selected directory to a real project root before any
-          candidate is considered. The project root is selected explicitly or
-          is the caller's current working directory; AGENTERA_HOME, profile
-          paths, docs.yaml overrides, and Git worktrees do not replace it.
-      artifact:
-        flag: --artifact ARTIFACT
-        required_for_apply: true
-        valid_values: [progress, decisions, health]
-      number:
-        flag: --number N
-        pattern: '^[1-9][0-9]*$'
-        required_with: --artifact
-        meaning: exact positive legacy entry number; never a positional offset
-      path:
-        flag: --path PATH
-        pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}\.(md|yaml|yml)$'
-        relative_to: selected_project_root
-        required_for_custom_apply: true
-        meaning: exact candidate path pin; inventory may omit it to enumerate candidates
-      limit:
-        flag: --limit N
-        default: 20
-        minimum: 1
-        maximum: 100
-        meaning: maximum returned candidate summaries, not a scan escape hatch
-      format:
-        flag: --format FORMAT
-        valid_values: [text, json, yaml]
-    modes:
-      inventory:
-        selector: default when neither --dry-run nor --apply is present
-        read_only: true
-        writes: forbidden
-      preview:
-        selector: --dry-run
-        read_only: true
-        writes: forbidden
-        output: exact proposed archive, backup, and projection operations only for addressable candidates
-      apply:
-         selector: --apply --force
-         read_only: false
-         mutation_intent: explicit_apply_and_force
-         selectors_required: [--artifact, --number]
-         mutation: >-
-           The runtime publishes only after revalidating the selected candidate,
-           project boundary, backup identity, and immutable archive identity.
-      invalid_combinations:
-        - flags: [--apply, --dry-run]
-          failure_class: invalid_selector
-          message: --apply and --dry-run are mutually exclusive
-        - flags: [--apply]
-          requires: --force
-          failure_class: invalid_selector
-          message: --apply requires explicit --force intent
-        - flags: [--force]
-          requires: --apply
-          failure_class: invalid_selector
-          message: --force requires --apply
-    inventory:
-      project_local: true
-      bounded_scan:
-        roots:
-          - path: .
-            maximum_depth: 1
-          - path: .agentera
-            maximum_depth: 1
-        excluded_relative_paths:
-          - .git
-          - .agentera/archive
-          - .agentera/overlays
-          - .agentera/migration-backups
-        maximum_candidate_files: 256
-        maximum_file_bytes: 1048576
-        maximum_total_bytes: 16777216
-        ordering: normalized_relative_path_ascending
-      candidate_rule: >-
-        A candidate is a regular, non-symlink file directly under one declared
-        scan root whose basename is ASCII and matches
-        ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}\.(md|yaml|yml)$. Fixed legacy names
-        are recognized first; every other accepted name is a custom candidate
-        and remains project-local.
-      fixed_names:
-        - path: .agentera/PROGRESS.md
-          artifact: progress
-        - path: .agentera/DECISIONS.md
-          artifact: decisions
-        - path: .agentera/HEALTH.md
-          artifact: health
-      custom_name_rule: >-
-        Custom names are discovered only within the declared roots and are
-        never mapped from their basename alone. A custom candidate is
-        addressable only when --path pins it, --artifact identifies the
-        numbered artifact, and parsing yields exactly one supported stable
-        identity for the requested --number. A candidate with zero, multiple,
-        conflicting, or unsupported identities is inventory-visible but not
-        apply-eligible.
-      deterministic_rejections:
-        unsafe_path: absolute paths, traversal segments, encoded traversal, URI paths, or symlink components
-        escaping_path: realpath is outside the selected project root
-        ambiguous_candidate: one candidate yields multiple artifact or entry identities, or identities conflict
-        unsupported_candidate: unsupported extension, non-regular file, invalid encoding, or unsupported artifact shape
-        scan_bounded: candidate or byte limits are exceeded; omitted candidates are reported, never silently dropped
-    project_boundary:
-      selected_root: resolved_realpath_of_project_selector
-      candidate_rule: >-
-        The candidate realpath and every existing parent must remain strictly
-        beneath selected_root. The project root itself is not a candidate.
-      reject: [absolute_candidate_path, traversal, encoded_traversal, uri_path, symlink_escape, outside_project]
-      docs_mapping: forbidden
-      remote_access: forbidden
-    compatibility_window:
-      name: v2_to_v3_local_state
-      scope: numbered_progress_decisions_health_only
-      supported_sources: [legacy_markdown, legacy_yaml, current_yaml_projection]
-      classifications: [complete, degraded, blocked, unsupported]
-      cases:
-        new:
-          classification: complete
-          behavior: preserve current archive and projection authority
-        legacy_full:
-          classification: degraded
-          behavior: archive exact parsed records and retain source provenance
-        legacy_summary:
-          classification: degraded
-          behavior: preserve summary-only detail and never reconstruct absent fields
-        non_git:
-          classification: complete
-          behavior: local inventory and publication do not require Git
-        ambiguous:
-          classification: blocked
-          behavior: never choose between candidates; preserve all diagnostics
-        corrupt:
-          classification: blocked
-          behavior: preserve source bytes and do not archive or project invalid records
-        unsupported:
-          classification: unsupported
-          behavior: report a deterministic candidate diagnostic without mutation
-      no_reconstruction: >-
-        Missing, ambiguous, compacted, summary-only, and satisfaction-incomplete
-        state remains explicitly classified. No fields, identity, satisfaction,
-        provenance, or history are inferred from names, summaries, Git, or
-        profile state. Decision 53 remains governed by overlays.decision_53_rules.
-    backups:
-      required_for_apply: true
-      project_local: true
-      root: .agentera/migration-backups
-      path_template: .agentera/migration-backups/<sha256-relative-source>.bak
-      bytes: exact_source_bytes_before_projection
-      identity: sha256(relative_source_path + NUL + source_bytes)
-      publication: exclusive_immutable_file
-      existing_backup: >-
-        An identical backup is an idempotent replay. Different bytes at the
-        same backup identity are backup_conflict and block without overwrite.
-      cleanup: forbidden
-      required_before_projection: true
-    publication:
-      order:
-        - validate_candidate_and_selector
-        - publish_immutable_archive_record
-        - publish_immutable_backup
-        - publish_current_projection
-      archive_before_projection: true
-      archive_immutability: storage.archive.mutation_policy
-      projection_failure: >-
-        Leave archive, backup, and the pre-existing projection bytes unchanged
-        except for successfully published immutable artifacts; retry must replay
-        identical artifacts rather than restart or synthesize a new identity.
-      monotonic_states: [inventory, previewed, archive_published, backup_published, projection_published]
-      retry: >-
-        Repeating the same project, selector, source bytes, and canonical record
-        is an idempotent replay. The same stable identity with different bytes
-        is immutable_conflict; no existing archive, backup, or projection bytes
-        may be overwritten.
-    git:
-      required: false
-      reads: forbidden
-      remote_contact: forbidden
-      completion_independent: true
-      provenance: local_source_path_and_content_hash_only
-    result:
-      schema_version: agentera.stateMigrationResult.v1
-      statuses: [complete, degraded, blocked, unavailable]
-      required_fields: [schemaVersion, command, status, mode, project, read_only, mutation_intent, mutation_performed, remote_contact, inventory_performed, entries, counts, diagnostics, source_contract, omitted, omitted_count, omission_reason, retrieval]
-      entry_fields: [candidate_id, path, artifact_id, entry_number, classification, detail_availability, compatibility, source, addressable, size_bytes, rejection, provenance]
-      count_fields: [physical, addressable, addressable_ids, unaddressable, ambiguous, mirrored, duplicate, conflict, omitted]
-      count_rules:
-        physical:
-          source: all_candidates
-          operation: count
-        addressable:
-          source: visible_entries
-          operation: count
-          predicates: [{field: addressable, equals: true}]
-        addressable_ids:
-          source: visible_entries
-          operation: distinct
-          field: candidate_id
-        unaddressable:
-          source: visible_entries
-          operation: count
-          predicates:
-            - {field: addressable, equals: false}
-            - {field: classification, not_equals: ambiguous}
-        ambiguous:
-          source: visible_entries
-          operation: count
-          predicates: [{field: classification, equals: ambiguous}]
-        mirrored:
-          source: visible_entries
-          operation: count
-          predicates: [{field: classification, equals: mirrored}]
-        duplicate:
-          source: visible_entries
-          operation: count
-          predicates: [{field: classification, equals: duplicate}]
-        conflict:
-          source: visible_entries
-          operation: count
-          predicates: [{field: classification, equals: conflict}]
-        omitted:
-          source: omitted_count
-          operation: value
-      omission:
-        fields: [omitted, omitted_count, omission_reason, retrieval]
-        field_sources:
-          omitted: has_omissions
-          omitted_count: omitted_count
-          omission_reason: omission_reason
-          retrieval: retrieval
-        complete_reason: none
-        bounded_reason: scan_bounded
-        output_bounded_reason: serialized_output_byte_budget
-        retry: >-
-          Retry with narrower project or selectors, or use the bounded list
-          pointer to continue from the same normalized snapshot.
-        output_retry: >-
-          Retry with a smaller --limit or narrower selectors; use --path with
-          --artifact and --number to address one omitted candidate. The omitted
-          records remain accounted for and no state was changed by output bounding.
-        retrieval: >-
-          agentera state migrate --project PATH [selectors] --limit N
-        semantics: >-
-          Omitted candidates are represented by omitted=true, omitted_count,
-          omission_reason, and a bounded retry/list pointer. Text, JSON, and YAML
-          are projections of the same envelope and never contain unbounded records.
-    failures:
-      schema_version: agentera.stateFailure.v1
-      deterministic: >-
-        The same authority, project bytes, selectors, and local filesystem
-        state produce the same failure class, syntax, example, and recovery.
-      classes:
-        - class: invalid_selector
-          message: selector is missing, duplicated, malformed, or not allowed for the selected mode
-          example: agentera state migrate --number 1 --format json
-          recovery: add one supported --artifact selector and retry; no state was changed
-        - class: project_boundary
-          message: selected project or candidate path escapes the project boundary
-          example: agentera state migrate --path ../secrets.yaml --format json
-          recovery: select a project-local relative path; no state was changed
-        - class: unsupported_candidate
-          message: candidate is not a supported regular file or artifact shape
-          example: agentera state migrate --path .agentera/state.txt --format json
-          recovery: use a supported Markdown or YAML candidate; no state was changed
-        - class: ambiguous_candidate
-          message: candidate has multiple or conflicting supported identities
-          example: agentera state migrate --artifact progress --number 1 --path CUSTOM.md --dry-run --format json
-          recovery: resolve the candidate ambiguity before retrying; no state was changed
-        - class: corrupt_candidate
-          message: candidate bytes or parsed record fail the declared artifact schema
-          example: agentera state migrate --artifact decisions --number 53 --dry-run --format json
-          recovery: repair or preserve the source and retry only after validation; no state was changed
-        - class: backup_conflict
-          message: immutable backup identity already contains different source bytes
-          example: agentera state migrate --artifact progress --number 1 --apply --force --format json
-          recovery: preserve the existing backup and resolve the source conflict; no projection was changed
-        - class: immutable_conflict
-          message: immutable archive identity already contains different canonical content
-          example: agentera state migrate --artifact progress --number 1 --apply --force --format json
-          recovery: preserve the existing archive and resolve the identity conflict; no projection was changed
-        - class: changed_candidate
-          message: candidate changed between inventory, preview, and apply
-          example: agentera state migrate --artifact health --number 1 --apply --force --format json
-          recovery: rerun inventory and preview against the current local bytes; no projection was changed
-        - class: scan_bounded
-          message: bounded candidate or byte limit was exceeded
-          example: agentera state migrate --limit 100 --format json
-          recovery: narrow the project or selectors; omitted candidates remain reported
-    guarantees:
-      read_only_inventory_and_preview: true
-      apply_requires_force: true
-      archive_before_projection: true
-      backups_before_projection: true
-      monotonic_retry: true
-      archive_immutability: true
-      project_local: true
-      remote_contact: forbidden
-      git_independent: true
+  entity_migration_discovery:
+    command: agentera state migrate entities --project PATH --dry-run --format json
+    implementation: implemented
+    read_only: true
+    writes: forbidden
+    authority: entity_migration.read_only_preview
   cursor:
     syntax: opaque TOKEN returned as response.next_cursor
     first_page: omit --cursor to establish a snapshot