garrytan/gbrainmarkdown explorer
garrytan/gbrainmaster
Repository

Scalar-source Backlink Validation Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make backlink validation compare exact (source_id, slug) endpoint identities while preserving existing scalar, unscoped, and federated link-read semantics.

Architecture: Enrich every engine link-read row with the source identity of its joined from, to, and visible origin pages. Pass the validated page's scalar or federated scope into validator context; the backlink validator scopes its initial read consistently, groups targets by exact identity, and accepts only an exact reverse endpoint pair. SQL predicates remain unchanged, so trusted scalar cross-source visibility and federated all-endpoint containment remain intact.

Tech Stack: TypeScript, Bun test, PGLite, PostgreSQL/postgres.js.

Global Constraints

  • Use strict red-before-green TDD with duplicate slugs across sources.
  • Preserve unscoped historical reads, scalar near-endpoint scoping, scalar explicit cross-source visibility, federated all-endpoint containment, and sourceIds precedence.
  • Keep PostgreSQL and PGLite projections in parity.
  • Do not change schema or conditional-write conflict semantics.
  • Keep deployment, restart, migration, and push actions outside the implementation tasks; a separately authorized release workflow may perform them after verification.
  • Capture full test output to files before inspecting it.

Files:

  • Modify: test/writer.test.ts

Interfaces:

  • Consumes: backLinkValidator.validate(PageValidationContext) and source-qualified putPage/addLink.

  • Produces: regressions for wrong-source reverse rejection, exact reverse acceptance, cross-source pair acceptance, and exact target deduplication.

  • Step 1: Add the minimal failing duplicate-slug regression

Create default and team-x copies of the origin and target, add (team-x, origin) -> (team-x, target) plus the wrong reverse (team-x, target) -> (default, origin), validate with sourceId: 'team-x', and require one warning.

  • Step 2: Run the focused test and verify RED
bun test test/writer.test.ts -t "wrong-source reverse" > "$TEMP/backlink-red.txt" 2>&1

Expected: assertion failure because current slug-only validation returns zero findings.

  • Step 3: Add the remaining behavioral regressions after the first red is recorded

Add tests proving that the exact reverse clears the warning, a legitimate cross-source forward/reverse pair passes, and two destinations sharing one slug but differing by source are validated independently.

Task 2: Expose exact endpoint identity from both engines

Files:

  • Modify: src/core/types.ts:1204-1229
  • Modify: src/core/postgres-engine.ts:3021-3124
  • Modify: src/core/pglite-engine.ts:2941-3037
  • Modify: test/get-page-federated-scope.test.ts:187-246,289-306
  • Modify: test/e2e/multi-source-bug-class.test.ts:184-205
  • Modify: test/e2e/engine-parity.test.ts:813-875

Interfaces:

  • Produces: Link.from_source_id: string, Link.to_source_id: string, and Link.origin_source_id?: string | null.

  • Preserves: getLinks(slug, { sourceId?, sourceIds? }) and getBacklinks(...) filtering semantics.

  • Step 1: Add engine-contract assertions before implementation

Assert scalar cross-source rows expose beta -> default, federated rows expose only in-grant endpoint IDs, sourceIds still beats scalar sourceId, and an out-of-grant origin has both origin_slug and origin_source_id null.

  • Step 2: Run the focused contract tests and verify RED
bun test test/get-page-federated-scope.test.ts test/e2e/multi-source-bug-class.test.ts > "$TEMP/link-identity-red.txt" 2>&1

Expected: source-ID assertions fail because fields are absent.

  • Step 3: Extend Link and project IDs without changing predicates

Use this additive contract:

export interface Link {
  from_slug: string;
  from_source_id: string;
  to_slug: string;
  to_source_id: string;
  link_type: string;
  context: string;
  link_source?: string | null;
  origin_slug?: string | null;
  origin_source_id?: string | null;
  origin_field?: string | null;
}

In all six branches per engine, project:

f.source_id AS from_source_id,
t.source_id AS to_source_id,
o.source_id AS origin_source_id

Keep every WHERE and grant-aware origin LEFT JOIN unchanged.

  • Step 4: Re-run contract tests and verify GREEN

Use the same command and require all focused tests to pass.

Task 3: Validate exact reverse identities and propagate scope

Files:

  • Modify: src/core/output/writer.ts:89-96,240-318
  • Modify: src/core/output/post-write.ts:36-41,73-118
  • Modify: src/core/output/validators/back-link.ts:24-47
  • Modify: src/core/operations.ts:1227-1246
  • Modify: test/post-write-lint.test.ts:67-130

Interfaces:

  • Produces: optional PageValidationContext.sourceId and sourceIds, with sourceIds taking precedence.

  • runPostWriteLint(..., opts) accepts the same optional scope and loads the validated page through it.

  • Step 1: Add a post-write nested-read regression and verify RED

Validate a non-default page with a wrong-source reverse via runPostWriteLint(..., { force: true, noLog: true, sourceId: 'team-x' }); require a backlink warning.

  • Step 2: Implement minimal scope propagation

Add sourceId?/sourceIds? to validation context and lint options. Load pages using sourceIds when non-empty, otherwise scalar sourceId. Pass the same scope into nested validators. In the put-page success hook, call lint with the already-resolved write source ID.

  • Step 3: Implement exact backlink matching

Initial outbound reads use the validation scope. Deduplicate rows by all four endpoint identity fields so every distinct expected origin remains represented even when targets share a source-qualified identity. Read each target using the federated grant when present, otherwise the target's exact scalar source. Accept only a row matching all four endpoint fields of the expected reverse.

  • Step 4: Run writer and post-write tests and verify GREEN
bun test test/writer.test.ts test/post-write-lint.test.ts > "$TEMP/backlink-green.txt" 2>&1

Expected: all tests pass, including the recorded false-negative.

Task 4: Verify PostgreSQL/PGLite parity and final scope

Files:

  • Modify: test/e2e/engine-parity.test.ts:813-875
  • Verify: all files above

Interfaces:

  • Consumes: exact endpoint fields and unchanged filtering semantics.

  • Produces: parity evidence for scalar cross-source and federated reads.

  • Step 1: Compare complete endpoint tuples across engines

Compare sorted tuples containing from_source_id, from_slug, to_source_id, to_slug, origin_source_id, and origin_slug for scalar and federated fixtures.

  • Step 2: Run focused PGLite/source-isolation tests
bun test test/writer.test.ts test/post-write-lint.test.ts test/get-page-federated-scope.test.ts test/e2e/multi-source-bug-class.test.ts > "$TEMP/backlink-focused.txt" 2>&1

Expected: exit 0.

  • Step 3: Run PostgreSQL parity when the test database is available
bun test test/e2e/engine-parity.test.ts -t "federated sourceIds" --timeout=300000 > "$TEMP/backlink-parity.txt" 2>&1

Expected: exit 0; if the configured test database is unavailable, report the exact environmental blocker rather than claiming parity execution.

  • Step 4: Typecheck and inspect the final diff
bun run typecheck > "$TEMP/backlink-typecheck.txt" 2>&1

Expected: exit 0. Then run git diff --check and confirm no version, schema, migration, deployment, or conditional-write files changed.

Continue exploring589 Markdown documents in the local repository