Skip to content

feat(authoring): versioned manifest with pages, geometry, and stable flow identity - #83

Merged
Hacks4Snacks merged 2 commits into
mainfrom
hacks4snacks/stableflowidentity
Jul 29, 2026
Merged

feat(authoring): versioned manifest with pages, geometry, and stable flow identity#83
Hacks4Snacks merged 2 commits into
mainfrom
hacks4snacks/stableflowidentity

Conversation

@Hacks4Snacks

Copy link
Copy Markdown
Owner

feat(authoring): versioned manifest with pages, geometry, and stable flow identity

What changed

tmforge apply was not idempotent. Applying one manifest twice produced models that
tmforge diff reported as 4 added / 4 removed flows, with 0 of 18 finding ids matching.
Element ids were already derived from aliases; page and connector ids were minted fresh
with Guid.NewGuid().

Four slices, all on the manifest path:

  1. Stable identity — page and connector ids are now derived, not minted. New optional
    flows[].alias; alias-less objects fall back to a structural key. Aliases and structural
    keys use separate GUID namespaces (tmforge-alias: / tmforge-structural:) so they
    cannot collide, plus a post-build count guard.
  2. Envelope + geometry — optional schema/version on the manifest, validated against
    the raw JSON before deserializing. Optional x/y/width/height on boundaries and
    elements, emitted by export --geometry (opt-in).
  3. Pages — optional pages: [{alias, name}] plus page on boundaries and elements.
    A flow may not cross pages; an unknown page reference is refused, not defaulted.
  4. Flow targetingset --id and remove --id resolve a flow by its alias.

Why

The finding id is {ruleId}:{diagram}:{target}:{occurrence}, so an unstable page GUID moved
every finding, not just flow-targeted ones. That defeated ANA-001's stable identity, made
tmforge analysis diff report 18 resolved + 18 introduced for a no-op re-apply, and orphaned
threat-register triage. Manifests are the reviewable authoring surface, so this is the path
where identity has to hold.

Behaviour changes reviewers should see

  • apply now rejects a document whose schema is not tmforge-manifest. Anything
    feeding it other JSON will fail loudly instead of silently coercing.
  • AuthoringSupport.RekeyComponent / RekeyConnector now throw when the id is absent
    (was a silent no-op, which hid a real multi-page bug). All call sites verified.
  • Geometry is opt-in. The concise round trip changes 3 boundary crossings on the sample
    model; that is pre-existing and only measured here, and --geometry is the way out.
    Recorded in docs/cli-reference.md and in the Extract overload's <remarks>.

@Hacks4Snacks Hacks4Snacks linked an issue Jul 29, 2026 that may be closed by this pull request
7 tasks
@Hacks4Snacks
Hacks4Snacks merged commit e454416 into main Jul 29, 2026
10 checks passed
@Hacks4Snacks
Hacks4Snacks deleted the hacks4snacks/stableflowidentity branch July 29, 2026 23:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[AUTH-001] Versioned declarative geometry and flow identity

1 participant