Skip to content

feat(api): gate project lifecycle and durable publishers on filesystem admission #780

Description

@DecisionNerd

Parent

Canonical close gate: #776.

Blocked By

The native filesystem publication-semantics child of #776.

Problem

Even with native probe primitives, GraphForge can still mutate a supplied root before admission, race concurrent first openers, or let individual durable publishers bypass the shared gate.

Objective

Make one parent-scoped admission lifecycle the mandatory entry point before project creation, open-for-mutation, recovery, or publication.

Requirements

  • Coordinate absent-root and empty-root initialization with a persistent parent-scoped creation lock that is never unlinked after unlock.
  • Run the sibling native probe before the target root, FORMAT, generations, CURRENT, or project locks change.
  • Revalidate existing valid projects at the documented lifecycle boundary without changing the selected generation.
  • Route ordinary publication, recovery, deltas, compaction, checkpoints/revert, portable import, and every durable public mutation entry point through the same Rust admission.
  • Map unproven semantics to GF_UNSUPPORTED_FILESYSTEM before project mutation.
  • Preserve CURRENT plus complete immutable generations as the only authority.
  • Prevent symlink-mediated traversal and time-of-check/time-of-use substitution.
  • Define deterministic cleanup and retry behavior for process death and concurrent first openers.

Acceptance Criteria

  • Unsupported or unproven filesystems fail before any project-root mutation.
  • Multiprocess concurrent first openers initialize exactly once and resolve the same CURRENT.
  • Every durable public publisher consumes the same admission path.
  • Existing-project revalidation does not change the selected generation.
  • Process death at each admission phase leaves deterministic bounded recovery state.
  • Rust facade plus thin Python, Node, and CLI surfaces expose the same typed rejection.

BDD Completion Scenarios

  • Given an absent project root on a supported filesystem, when two processes open it concurrently, then one admission and initialization sequence wins and both observe the same complete generation.
  • Given an unsupported filesystem, when any public durable mutation path is invoked, then GF_UNSUPPORTED_FILESYSTEM is returned before the root changes.
  • Given an existing valid project, when admission is revalidated, then CURRENT and the selected immutable generation remain unchanged.

Non-Goals

Implementing platform probe primitives, delta semantics, compaction, or final model-based certification.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    coreCore source code changesenhancementNew feature or requesttestingTest coverage and testing infrastructure

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions