@principal-ai/subsystems-react 0.38.0 → 0.39.0

package/src/graphify/construct.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from 'bun:test';
 import type { GraphifyEdge, GraphifyNode } from './types';
-import { inferConstructFromGraphify, constructsMatch } from './construct';
+import {
+	inferConstructFromGraphify,
+	constructsMatch,
+	resolveConstructMatch,
+} from './construct';
 
 function node(
 	id: string,
@@ -106,3 +110,59 @@ describe('constructsMatch', () => {
 		expect(constructsMatch('function', 'class')).toBe(false);
 	});
 });
+
+describe('resolveConstructMatch', () => {
+	test('structural match is enough (no augmentation)', () => {
+		expect(resolveConstructMatch('function', 'function')).toEqual({
+			match: true,
+		});
+	});
+
+	test('plain mismatch without augmentation stays a hard failure', () => {
+		expect(resolveConstructMatch('function', 'class')).toEqual({
+			match: false,
+		});
+	});
+
+	test('unknown without augmentation is unconfirmed, not a mismatch', () => {
+		expect(resolveConstructMatch('store', 'unknown')).toEqual({ match: null });
+	});
+
+	test('accepted augmentation confirms a claim Graphify infers differently', () => {
+		expect(resolveConstructMatch('store', 'function', 'store')).toEqual({
+			match: true,
+			augmentedBy: 'store',
+		});
+	});
+
+	test('accepted augmentation confirms a claim Graphify leaves unknown', () => {
+		expect(resolveConstructMatch('interface', 'unknown', 'interface')).toEqual({
+			match: true,
+			augmentedBy: 'interface',
+		});
+	});
+
+	test('augmentation only confirms its own claim, not a different one', () => {
+		expect(resolveConstructMatch('store', 'function', 'module')).toEqual({
+			match: false,
+		});
+		expect(resolveConstructMatch('store', 'unknown', 'module')).toEqual({
+			match: null,
+		});
+	});
+
+	test('blank augmentation is ignored', () => {
+		expect(resolveConstructMatch('store', 'function', '  ')).toEqual({
+			match: false,
+		});
+	});
+
+	test('external / missing claimed still short-circuits to match', () => {
+		expect(resolveConstructMatch('external', 'function')).toEqual({
+			match: true,
+		});
+		expect(resolveConstructMatch(undefined, 'unknown')).toEqual({
+			match: true,
+		});
+	});
+});

package/src/graphify/construct.ts

@@ -118,3 +118,36 @@ export function constructsMatch(
 	if (TYPE_FAMILY.has(claimed)) return inferred === 'type';
 	return claimed === inferred;
 }
+
+export interface ConstructCheckOutcome {
+	/** true = confirmed, false = known mismatch, null = unconfirmed (needs agent). */
+	match: boolean | null;
+	/** Confirming construct from an accepted augmentation, when that is what confirmed it. */
+	augmentedBy?: string;
+}
+
+/**
+ * Resolve a claimed construct against Graphify's inferred construct, allowing an
+ * accepted, agent-confirmed augmentation to stand in for Graphify when it is
+ * silent (`unknown`) or when it disagrees.
+ *
+ * Graphify's inferred construct is a *structural hint*, never ground truth: its
+ * vocabulary (`class | function | method | type | module | unknown`) has no
+ * `store` or `custom_entity`, and a call-style accessor label biases it to
+ * `function`. When source-reading confirms the model's claim, that confirmation
+ * (recorded as an accepted augmentation) wins over the hint.
+ */
+export function resolveConstructMatch(
+	claimed: string | undefined,
+	inferred: InferredGraphifyConstruct,
+	augmentedConstruct?: string | null,
+): ConstructCheckOutcome {
+	const aug = augmentedConstruct?.trim();
+	if (!claimed || claimed === 'external') return { match: true };
+	const augConfirms = !!aug && aug === claimed;
+	if (inferred === 'unknown') {
+		return augConfirms ? { match: true, augmentedBy: aug } : { match: null };
+	}
+	if (constructsMatch(claimed, inferred)) return { match: true };
+	return augConfirms ? { match: true, augmentedBy: aug } : { match: false };
+}

package/src/graphify/index.ts

@@ -61,8 +61,13 @@ export {
 export type {
 	InferredGraphifyConstruct,
 	InferConstructFromGraphifyResult,
+	ConstructCheckOutcome,
+} from './construct';
+export {
+	inferConstructFromGraphify,
+	constructsMatch,
+	resolveConstructMatch,
 } from './construct';
-export { inferConstructFromGraphify, constructsMatch } from './construct';
 export type {
   GraphifyInferredSignature,
   ClaimedSignature,

package/src/index.ts

@@ -62,6 +62,7 @@ export {
   symbolLabelVariants,
   inferConstructFromGraphify,
   constructsMatch,
+  resolveConstructMatch,
   extractNamedTypes,
   extractGraphifySignature,
   compareSignatures,