al-sem 0.0.1

package/src/model/expression.ts

@@ -0,0 +1,98 @@
+// src/model/expression.ts
+// Structured, tree-sitter-derived classification of one expression — used for
+// CallSite arguments and RecordOperation field-arguments. Detectors read this
+// instead of re-shredding `text` with regex.
+//
+// The `kind` mirrors tree-sitter-al's expression node types verbatim, so the
+// builder in `src/index/expression-from-node.ts` is a 1:1 map; "other" is the
+// fallback for unmodeled expression shapes (binary expressions, parenthesized
+// expressions, subscripts, etc.). Detectors only need a handful of kinds for
+// their literal/identity decisions — the helpers below encode those rules
+// once so consumers never branch on `kind` strings directly.
+
+/** Grammar-aligned expression kinds. Closed enum; `"other"` is the catch-all. */
+export type ExpressionKind =
+	| "string_literal"
+	| "integer"
+	| "decimal"
+	| "boolean"
+	| "identifier"
+	| "quoted_identifier"
+	| "qualified_enum_value"
+	| "database_reference"
+	| "unary_expression"
+	| "member_expression"
+	| "call_expression"
+	| "parenthesized_expression"
+	| "other";
+
+export interface ExpressionInfo {
+	kind: ExpressionKind;
+	/** Source-faithful text including any surrounding quotes / signs. */
+	text: string;
+	/**
+	 * Consumer-friendly value:
+	 *   - string_literal:        contents between the single quotes
+	 *   - quoted_identifier:     contents between the double quotes
+	 *   - integer / decimal:     decimal text (unchanged)
+	 *   - boolean:               "true" / "false"
+	 *   - identifier:            the bare name
+	 *   - qualified_enum_value:  RHS of `::` (the `value` field)
+	 *   - database_reference:    RHS of `::` (the `table_name` field, unquoted)
+	 * Undefined for member_expression / call_expression / unary_expression /
+	 * parenthesized_expression / other — those need full sub-tree inspection
+	 * the model layer deliberately omits.
+	 */
+	value?: string;
+	/** LHS of `::` for qualified_enum_value / database_reference. */
+	qualifier?: string;
+	/** RHS of `::` for qualified_enum_value / database_reference (unquoted for db-ref). */
+	member?: string;
+}
+
+/**
+ * A string-like literal — either single-quoted (`'val'`) or
+ * double-quoted-identifier (`"val"`). D4 and D22 want this: they treat
+ * either form as "the same key" for comparison after stripping the quotes.
+ * The `value` field is the unquoted contents in both cases.
+ */
+export function isStringLikeLiteral(info: ExpressionInfo): boolean {
+	return info.kind === "string_literal" || info.kind === "quoted_identifier";
+}
+
+/**
+ * A loop-invariant literal — string, number, boolean, or qualified enum value.
+ * D18 uses this to decide whether a `SetRange` / `SetFilter` value is constant
+ * across iterations. Identifiers and calls are NOT literals (we cannot prove
+ * loop-invariance without dataflow). Unary `+`/`-` over a numeric literal is
+ * literal too — `expressionInfoFromNode` sets `value` on a `unary_expression`
+ * iff its operand is `integer` / `decimal`, so the value-set check is the
+ * predicate.
+ */
+export function isLiteralExpression(info: ExpressionInfo): boolean {
+	switch (info.kind) {
+		case "string_literal":
+		case "quoted_identifier":
+		case "integer":
+		case "decimal":
+		case "boolean":
+		case "qualified_enum_value":
+			return true;
+		case "unary_expression":
+			return info.value !== undefined;
+		default:
+			return false;
+	}
+}
+
+/**
+ * Resolve a field-name argument to its lowered, unquoted form for
+ * case-insensitive comparison against `Field.name`. Quoted identifiers
+ * (`"Document No."`) and string literals (`'Discount Amount'`) yield their
+ * inner value; plain identifiers (`Quantity`) yield their text. Returns the
+ * source text lowercased as a safe fallback for anything else.
+ */
+export function unquotedFieldName(info: ExpressionInfo): string {
+	if (info.value !== undefined) return info.value.toLowerCase();
+	return info.text.toLowerCase();
+}

package/src/model/finding.ts

@@ -0,0 +1,110 @@
+import type { Evidence } from "./graph.ts";
+import type { SourceAnchor } from "./identity.ts";
+import type { CallsiteId, LoopId, ObjectId, OperationId, RoutineId, TableId } from "./ids.ts";
+
+export interface FixOption {
+	description: string;
+	safety: "high" | "medium" | "low";
+}
+
+export interface EvidenceStep {
+	routineId: RoutineId;
+	operationId?: OperationId;
+	callsiteId?: CallsiteId;
+	loopId?: LoopId;
+	sourceAnchor: SourceAnchor;
+	note: string;
+}
+
+export interface FindingConfidence {
+	level: "confirmed" | "likely" | "possible";
+	cappedBy?: (
+		| "unresolved-call"
+		| "opaque-callee"
+		| "dynamic-dispatch"
+		| "parse-incomplete"
+		| "version-mismatch"
+	)[];
+	evidence: Evidence[];
+}
+
+export interface Finding {
+	id: string;
+	rootCauseKey: string;
+	detector: string;
+	title: string;
+	rootCause: string;
+	severity: "critical" | "high" | "medium" | "low" | "info";
+	confidence: FindingConfidence;
+	primaryLocation: SourceAnchor;
+	evidencePath: EvidenceStep[];
+	/**
+	 * Additional supporting traces for the SAME terminal anchor. Set only on detectors
+	 * that emit one Finding per (terminal-op | publisher) regardless of how many
+	 * in-loop ancestor routines reach it (D1, D2). The canonical, max-severity path
+	 * is in `evidencePath`; this carries the others, sorted deterministically.
+	 *
+	 * Absent (undefined) when there's a single reaching path — the common case for
+	 * all other detectors and for most D1/D2 findings.
+	 */
+	additionalPaths?: EvidenceStep[][];
+	affectedObjects: ObjectId[];
+	affectedTables: TableId[];
+	fixOptions: FixOption[];
+	provenance: Evidence[];
+	/** Set in later phases. The primary-app source anchor a developer can act on, when primaryLocation falls in a dependency. */
+	actionableAnchor?: SourceAnchor;
+	/** Set in later phases. Stable edit-survival key used by baselines + SARIF. */
+	fingerprint?: string;
+	/**
+	 * For event-flow detectors (D43/D44/D45). The kind of event whose
+	 * dispatch / multi-subscriber / transitive exposure produced the finding.
+	 * Mirrors EventKind from src/engine/event-flow.ts but kept loose
+	 * (string union) to avoid a model→engine import cycle.
+	 *
+	 * Set to one of: "integration", "business", "internal".
+	 * Absent on non-event-flow findings.
+	 */
+	eventKind?: "integration" | "business" | "internal";
+	/**
+	 * For event-flow detectors. Subset of the event's subscribers that
+	 * live in a different app than the publisher (subscriberAppId !==
+	 * publisherAppId). Sorted RoutineId list. Empty when all subscribers
+	 * are in-app. Absent on non-event-flow findings.
+	 *
+	 * Evidence only — no detector filters on it. Consumers (baselines,
+	 * dashboards, al-perf) may weight findings differently based on
+	 * cross-app subscriber presence.
+	 */
+	crossExtensionSubscribers?: readonly RoutineId[];
+}
+
+export interface Diagnostic {
+	severity: "error" | "warning" | "info";
+	stage: "discover" | "parse" | "symbol-read" | "index" | "resolve" | "summarize" | "detect";
+	message: string;
+	sourceRef?: string;
+}
+
+export interface DetectorStats {
+	detector: string;
+	candidatesConsidered: number;
+	findingsEmitted: number;
+	/** Named skip counters. The well-known fields below are documented for shared
+	 * conventions (`temporaryRecord`, `parseIncomplete`, etc.); detector-specific
+	 * counters are also allowed via the index signature so each detector can name
+	 * its own skip paths (e.g. `nonModifyEvent`, `noPublisherRoutine`). */
+	skipped: {
+		opaqueCallee?: number;
+		dynamicDispatch?: number;
+		parseIncomplete?: number;
+		temporaryRecord?: number;
+		dependencyTerminal?: number;
+		/** Not skipped — downgraded to "info" severity (D1 temp records). */
+		downgradedToInfo?: number;
+		/** Event dispatch edge has no resolvable subscriber routine (D2). */
+		unresolvedSubscriber?: number;
+		other?: number;
+		[counter: string]: number | undefined;
+	};
+}

package/src/model/graph-edge.ts

@@ -0,0 +1,93 @@
+import type { ValueSource } from "./capability.ts";
+import type { SourceAnchor } from "./identity.ts";
+import type { CallsiteId, EventId, ObjectId, OperationId, RoutineId } from "./ids.ts";
+
+/**
+ * Typed graph edges. Per the capability-stack roadmap §3.2, the v2
+ * combined graph's generic call + event-dispatch edges with `uncertainty`
+ * annotations are promoted to a discriminated union. Every propagating
+ * edge is routine-to-routine and carries an anchor for witness
+ * reconstruction.
+ *
+ *  - `direct-call`            resolved bare or member call
+ *  - `object-run-resolved`    Codeunit.Run/Page.Run/Report.Run with
+ *                             resolved target entrypoint — composer walks
+ *                             through `to`
+ *  - `object-run-unresolved`  dispatch where target is dynamic or
+ *                             entrypoint isn't resolved — composer does
+ *                             NOT walk through (no `to`); produces an
+ *                             execute CapabilityFact directly + a coverage
+ *                             reason on the source routine
+ *  - `event-dispatch`         composed publisher→subscriber edge
+ *                             (one per resolved (publisher event,
+ *                             subscriber binding) pair) — composer walks
+ *  - `implicit-trigger`       record op raises a table OnInsert/OnModify/
+ *                             OnValidate/OnDelete trigger
+ *  - `dependency-export`      primary-app routine calls into a
+ *                             dependency-app exported routine
+ *
+ * Permission facts are NOT graph edges; see `src/model/permission.ts`.
+ */
+export type GraphEdgeKind =
+	| "direct-call"
+	| "object-run-resolved"
+	| "object-run-unresolved"
+	| "event-dispatch"
+	| "implicit-trigger"
+	| "dependency-export";
+
+/** Table-trigger kind raised by an implicit-trigger edge. */
+export type TriggerKind = "OnInsert" | "OnModify" | "OnValidate" | "OnDelete" | "OnRename";
+
+export type GraphEdge =
+	| {
+			kind: "direct-call";
+			callsiteId: CallsiteId;
+			from: RoutineId;
+			to: RoutineId;
+			sourceAnchor: SourceAnchor;
+	  }
+	| {
+			kind: "object-run-resolved";
+			callsiteId: CallsiteId;
+			from: RoutineId;
+			to: RoutineId;
+			targetObject: ObjectId;
+			objectType: "Codeunit" | "Page" | "Report";
+			sourceAnchor: SourceAnchor;
+	  }
+	| {
+			kind: "object-run-unresolved";
+			callsiteId: CallsiteId;
+			from: RoutineId;
+			/** Set when the target object is known but the entrypoint isn't. */
+			targetObject?: ObjectId;
+			/** Always set — describes the source of the runtime-resolved target id. */
+			targetIdSource: ValueSource;
+			objectType: "Codeunit" | "Page" | "Report";
+			sourceAnchor: SourceAnchor;
+	  }
+	| {
+			kind: "event-dispatch";
+			from: RoutineId;
+			to: RoutineId;
+			eventId: EventId;
+			publishAnchor: SourceAnchor;
+			subscriberAnchor: SourceAnchor;
+	  }
+	| {
+			kind: "implicit-trigger";
+			from: RoutineId;
+			to: RoutineId;
+			triggerKind: TriggerKind;
+			operationId: OperationId;
+			sourceAnchor: SourceAnchor;
+	  }
+	| {
+			kind: "dependency-export";
+			callsiteId: CallsiteId;
+			from: RoutineId;
+			to: RoutineId;
+			targetAppGuid: string;
+			sourceAnchor: SourceAnchor;
+	  };

package/src/model/graph.ts

@@ -0,0 +1,62 @@
+import type { ParameterSymbol } from "./entities.ts";
+import type { CallsiteId, EventId, ObjectId, OperationId, RoutineId } from "./ids.ts";
+
+export interface Evidence {
+	source: "tree-sitter" | "symbol-package" | "external-source";
+	note?: string;
+}
+
+/** Shared provenance constant for tree-sitter-derived edges and symbols. */
+export const TREE_SITTER_EVIDENCE: Evidence = { source: "tree-sitter" };
+
+export type DispatchKind =
+	| "direct"
+	| "method"
+	| "interface"
+	| "codeunit-run"
+	| "report-run"
+	| "page-run"
+	| "event-dispatch"
+	| "implicit-trigger"
+	| "dynamic"
+	| "unresolved";
+
+export type ResolutionQuality = "resolved" | "maybe" | "unknown" | "opaque";
+
+export interface CallEdge {
+	from: RoutineId;
+	to?: RoutineId; // absent when unresolved
+	callsiteId: CallsiteId;
+	operationId: OperationId;
+	dispatchKind: DispatchKind;
+	resolution: ResolutionQuality;
+	provenance: Evidence[];
+}
+
+export interface EventSymbol {
+	id: EventId;
+	publisherObjectId: ObjectId;
+	publisherRoutineId?: RoutineId;
+	eventName: string;
+	eventKind: "integration" | "business" | "trigger" | "internal" | "unknown";
+	elementName?: string;
+	signatureHash: string;
+	parameters: ParameterSymbol[];
+	provenance: Evidence[];
+}
+
+export interface EventEdge {
+	eventId: EventId;
+	subscriberRoutineId: RoutineId;
+	subscriberAppId: string;
+	skipOnMissingLicense?: boolean;
+	skipOnMissingPermission?: boolean;
+	resolution: "resolved" | "maybe" | "unknown";
+	provenance: Evidence[];
+}
+
+/** The event graph: publisher symbols and subscriber edges. */
+export interface EventGraph {
+	events: EventSymbol[];
+	edges: EventEdge[];
+}

package/src/model/identity.ts

@@ -0,0 +1,81 @@
+import type { ManifestDependency } from "../symbols/app-manifest.ts";
+
+/** A character range in a source file. */
+export interface SourceRange {
+	startLine: number; // 0-based
+	startColumn: number;
+	endLine: number;
+	endColumn: number;
+}
+
+/**
+ * A stable reference to a location in source. The fingerprint hash fields are a SEAM
+ * only in Phase 1 — left undefined; computation is deferred to sub-project D.
+ */
+export interface SourceAnchor {
+	sourceUnitId: string;
+	range: SourceRange;
+	enclosingRoutineId: string;
+	syntaxKind: string;
+	normalizedTextHash?: string;
+	leadingContextHash?: string;
+	trailingContextHash?: string;
+}
+
+export type SourceKind = "workspace" | "app-source" | "symbol-only" | "external-source";
+
+export interface AppIdentity {
+	appGuid: string;
+	publisher: string;
+	name: string;
+	version: string;
+	packageHash?: string;
+	symbolReferenceHash?: string;
+	sourceAggregateHash?: string;
+	sourceKind: SourceKind;
+}
+
+/** Top-level version identity of one analysis run. Keys the cache. */
+export interface ModelIdentity {
+	schemaVersion: string;
+	analyzerVersion: string;
+	grammarVersion: string;
+	symbolReaderVersion: string;
+	createdAt: string;
+	workspace?: { rootHash?: string; appJsonHash?: string };
+	primaryApp?: AppIdentity;
+	apps: AppIdentity[];
+	dependencyGraphHash: string;
+	runtime?: { platform?: string; application?: string; runtime?: string };
+	/**
+	 * Dependencies declared by the primary workspace's app.json (both explicit
+	 * dependencies[] and implicit Microsoft platform-tier entries). Each carries
+	 * the declared MinVersion the user committed to. Used by D17 to detect drift
+	 * against the actually-resolved dependency version stored in apps[].version.
+	 */
+	primaryDependencies?: ManifestDependency[];
+	/**
+	 * App GUIDs (lowercased, sorted) listed in the primary workspace's
+	 * `internalsVisibleTo` array — apps granted access to this app's `internal`
+	 * procedures. Empty/undefined means no external app can reach `internal`, so
+	 * D14 treats them as app-scoped for dead-routine reachability.
+	 */
+	primaryInternalsVisibleTo?: string[];
+	/**
+	 * Phase 1 §4.3 — `roots.config.json` provenance. Populated when the file
+	 * was loaded AND hashed successfully (i.e., `loadRootsConfig` returned a
+	 * `contentHash`). Undefined when the file is missing, when
+	 * `--no-roots-config` / `options.noRootsConfig` skipped loading, or when
+	 * a file-read error prevented hashing (the read error is still surfaced
+	 * via diagnostics). Parse/validation errors that occur AFTER hashing
+	 * keep the field populated so the fingerprint reflects the byte content
+	 * that was attempted.
+	 *
+	 * Whether to surface read-failure as a `rootsConfigReadError?` metadata
+	 * flag is deferred; today the diagnostic is the only signal.
+	 *
+	 * The path is the absolute path that was attempted; consumers may
+	 * workspace-relativize it for stability across machines.
+	 */
+	rootsConfig?: { path: string; contentHash: string };
+}

package/src/model/ids.ts

@@ -0,0 +1,90 @@
+import { sha256OfStrings } from "../hash.ts";
+
+/** Routine kinds — table/page/report triggers are routines, indexed from day one. */
+export type RoutineKind = "procedure" | "trigger" | "event-publisher" | "event-subscriber";
+
+// --- ID string aliases. Opaque outside this module. ---
+export type ObjectId = string; // "{appGuid}/{objectType}/{objectNumber}"
+export type TableId = string; // "{appGuid}/table/{number}"  (physical table)
+export type FieldId = string; // "{tableId}/{fieldNumber}"
+export type KeyId = string; // "{tableId}/key/{index}"
+export type RoutineId = string; // encodes { canonicalKey, modelInstanceId }
+export type CallsiteId = string; // "{routineId}/cs{index}"
+export type LoopId = string; // "{routineId}/loop{index}"
+export type OperationId = string; // "{routineId}/op{index}"
+export type RecordVariableId = string; // "{routineId}/rv/{name}"
+export type EventId = string; // "{publisherObjectId}/event/{eventName}"
+
+/**
+ * Stable across app version bumps when the symbol is semantically the same.
+ * This is the key regression comparison (sub-project D) and profile fusion
+ * (sub-project B) join on.
+ */
+export interface CanonicalRoutineKey {
+	appGuid: string;
+	objectType: string;
+	objectNumber: number;
+	routineKind: RoutineKind;
+	routineName: string;
+	normalizedSignatureHash: string;
+}
+
+export function encodeObjectId(
+	appGuid: string,
+	objectType: string,
+	objectNumber: number,
+): ObjectId {
+	return `${appGuid}/${objectType}/${objectNumber}`;
+}
+
+export function encodeTableId(appGuid: string, tableNumber: number): TableId {
+	return `${appGuid}/table/${tableNumber}`;
+}
+
+export function encodeFieldId(tableId: TableId, fieldNumber: number): FieldId {
+	return `${tableId}/${fieldNumber}`;
+}
+
+export function encodeKeyId(tableId: TableId, keyIndex: number): KeyId {
+	return `${tableId}/key/${keyIndex}`;
+}
+
+/** Order-sensitive, collision-free hash of the canonical key fields. */
+export function encodeCanonicalRoutineKey(key: CanonicalRoutineKey): string {
+	return sha256OfStrings([
+		key.appGuid,
+		key.objectType,
+		String(key.objectNumber),
+		key.routineKind,
+		key.routineName.toLowerCase(),
+		key.normalizedSignatureHash,
+	]);
+}
+
+/** Model-instance-scoped concrete routine identity. */
+export function encodeRoutineId(key: CanonicalRoutineKey, modelInstanceId: string): RoutineId {
+	return `${modelInstanceId}/${encodeCanonicalRoutineKey(key)}`;
+}
+
+export function encodeCallsiteId(routineId: RoutineId, index: number): CallsiteId {
+	return `${routineId}/cs${index}`;
+}
+
+export function encodeLoopId(routineId: RoutineId, index: number): LoopId {
+	return `${routineId}/loop${index}`;
+}
+
+export function encodeOperationId(routineId: RoutineId, index: number): OperationId {
+	return `${routineId}/op${index}`;
+}
+
+export function encodeRecordVariableId(
+	routineId: RoutineId,
+	variableName: string,
+): RecordVariableId {
+	return `${routineId}/rv/${variableName.toLowerCase()}`;
+}
+
+export function encodeEventId(publisherObjectId: ObjectId, eventName: string): EventId {
+	return `${publisherObjectId}/event/${eventName.toLowerCase()}`;
+}

package/src/model/index.ts

@@ -0,0 +1,13 @@
+export * from "./ids.ts";
+export * from "./identity.ts";
+export * from "./entities.ts";
+export * from "./summary.ts";
+export * from "./graph.ts";
+export * from "./finding.ts";
+export * from "./model.ts";
+// Phase 0a additions:
+export * from "./stable-identity.ts";
+export * from "./coverage.ts";
+export * from "./capability.ts";
+export * from "./graph-edge.ts";
+export * from "./permission.ts";

package/src/model/model.ts

@@ -0,0 +1,51 @@
+import type { App, ObjectDecl, Routine, Table } from "./entities.ts";
+import type { GraphEdge } from "./graph-edge.ts";
+import type { CallEdge, EventGraph } from "./graph.ts";
+import type { ModelIdentity } from "./identity.ts";
+import type { CallsiteId, OperationId, RoutineId } from "./ids.ts";
+import type { RootClassification } from "./root-classification.ts";
+
+/** First-class "no silent clean" coverage record. Populated in Phase 2. */
+export interface AnalysisCoverage {
+	sourceUnitsTotal: number;
+	sourceUnitsParsed: number;
+	routinesTotal: number;
+	routinesBodyAvailable: number;
+	routinesParseIncomplete: RoutineId[];
+	opaqueApps: string[];
+	unresolvedCallsites: CallsiteId[];
+	dynamicDispatchSites: OperationId[];
+}
+
+/**
+ * The Phase 1 deliverable: identity + apps + objects + routines (with intraprocedural
+ * features, no summaries) + tables. No call graph, no event graph.
+ */
+export interface SemanticIndex {
+	identity: ModelIdentity;
+	apps: App[];
+	objects: ObjectDecl[];
+	routines: Routine[];
+	tables: Table[];
+}
+
+/** The full model — Phase 2 extends a SemanticIndex with graphs and coverage. */
+export interface SemanticModel extends SemanticIndex {
+	callGraph: CallEdge[];
+	eventGraph: EventGraph;
+	coverage: AnalysisCoverage;
+	/**
+	 * Typed discriminated-union graph edges. Populated by `buildCombinedGraph`
+	 * (Phase 0b-β Task 19). Kinds emitted initially: `direct-call`,
+	 * `object-run-resolved`, `object-run-unresolved`. Event-dispatch and
+	 * implicit-trigger edges are composed in Task 20+.
+	 */
+	typedEdges?: readonly GraphEdge[];
+	/**
+	 * Phase 1 §4.3 — per-routine root classification with provenance.
+	 * Populated by root-classifier (post-summary engine, pre-snapshot
+	 * composition). Empty when no routine qualifies as a root. Routines
+	 * with no qualifying RootKind are NOT in the array.
+	 */
+	rootClassifications: RootClassification[];
+}

package/src/model/permission.ts

@@ -0,0 +1,76 @@
+import type { CapabilityOp } from "./capability.ts";
+import type { CoverageStatus } from "./coverage.ts";
+import type { CallsiteId } from "./ids.ts";
+import type {
+	StableObjectId,
+	StablePermissionSetId,
+	StableRoutineId,
+	StableTableId,
+} from "./stable-identity.ts";
+
+/**
+ * AL permission right set. R/I/M/D apply to TableData; X is execute
+ * for codeunits/pages/reports/xmlports/queries.
+ */
+export type PermissionRight = "R" | "I" | "M" | "D" | "X";
+
+/**
+ * What an AL permission entry targets. `TableData` is the
+ * read/insert/modify/delete pseudo-target; `Table` is the table
+ * definition itself (rare). `System` covers a small set of system
+ * permissions.
+ */
+export type PermissionTargetKind =
+	| "TableData"
+	| "Table"
+	| "Codeunit"
+	| "Page"
+	| "Report"
+	| "XmlPort"
+	| "Query"
+	| "System";
+
+/**
+ * A permission entry from an AL `PermissionSet` object. Materialized at
+ * index time from the workspace and from `.app` symbol packages.
+ *
+ * `scope: "Inherent"` = permissions granted by inherent entitlements (set
+ * via object-level `InherentEntitlements` / `InherentPermissions`
+ * properties). `scope: "Assignable"` = permissions declared in a
+ * `PermissionSet` object that can be assigned to a user.
+ */
+export interface DeclaredPermissionFact {
+	kind: "declared";
+	permissionSet: StablePermissionSetId;
+	target: StableTableId | StableObjectId;
+	targetKind: PermissionTargetKind;
+	rights: PermissionRight[];
+	scope: "Inherent" | "Assignable";
+}
+
+/**
+ * A permission inferred as REQUIRED by a routine's capability cone.
+ * Derived from `CapabilityFact`s on the routine's transitive reachable
+ * set (table read/insert/modify/delete → R/I/M/D on TableData; execute
+ * → X on codeunit/page/report).
+ *
+ * G6 enforcement: every RequiredPermissionFact carries the coverage
+ * status of the underlying cone. Required perms are "may be incomplete"
+ * when the cone is partial — Phase 4 policy must surface this.
+ *
+ * al-sem DOES NOT claim runtime authorization outcomes. RequiredPermissionFact
+ * only says "the reachable code surface implies this permission was
+ * needed at some path"; Phase 4 compares it against DeclaredPermissionFact
+ * sets in scope.
+ */
+export interface RequiredPermissionFact {
+	kind: "required";
+	subject: StableRoutineId;
+	target: StableTableId | StableObjectId;
+	targetKind: PermissionTargetKind;
+	rights: PermissionRight[];
+	derivedFromCapability: { op: CapabilityOp; witnessCallsiteId?: CallsiteId };
+	coverage: CoverageStatus;
+}
+
+export type PermissionFact = DeclaredPermissionFact | RequiredPermissionFact;