onto-mcp 0.3.0

package/.onto/domains/palantir-foundry/logic_rules.md

@@ -0,0 +1,172 @@
+---
+version: 3
+last_updated: "2026-03-31"
+source: manual
+status: established
+---
+
+# Palantir Foundry Domain — Logic Rules
+
+## Object Type Definition Rules
+
+- Every Object Type must have a primary_key defined. An Object Type without a primary_key cannot uniquely identify instances, making Link Type connections impossible
+- If Properties with the same name within an Object Type are defined with different types, it is a contradiction. Resolve by: (a) renaming one Property to distinguish meaning, or (b) extracting as Shared Property per conciseness_rules.md Section 1 criteria
+- An Object Type's description and its properties must describe the same subject. If the description says "Order" but the properties contain only attributes unrelated to orders, it is a contradiction
+- Enum values must be mutually exclusive (ME). A single instance must not be able to hold two Enum values simultaneously
+
+## Link Type Rules
+
+- The direction of a Link Type (source -> target) must match the business meaning. In "Order has Payment," Order is the source and Payment is the target
+- Cardinality must match actual business rules. If "1 order = 1 payment," then one-to-one; if "1 order = N payments," then one-to-many. Cardinality errors break data integrity
+- Multiple Link Types with different meanings may exist for the same source-target pair. In such cases, each Link Type's meaning must be distinguishable
+
+## Change Classification Rules
+
+- 변경은 두 개의 직교축으로 분류된다: Impact Severity (non_breaking / breaking_minor / breaking_major)와 Lifecycle Intent (immediate / deprecation). Impact Severity와 Lifecycle Intent는 직교축이다. 단일 변경에 두 축의 값이 동시에 부여된다
+- Impact Severity 값은 상호 배타적(ME)이다. 단일 변경은 non_breaking, breaking_minor, breaking_major 중 정확히 하나의 값을 가진다
+- breaking_major is not a superset of breaking_minor. Each classification is determined by independent criteria (impact scope, degree of compatibility breakage)
+- Changing a Property type (e.g., String -> Integer) is always breaking_major + immediate. This is because existing data requires conversion
+- Adding an enum value is breaking_minor + immediate. This is because existing code may not handle the new value
+- Removing an enum value is breaking_major + deprecation. This is because existing data may be using that value; grace period is required before removal
+
+## Governance Rules
+
+- Approval authority level is determined by Impact Severity. Lifecycle Intent가 deprecation인 경우 추가 승인 요건이 적용된다. Approval cannot proceed without both axes classified
+- Changes that directly affect operational metrics require additional executive approval regardless of Impact Severity or Lifecycle Intent. (Ref: domain_scope.md "Approval Authority")
+- Deprecation (Lifecycle Intent) must include a grace period. Deprecation without a grace period is functionally identical to immediate removal and violates the obligation to provide advance notice to integrated systems
+
+## Data Layer Rules
+
+- Lower layers (Master Data) do not reference upper layers (Transaction, Derived). Reverse references create circular dependencies that prevent guaranteed data update ordering
+- Derived Data must be traceable back to source records in the Transaction and Master layers. If tracing back is impossible, auditing is impossible
+- Master Data changes propagate to all upper layers. Therefore, Master Data changes have the widest impact scope and tend to be classified as breaking_major
+
+## Temporal and Ordering Rules
+
+[관찰→참여] Action execution and Rule evaluation follow deterministic ordering. Unpredictable ordering breaks transactional guarantees. (Ref: Palantir Action Types Overview)
+
+- Rule evaluation within an Action is sequential. Later rules on the same property override earlier ones. If the final value depends on evaluation order and the order is not intentional, this is a latent conflict
+- When a webhook is configured as writeback, it executes before other rules. If the webhook fails, all changes are cancelled — no partial commits occur. This is a simplified saga pattern: external system confirmation is a precondition for ontology mutation
+- Function-Backed Actions execute asynchronously relative to the caller. The caller receives a confirmation that the Action was submitted, not that it completed. Design consuming code to handle eventual consistency, not immediate state change
+- Workflow Rule triggers (event-driven Actions) execute after the triggering event commits. A Rule triggered by "Property X changed" observes the committed value, not an intermediate value. Chained Rules (Rule A triggers event -> Rule B fires) execute sequentially in commit order
+
+## Constraint Conflict Patterns
+
+[관찰→참여] Constraint conflicts arise when independently valid rules produce contradictions when combined. Detection requires cross-rule analysis, not single-rule inspection.
+
+### Precondition-Postcondition Conflicts
+
+- If an Action Type's submission criteria (precondition) and its ontology rules (postcondition) contradict each other, that Action is non-executable. Example: submission criteria requires status = "active" but the rule sets status = "closed" — the next invocation of the same Action on the same object will always fail
+- If a postcondition creates a state that violates an invariant defined on the Object Type (e.g., setting a required Property to null), the Action commits but produces an invalid object. Validate postcondition states against Object Type constraints at design time
+
+### Permission-Action Authorization Conflicts
+
+- [관찰→참여] Marking (mandatory, AND-evaluated, restricts access) and role-based Permission (discretionary, expands access) operate in opposite directions. A user with the correct role but missing a required Marking cannot execute the Action. Conflicts arise when Action authorization checks role only and ignores Marking — the Action appears authorized but data access is denied at runtime. (Ref: Palantir Markings docs)
+- If an Action modifies an Object protected by a Marking that the Action's executor does not possess, the Action fails at execution time, not at definition time. Validate that the Action's expected executors hold all required Markings
+
+### Concurrent Action Race Conditions
+
+- If the postconditions of Action Types that can execute simultaneously on the same Object conflict, there is a race condition risk. Example: Action A sets priority = "high" while Action B sets priority = "low" on the same Object
+- Resolution: (a) define Object-level locking via submission criteria (check version/timestamp), or (b) design Actions so that concurrent execution on the same Object is impossible (sequential Workflow), or (c) accept last-write-wins semantics and document this explicitly
+
+### Marking AND Logic vs Permission OR Logic
+
+- [관찰→참여] Multiple Markings on a resource are AND-evaluated: a user must hold all Markings. Multiple role grants are OR-evaluated: any one sufficient role grants access. When both mechanisms apply to the same resource, the effective access is: (any role grants access) AND (all Markings are held). Misunderstanding this interaction produces false expectations about who can access what
+
+### Schema-Level Constraint Declaration
+
+[참여] Constraints belong at the schema level (ontology definition), not at the application level. When constraints are defined in consuming applications instead of the ontology, different applications may enforce different rules, producing inconsistent data.
+
+- Value Type constraints (regex, range, enum, uniqueness)는 온톨로지 정의에서 선언적으로 정의되어야 한다. 애플리케이션 코드에서 정의하면 소비자마다 다른 규칙이 적용될 수 있다
+- 온톨로지에서 선언된 constraint는 모든 소비 경로(OSDK, API, UI)에 일관되게 적용되어야 한다. 특정 소비 경로에서만 검증하는 것은 불완전한 제약이다
+- Constraint 변경은 영향 범위 분석이 필요하다. regex 패턴 변경은 기존 데이터의 유효성을 무효화할 수 있으므로 breaking_minor 이상으로 분류한다
+
+## Data Integrity Rules
+
+[관찰→참여] The ontology sits atop physical data. Schema mismatches between the ontology definition and the backing data produce silent errors or runtime failures. (Ref: Palantir Data Integration docs)
+
+- Backing Dataset schema must be consistent with Object Type definition. If the Object Type declares a Property of type Integer but the Backing Dataset column is String, queries may return incorrect results or fail. Verify type alignment after Pipeline transforms and before ontology binding
+- Writeback Dataset captures user edits as a separate layer from the Backing Dataset. If Writeback Dataset schema diverges from the Object Type definition (e.g., after a Property type change), existing writeback records become unreadable. Property type changes require Writeback Dataset migration
+- Source-writeback separation must be maintained: the Backing Dataset (source) is never directly modified by Actions. All user mutations are recorded in the Writeback Dataset. Violating this separation breaks the audit trail and rollback capability. Cross-reference: structure_spec.md "Data Integration Structural Requirements"
+
+## Pipeline Quality Rules
+
+[관찰→참여] Data pipelines follow a staged quality progression. Each stage has a distinct purpose, and skipping stages introduces quality gaps that compound downstream.
+
+- 파이프라인은 Raw → Clean → Transform의 3단계를 따른다. Raw는 소스 시스템 원본, Clean은 기본 정제(타입 정렬, null 처리, 중복 제거), Transform은 사용 사례별 변환이다
+- Clean에서 Transform으로 가는 중간 변환 단계는 항상 존재해야 한다. Clean에서 직접 Ontology에 바인딩하면 사용 사례별 변환 로직이 바인딩에 섞여 유지보수가 어렵다
+- 네이밍 규칙: Dataset/Column 이름은 snake_case, 고유 부분(distinctive portion)을 이름 앞에 배치, 약어 사용 금지, 번호 증분(dataset1, dataset2) 금지
+- 각 파이프라인 단계의 출력 Dataset은 독립적으로 검증 가능해야 한다. Clean 단계 출력이 올바른지 확인하지 않고 Transform으로 진행하면, 오류의 원인 추적이 어렵다
+
+## Codegen Logic
+
+[참여] Codegen rules are defined in structure_spec.md "Codegen Output Structure (SSOT)." This section defines the logical inference and detection rules that operate on that structure. It does not redefine generated file layout, type naming conventions, or subset generation principles.
+
+### Type Inference Rules
+
+- Object Type -> TypeScript interface: each Property becomes a readonly field. The generated type is the contract between ontology definition and application code. If a Property is nullable in the ontology, the generated field type includes `| undefined`
+- Link Type -> reference type with direction encoded in the name. The generated type enforces cardinality at the type level: one-to-one produces a single reference, one-to-many produces an array
+- Enum -> union type with literal values. The set of literal values is exhaustive. Adding a value requires regeneration; consuming code that does not handle the new value produces a compile error (this is the intended detection mechanism)
+
+### Breaking Change Detection Logic
+
+- Schema change -> type regeneration -> compile errors in referencing code. This converts runtime errors into compile-time errors. The number of compile errors equals the impact scope of the change
+- Property type change (e.g., String -> Integer) produces type mismatch errors at every usage site. This is always breaking_major
+- Property removal produces "property does not exist" errors. This is breaking_major + deprecation (grace period required)
+- New required Property (non-nullable without default) produces errors in every Action that creates the Object Type without providing the new value
+
+## Multi-Ontology Consistency Rules
+
+[관찰→참여] In multi-ontology environments, consistency across ontology boundaries is maintained through Interface contracts and Shared Properties. Direct cross-ontology references without these mechanisms destroy ontology independence.
+
+- An Object Type that implements an Interface must include all Properties defined by that Interface. Partial implementation is a contradiction. Cross-reference: structure_spec.md "Multi-Ontology Connection Structure"
+- Changing the type of a Shared Property triggers breaking_major for all referencing Object Types across all ontologies that use that Shared Property. Impact scope analysis must span ontology boundaries
+- Cross-references between ontologies must be made only through Interface or Shared Property. Direct references (Object Type A in Ontology 1 directly links to Object Type B in Ontology 2) create tight coupling that prevents independent ontology evolution
+- Interface compliance verification: when an Object Type claims to implement an Interface, verify that (a) all Interface Properties exist with matching types, (b) all Interface Link Type Constraints are satisfied, and (c) the Object Type does not redefine an Interface Property with a different type
+
+## AI Agent Authorization Rules
+
+[관찰→참여] AI agents operating on the ontology are subject to the same authorization model as human users, plus additional constraints to prevent autonomous mutations.
+
+- AI 에이전트의 데이터 접근 범위는 호출한 사용자의 접근 범위를 초과할 수 없다. Marking과 Permission이 동일하게 적용된다. AI 에이전트에게 별도의 확장 권한을 부여하면 privilege escalation 경로가 생긴다
+- AI 에이전트가 제안한 ontology 변경(Object 생성/수정/삭제, Action 실행)은 Branch Proposal을 통해 사람의 검토를 거쳐야 한다. 직접 Main에 커밋하는 것은 거버넌스 우회이다
+- AI 에이전트가 Action을 실행할 때, Action Type의 submission criteria(precondition)가 AI 에이전트에게도 동일하게 적용된다. AI가 precondition을 우회하는 것은 허용되지 않는다
+- [관찰→참여] Ontology-Augmented Generation(OAG): AI 에이전트에게 컨텍스트를 제공할 때, 텍스트 문서가 아닌 온톨로지 객체(Object의 Property와 Link)를 주입한다. 구조화된 데이터는 해석의 여지가 적어 할루시네이션을 줄인다
+
+## Resource Status Logic
+
+[관찰→참여] Ontology resources follow a lifecycle that governs their availability and stability guarantees. Status transitions are unidirectional within the standard path and affect all dependent resources.
+
+### Status Lifecycle (5-stage)
+
+| Stage | Meaning | Allowed Transitions |
+|-------|---------|---------------------|
+| Draft | Under construction, not yet available to consumers | -> Experimental |
+| Experimental | Available for testing, no stability guarantees | -> Stable, -> Deprecated |
+| Stable | Production-ready, breaking changes require full governance | -> Deprecated |
+| Deprecated | Scheduled for removal, grace period active | -> Retired |
+| Retired | Removed from active ontology, retained in history | (terminal) |
+
+- Backward transitions (e.g., Stable -> Experimental) are prohibited. If a Stable resource needs fundamental redesign, deprecate it and create a new resource starting at Draft
+- The Draft -> Stable shortcut is prohibited. All resources must pass through Experimental to verify consumer compatibility before receiving stability guarantees
+
+### Hierarchical Cascade Rules
+
+- If a parent Object Type's status transitions to Deprecated, all child Object Types (connected via Link Types where the parent is the source) must be evaluated for deprecation. Children that have no other active parent remain functional but lose their dependency anchor
+- An Experimental parent cannot contain Stable children. The stability guarantee of a child cannot exceed the stability guarantee of its parent. If a child needs to be Stable, its parent must first transition to Stable
+- Shared Property status constrains referencing Object Types: a Deprecated Shared Property forces all referencing Object Types to plan migration to an alternative Property within the grace period
+
+## External References
+
+1. Palantir Action Types & Rules — rule evaluation order, webhook transaction guarantees, submission criteria (Ref: Palantir Action Types Overview)
+2. Palantir Markings & Object Security Policies — mandatory access control, AND-evaluation, Marking propagation (Ref: Palantir security docs)
+3. Palantir Data Integration — Pipeline, Backing Dataset, Writeback Dataset, schema consistency (Ref: Palantir Data Integration docs)
+4. Palantir OSDK — codegen pipeline, type inference, subset generation (Ref: Palantir developer docs)
+
+## Related Documents
+- concepts.md — definitions of terms used in each rule (Action Type, Marking, Backing Dataset, codegen, etc.)
+- dependency_rules.md — dependency direction rules, Pipeline data flow
+- structure_spec.md — structural required elements, Codegen Output Structure (SSOT)
+- domain_scope.md — three-layer architecture scope, change classification definitions
+- competency_qs.md — questions this logic must be able to answer
+- conciseness_rules.md — entity-relation ratio thresholds

package/.onto/domains/palantir-foundry/structure_spec.md

@@ -0,0 +1,291 @@
+---
+version: 4
+last_updated: "2026-03-31"
+source: manual
+status: established
+---
+
+# Palantir Foundry Domain — Structure Specification
+
+## Object Type Required Elements
+
+Every Object Type must include:
+- `display_name`: User-facing display name
+- `primary_key`: Unique identifier Property
+- `description`: Business meaning description (1-2 sentences)
+- `properties`: At least one Property
+- `data_source`: Data origin source (if undetermined, state "TBD")
+
+## Property Required Elements
+
+- `name`: Attribute name (English, snake_case)
+- `type`: Data type (String, Integer, Decimal, Date, Boolean, Enum, Timestamp, Geopoint, and others per concepts.md)
+- `description`: Business meaning description
+- `nullable`: Whether optional (true/false)
+
+## Link Type Required Elements
+
+- `source`: Origin Object Type
+- `target`: Destination Object Type
+- `cardinality`: one-to-one, one-to-many, or many-to-many
+- `description`: Business meaning of the relationship
+
+## Action Type Required Elements
+
+[관찰→참여] Every Action Type must include:
+- `parameters`: Input definitions with value source (from parameter, object parameter property, static value, current user/time)
+- `preconditions`: Rules applied before execution — Ontology Rules (8 types: create/modify/delete objects, create/delete links, function rule, interface-based operations) + Side Effect Rules (2 types: notification rules, webhook rules)
+- `postconditions`: Expected state after successful execution
+- `side_effects`: External effects (notifications, webhook calls). When a webhook is configured as writeback, it executes before other rules — failure cancels all changes
+- `affected_object_types`: List of Object Types modified by the Action
+
+Rule evaluation order: sequential. Later rules on the same property override earlier ones.
+
+## Function Required Elements
+
+[관찰→참여] Every Function must include:
+- `input_types`: Parameter types (ontology Objects or primitive values)
+- `return_type`: Output type
+- `purity`: Must be declared read-only (no state changes). Functions correspond to Query in CQRS. If state changes are needed, use Action Type instead
+
+## Workflow and Rule Required Elements
+
+[관찰→참여] Workflows and Rules require:
+- `trigger_condition`: Event or state that initiates execution (e.g., object creation, property value change, schedule)
+- `action_binding`: Which Action Type(s) the Workflow/Rule invokes
+- `frequency`: Execution frequency (one-time, recurring, event-driven)
+
+Workflow Rules trigger Actions based on events — distinct from Action rules, which define what happens inside an Action.
+
+## Enum Required Elements
+
+[관찰→참여] Every Enum must include:
+- `name`: Enum type name (PascalCase)
+- `description`: Business meaning and usage context
+- `values`: List of allowed values (each with label and description)
+- `default_value`: (optional) Default value when not explicitly set
+- `deprecated_values`: (optional) Values no longer recommended, with migration guidance
+
+## Interface Required Elements
+
+[관찰→참여] Every Interface must include:
+- `name`: Interface name (PascalCase)
+- `description`: Shared behavior or contract this Interface represents
+- `required_properties`: List of Properties that implementing Object Types must provide
+- `implementing_object_types`: Reference to Object Types that implement this Interface
+
+## Shared Property Required Elements
+
+[관찰→참여] Every Shared Property must include:
+- `name`: Property name (English, snake_case)
+- `type`: Data type
+- `description`: Business meaning description
+- `owning_ontology`: Ontology that defines and maintains this Property
+- `consuming_object_types`: List of Object Types that use this Shared Property
+
+## Permission Structure
+
+[관찰→참여] Foundry applies Mandatory Access Control (Marking) where security travels with data — derived resources inherit the restriction automatically. (Ref: Palantir Markings docs)
+
+- **Marking hierarchy**: Marking Group → Marking → Resource. Multiple Markings are AND-evaluated. Owner permissions cannot remove Markings (requires separate Expand Access privilege)
+- **Mandatory vs Discretionary**: Mandatory (Marking) restricts access, binary all-or-nothing, cannot be overridden by data owners. Discretionary (role-based grants) expands access. They operate in opposite directions
+- **Row/Column/Cell-level security**: Object Security Policy (row-level) + Property Security Policy (column-level) = cell-level security. These policies operate independently from backing datasource permissions
+- **Organization isolation**: Organization defines the boundary for Markings, Permissions, and roles. Cross-organization sharing requires explicit de-identification rules at the property level
+
+## Isolated Element Check
+
+[참여] Every element must be checked for structural connectivity:
+- **Object Type**: Not connected to any Link Type → "isolated entity." Exception: top-level Master Data entities referenced by others are not isolated
+- **Link Type**: References a non-existent Object Type → dangling reference
+- **Action Type**: No `affected_object_types` → orphan action with no observable effect
+- **Function**: Not referenced by any Action Type or application → unused logic
+- **Permission**: References a non-existent Object Type or Property → stale security rule
+- **Interface**: No implementing Object Type → warning: unused contract
+- **Shared Property**: Not consumed by any Object Type → warning: orphan shared property
+- **Enum**: Not referenced by any Property → warning: unused enumeration
+- **Workflow**: No trigger condition binding → warning: workflow will never execute
+- **Rule**: No action binding → warning: rule has no effect
+
+## Connectivity Check
+
+- Object Types within the same data layer (Master/Transaction/Derived) must be traversable via Link Types
+- Cross-layer connections: Transaction -> Master direction. Upper layers reference lower layers; lower layers do not know about upper layers
+
+## Data Integration Structural Requirements
+
+[관찰→참여] Data flows through a staged pipeline before binding to the ontology. (Ref: Palantir Data Integration docs)
+
+```
+Source Systems → Data Connection → Sync → Dataset → Transform (Pipeline) → Ontology
+```
+
+- **Pipeline → Backing Dataset binding**: Every Object Type must declare at least one Backing Dataset
+- **Backing Dataset vs Virtual Table**: Backing Dataset = persistent copy with version history and lineage. Virtual Table = compute-on-demand, no storage. Choice depends on audit requirements, latency tolerance, and transformation complexity
+- **Source-writeback separation**: Source data (Backing Dataset) and change data (Writeback Dataset) must be separate — source systems are never directly modified
+
+## Pipeline Quality Structure
+
+[관찰→참여] Data quality is achieved through staged processing, not single-step transformation. (Ref: Palantir Development Best Practices docs)
+
+### Stage Definitions
+
+- **Raw**: Source system data as-is. No transformation applied. Purpose: audit trail and reprocessing capability
+- **Clean**: Basic quality operations applied (type alignment, null handling, deduplication). Starting point for most Foundry activities
+- **Transform**: Use-case-specific transformations. Produces datasets ready for ontology binding
+
+### Naming Conventions
+
+- Dataset/Column names: snake_case (e.g., awesome_dataset, not AwesomeDataset)
+- Distinctive portion first (e.g., order_daily_summary, not daily_summary_order) — prevents truncation in UI dropdowns
+- No abbreviations. No numeric increments (dataset1, dataset2)
+
+### Catalog Organization
+
+```
+/Domain
+  /Subject Area
+    /Entity
+      - gold_<entity>
+      - silver_<entity>
+      - ref_<lookups>
+```
+
+## Multi-Ontology Connection Structure
+
+- Object Types in the Shared Ontology are referenced from Private Ontologies through Interfaces
+- If a cross-reference exists without Interface implementation, it is a structural defect
+
+## Change Management Required Structure
+
+- `change_classification` rules must be defined (non_breaking/breaking_minor/breaking_major/deprecation)
+- `governance.roles` must define at least an Ontology Lead
+- `governance.approval_levels` must map approval authority to each change classification
+
+## Codegen Output Structure (SSOT)
+
+[참여] This section is the Single Source of Truth for codegen implementation rules. Other documents (domain_scope.md, logic_rules.md, dependency_rules.md) reference this section but do not redefine codegen rules.
+
+### Generated File Layout
+
+`generated/types/` — one file per entity category (ObjectTypes.ts, LinkTypes.ts, ActionTypes.ts, Enums.ts). `generated/functions/` — Function signatures. `generated/index.ts` — re-exports for consumer access.
+
+### Type Naming Conventions
+
+| Ontology Entity | Generated Type | Naming Rule |
+|----------------|---------------|------------|
+| Object Type | TypeScript interface | PascalCase (e.g., `interface SalesOrder`) |
+| Property | readonly field | camelCase (e.g., `readonly orderDate: Date`) |
+| Link Type | reference type | PascalCase with direction (e.g., `SalesOrder_To_Customer`) |
+| Enum | union type | PascalCase, literal values (e.g., `type Status = "active" \| "inactive"`) |
+| Action Type | parameter interface | PascalCase (e.g., `ProcessRefundParams`) |
+| Function | function signature | camelCase (e.g., `calculateTotal`) |
+
+### Subset Generation Principle
+
+[관찰→참여] Only the relevant portion of the ontology is generated per application, not the entire ontology — benefiting both performance (linear scaling with ontology shape, not size) and security (no access to unneeded entities). Each application declares which Object Types, Action Types, and Functions it requires; codegen produces types only for the declared subset. (Ref: Palantir OSDK Overview docs)
+
+### Scope-Limited Tokens
+
+[관찰→참여] Generated code uses tokens scoped to the selected ontology subset. Dual-layer security: (1) token scope limits accessible entities, (2) user permissions further restrict data access within that scope. (Ref: Palantir OSDK docs)
+
+### Schema Change Detection
+
+[참여] Schema change → type regeneration → compile errors in referencing code. Re-running codegen after a schema change converts runtime errors into compile-time errors. This pattern applies to any schema-based system.
+
+## Testing Structure
+
+[관찰→참여] Testing validates that the ontology implementation matches its design specification. Three levels of testing address different concerns. (Ref: CodeStrap Operating Model — Foundry Mocks, DAO pattern)
+
+### Platform Abstraction (DAO Pattern)
+
+[관찰→참여] Business logic is isolated from the ontology platform via Data Access Object (DAO) pattern. Foundry-specific operations (Object reads, Action executions) are encapsulated behind function interfaces. This enables:
+- Unit testing with mock implementations (no live platform required)
+- Platform migration without business logic changes
+- Dependency injection for component substitution
+
+### Unit Testing with Mocks
+
+[관찰→참여] Ontology interactions are testable via mock implementations (Foundry Mocks pattern):
+- Mock Object reads return predefined datasets
+- Mock Action executions verify parameter correctness and side effect invocation
+- Mock codegen types verify type compatibility without live ontology
+
+### Integration Testing (Schema Verification)
+
+[참여] Schema consistency between ontology definition and backing data:
+- Backing Dataset column types match Object Type Property types
+- Writeback Dataset schema aligns with current Object Type definition
+- Codegen output compiles without errors against current ontology
+
+### E2E Verification
+
+[참여] End-to-end validation of the complete pipeline:
+- Source → Pipeline (Raw→Clean→Transform) → Ontology binding → codegen → compile
+- Action execution → Writeback Dataset → re-indexing → query verification
+
+## Frontend Integration Structure
+
+[관찰→참여] The ontology-to-UI pipeline extends codegen to the presentation layer, ensuring type safety from schema to screen. (Ref: OSDK v2 React patterns, RESEARCH_NOTES.md Section 12)
+
+### Schema-Type-UI Pipeline
+
+[관찰→참여] The change detection chain extends beyond codegen:
+```
+Ontology Schema → codegen → Generated Types → UI Components
+                                    ↓
+                            Compile errors propagate
+                            to component boundaries
+```
+
+### Polymorphic Component Rendering
+
+[관찰→참여] Ontology Interfaces map to UI component hierarchies:
+- Interface defines the common shape (e.g., ITask with status, assignee)
+- Each implementing Object Type ($objectType field: CodingTask, LearningTask) renders via a distinct sub-component
+- New Object Type implementations are automatically handled if the Interface contract is satisfied
+
+### State Management
+
+[관찰→참여] Ontology-backed applications follow:
+- Context-based authentication (provider pattern) — no global state store required
+- Hook-level caching with SWR (stale-while-revalidate) strategy
+- Real-time subscription for onChange, onError, onOutOfDate events
+
+### OSDK v2 Specifics
+
+[관찰] Foundry OSDK v2 design decisions:
+- Performance scales with ontology shape (metadata), not ontology size (total data)
+- Lazy loading: types loaded at use time, not at initialization
+- Client-code decoupling: library updates do not require SDK regeneration
+- React Hooks: useOsdkObjects (collection), useOsdkObject (single), useLinks (relations)
+
+## Quantitative Thresholds
+
+Thresholds are structural health indicators. Exceeding a threshold requires explicit justification.
+
+| Metric | Threshold | Implication | Action |
+|--------|-----------|-------------|--------|
+| OTs without Link Types | > 10% of total OTs | Structural disconnection | Review per "Isolated Element Check" |
+| Action Type parameters | > 8 parameters | Overly complex action | Split into sub-actions or extract parameter groups |
+| Properties per OT | > 50 properties | Overloaded Object Type | Split into multiple OTs with Link Types |
+| Orphan Actions | > 0 | No affected_object_types | Remove or bind to Object Types |
+| Enum values | > 25 values | May indicate missing OT | Evaluate promotion to Object Type |
+| Pipeline depth | > 5 transform stages | Debugging complexity | Consolidate intermediate transforms |
+| Pipeline stages without Clean | > 0 | Quality gap | Add Clean stage between Raw and Transform |
+
+Cross-reference: Entity-relation ratio thresholds → conciseness_rules.md. Change classification → domain_scope.md "Change Classification."
+
+## External References
+
+1. Palantir OSDK Overview — type generation, subset generation principle, token scoping (Ref: Palantir developer docs)
+2. Palantir Action Types & Rules — 8 ontology rules + 2 side effect rules, webhook transaction guarantees (Ref: Palantir Action Types Overview)
+3. Palantir Markings & Object Security Policies — mandatory access control, row/column/cell-level security (Ref: Palantir security docs)
+4. Palantir Data Integration — Pipeline, Backing Dataset, Virtual Table, Writeback Dataset (Ref: Palantir Data Integration docs)
+
+## Related Documents
+- domain_scope.md — three-layer architecture scope, codegen design principles
+- concepts.md — term definitions (Object Type, Action Type, Marking, Pipeline, codegen, etc.)
+- logic_rules.md — logic rules; references "Codegen Output Structure" for codegen logic
+- dependency_rules.md — dependency directions; references "Codegen Output Structure" for codegen dependencies
+- competency_qs.md — questions this structure must be able to answer
+- conciseness_rules.md — entity-relation ratio thresholds, minimum granularity criteria