@world-engines/ladybug-bridge 0.1.0-alpha.0

package/dist/view-access-policy.d.ts

@@ -0,0 +1,153 @@
+export declare const VIEW_ACCESS_POLICY_SCHEMA_VERSION: 2;
+export declare const VIEW_ACCESS_POLICY_ROOT_SUBJECT_ID: "view_policy_root_v2";
+export type ViewAccessMode = "inherit" | "deny" | "read" | "read_write";
+export type EffectiveViewAccessMode = Exclude<ViewAccessMode, "inherit">;
+export type ViewAccessPolicySubjectKind = "root" | "node" | "attr" | "edge";
+export type ViewAccessAttributeOwnerAddress = {
+    readonly kind: "node";
+    readonly nodeId: string;
+} | {
+    readonly kind: "edge";
+    readonly sourceNodeId: string;
+    readonly destinationNodeId: string;
+    readonly relationKind: string;
+};
+/**
+ * Typed, canonical address of one policy subject. Attribute paths are always
+ * segmented; a key containing `.` is therefore distinct from nested keys.
+ * Vectors are intentionally absent: their policy subject is the owning node.
+ */
+export type ViewAccessPolicyAddress = {
+    readonly kind: "root";
+} | {
+    readonly kind: "node";
+    readonly nodeId: string;
+} | {
+    readonly kind: "attr";
+    readonly owner: ViewAccessAttributeOwnerAddress;
+    readonly path: readonly string[];
+} | {
+    readonly kind: "edge";
+    readonly sourceNodeId: string;
+    readonly destinationNodeId: string;
+    readonly relationKind: string;
+};
+/** A runtime target that can be reduced to exactly one policy address. */
+export type ViewAccessPolicyTarget = Exclude<ViewAccessPolicyAddress, {
+    readonly kind: "root";
+}> | {
+    readonly kind: "vector";
+    readonly nodeId: string;
+    readonly vectorSpace: string;
+};
+/**
+ * A policy subject's parent is structural only. Graph relations and `$ref`
+ * values are deliberately absent from this contract and must never be
+ * translated into `structuralParentId` by callers.
+ */
+export type ViewAccessPolicySubject = {
+    readonly id: string;
+    readonly kind: ViewAccessPolicySubjectKind;
+    readonly address: ViewAccessPolicyAddress;
+    readonly structuralParentId: string | null;
+    readonly mode: ViewAccessMode;
+};
+export declare const VIEW_ACCESS_POLICY_DENY_ROOT: ViewAccessPolicySubject;
+export type ViewAccessPolicySnapshot = {
+    readonly schemaVersion: typeof VIEW_ACCESS_POLICY_SCHEMA_VERSION;
+    /** Subjects are sorted by canonical UTF-8 byte order. */
+    readonly subjects: readonly ViewAccessPolicySubject[];
+    /** SHA-256 of the canonical policy bytes. Exactly 32 octets. */
+    readonly policySha256: readonly number[];
+};
+/** Compact database only: the complete schema-v2 policy is derived from graph-v5. */
+export type DerivedGraphViewAccessPolicy = {
+    readonly schemaVersion: 3;
+    readonly derivation: "graph-v5";
+    readonly policySha256: readonly number[];
+};
+export declare function derivedGraphViewAccessPolicy(snapshot: ViewAccessPolicySnapshot): DerivedGraphViewAccessPolicy;
+export type ViewAccessResolution = {
+    readonly mode: EffectiveViewAccessMode;
+    readonly decidedBySubjectId: string;
+};
+export type AttributeOwnerKind = "node" | "edge";
+/** Stable typed identity; callers must not collapse attribute paths to dotted strings. */
+export type TypedLadybugTarget = {
+    readonly kind: "node";
+    readonly nodeId: string;
+} | {
+    readonly kind: "attribute";
+    readonly ownerKind: AttributeOwnerKind;
+    readonly ownerId: string;
+    readonly path: readonly string[];
+} | {
+    readonly kind: "edge";
+    readonly edgeId: string;
+    readonly sourceNodeId: string;
+    readonly destinationNodeId: string;
+} | {
+    readonly kind: "vector";
+    readonly nodeId: string;
+    readonly vectorSpace: string;
+};
+export type OverlayLeafProvenance = "baseline" | "overlay_created";
+export type CanonicalWalLeafChange = {
+    readonly target: TypedLadybugTarget;
+    /** Full segmented canonical path to one changed leaf. Empty paths are rejected. */
+    readonly leafPath: readonly string[];
+    readonly provenance: OverlayLeafProvenance;
+};
+export type OverlayLeafAccessInput = {
+    readonly target: TypedLadybugTarget;
+    /** Full segmented canonical path of the leaf being considered. */
+    readonly leafPath: readonly string[];
+    /** Provenance must describe this exact target and leaf, not its containing row. */
+    readonly provenance: OverlayLeafProvenance;
+    readonly policyMode: EffectiveViewAccessMode;
+    readonly canonicalWalChanges: readonly CanonicalWalLeafChange[];
+};
+/** Canonical Ladybug relation identity shared with the Rust store. */
+export declare function canonicalLadybugRelationId(sourceNodeId: string, destinationNodeId: string, relationKind: string): string;
+/** Domain-separated stable identity of one typed policy address. */
+export declare function deriveViewAccessPolicySubjectId(address: ViewAccessPolicyAddress): string;
+/** Constructs a bound non-root subject; the root is the exported fixed constant. */
+export declare function createViewAccessPolicySubject(address: Exclude<ViewAccessPolicyAddress, {
+    readonly kind: "root";
+}>, structuralParentId: string, mode: ViewAccessMode): ViewAccessPolicySubject;
+/**
+ * Reduces a runtime target to its policy address. Vector spaces cannot carry
+ * policy overrides and always resolve through their owning node.
+ */
+export declare function viewAccessPolicyAddressForTarget(target: ViewAccessPolicyTarget): Exclude<ViewAccessPolicyAddress, {
+    readonly kind: "root";
+}>;
+/**
+ * Stable target-to-subject mapping used by every query and mutation gate.
+ * Vector-space names are validated but deliberately do not influence the id:
+ * every vector is governed by the policy subject of its owning node.
+ */
+export declare function deriveViewAccessPolicySubjectIdForTarget(target: ViewAccessPolicyTarget): string;
+/** Sorts, validates and seals one canonical fail-closed policy snapshot. */
+export declare function sealViewAccessPolicy(subjects: readonly ViewAccessPolicySubject[]): ViewAccessPolicySnapshot;
+/** Validates canonical ordering, graph invariants and digest. */
+export declare function validateViewAccessPolicy(snapshot: ViewAccessPolicySnapshot): void;
+/**
+ * Resolves the closest explicit mode on the subject's structural parent chain.
+ * A chain with only `inherit` modes ends at the sealed fixed-deny root.
+ */
+export declare function resolveViewAccessMode(subjects: readonly ViewAccessPolicySubject[], subjectId: string): ViewAccessResolution;
+export declare function isViewReadable(mode: EffectiveViewAccessMode): boolean;
+export declare function isViewWritable(mode: EffectiveViewAccessMode): boolean;
+/**
+ * Edge access never inherits through its endpoints. Endpoints are gates only:
+ * both must be readable; writing additionally requires the edge itself to be
+ * explicitly/effectively `read_write`.
+ */
+export declare function resolveEdgeViewAccessMode(edgeMode: EffectiveViewAccessMode, sourceMode: EffectiveViewAccessMode, destinationMode: EffectiveViewAccessMode): EffectiveViewAccessMode;
+/**
+ * Makes a leaf-scoped overlay decision. Canonical WAL visibility is granted
+ * only for an exact typed target and changed-leaf path; neither ancestor-prefix
+ * matches, a changed sibling nor another owner can make baseline data visible.
+ */
+export declare function resolveOverlayLeafViewAccessMode(input: OverlayLeafAccessInput): EffectiveViewAccessMode;