← Back to directory

knowledge.md

architecture/knowledge.md · 17.3 KB · 2026-11-02 12:48

Knowledge

Status: current architectural direction, 2026-09-11; implementation remains unverified unless evidenced separately. Owner: first-class knowledge, institutional memory, and the Knowledge Engine responsibility. Examples describe conceptual contracts, not committed storage fields or implemented features.

Canonical Prerequisites

Scope and Invariants

Knowledge is first-class business information, not an attachment to AI and not merely a collection of searchable files. It retains what a business knows, why it acts, and what experience has taught it across people and applications. Useful knowledge need not fit an ordinary structured property to deserve identity, relationships, ownership, or history. All persistent/addressable knowledge, source references, configuration, and classifications use the universal model. Their type definitions are also addressable objects; knowledge does not establish a second foundational schema. Knowledge participates in the connected Business Graph alongside people, orders, products, workflows, and decisions. Scalar text and nested metadata remain valid typed values where independent identity is unnecessary. An engine is a reusable execution responsibility, not a requirement for a dedicated service, class, or database. The Knowledge Engine manages knowledge meaning and stewardship; it does not own all platform search.

The settled Knowledge capability assembles existing Objects, Relationships, Assertions, Documents, Events, provenance, Policies, Definitions, external observations, AI-generated proposals and human Decisions. It makes that material discoverable, contextual and usable without creating a separate knowledge data universe. Final D10 approves all six principles represented here.

Knowledge, learning and reusable patterns are higher-level layers over Data, Workflow, Logic and their ordinary relationships. They do not introduce a Knowledge, Learning or Network semantic role. A pattern remains derived, attributable and subject to authority; its recognition does not silently create a platform Definition or replace the source objects and evidence from which it was derived.

Knowledge Forms

Supported conceptual forms include text, documents, notes, policies, procedures, explanations, decisions, and experience. They also include observations, learned preferences, historical information, contextual information, and external references. A procedure can describe the human reasoning behind a process without itself being an executable workflow. A policy document can explain a Policy object without every sentence becoming an executable Rule. A service technician's account can relate to Equipment, a Service Contract, and a past service outcome. Brand guidance such as "use typography on a solid background, not over an image" can remain explanatory knowledge. When enforcement is needed, an approved structured constraint may be related to that guidance rather than replacing its rationale. Customer-specific knowledge and company-wide knowledge differ in applicability and access, not foundational representation.

Sources, Interpretation and Context

A Document is an information source, not automatically authoritative knowledge. It can contain facts, assertions, instructions, opinions, Policies, historical information and contradictions. Preserve the chain Information -> interpretation -> Assertion/Object/Relationship -> provenance and standing -> contextual knowledge. Importing or extracting text does not make every sentence true, applicable or executable.

Knowledge use accounts for Business, object, relationship, time, scope, applicability, provenance, epistemic standing and authority context. It must answer not only what is known, but what applies here, why it is believed, where it came from and its current standing. Graph assertion applicability controls scope; accepted or verified information is not universally applicable.

Identity -> authorised context -> relevant knowledge -> presentation/reasoning is the governed path through Retrieval. Graph connectivity alone never makes knowledge retrievable. This applies equally to human users, workflows and optional AI.

Metadata and Relationships

The model must support the following concepts where applicable; this table is not a mandatory flat record layout.

| Concept | Contract | | --- | --- | | Identity and type | Stable address and meaningful classification, validated through the type definition. | | Title and content | Human-readable identification and the actual account, explanation, or referenced material. | | Source and provenance | Origin, acquisition context, transformations, and links back to supporting material. | | Author and owner | Distinguish who supplied the information from who stewards its use and review. | | Creation and update dates | Record knowledge handling without confusing it with when the statement applies. | | Status | Make its review/publication/withdrawal standing inspectable without inventing a universal status list. | | Effective date | Express applicability in time under the canonical temporal model. | | Review and expiry dates | Support stewardship and time-sensitive use; absence is not perpetual validity. | | Confidence | Where meaningful, retain an assessment and its basis, not a substitute for authority. | | Permissions | Govern access to content, relationships, sources, and derived representations. | | Business relationships | Identify the people, products, projects, policies, or activities to which it applies. | | Knowledge relationships | Connect supporting, explanatory, conflicting, related, or superseding accounts as permitted by relationship types. |

Applicability can be narrower than ownership: a business-owned procedure may apply to one product or site. Source-document identity, knowledge identity, and an associated Policy identity must remain distinguishable. Relationships carry their own meaning and provenance under the business-model contract, not informal filename conventions. Historical metadata follows Time and Events; this document does not prescribe retention or automatic deletion on expiry.

Provenance and Authority

Preserve distinctions among company policy, approved documentation, user-entered knowledge, observed behaviour, imported information, inferred information, and AI-generated suggestions. These are meaningful source/standing distinctions, not a fixed globally ordered authority ladder. Approval, confidence, source reliability, and applicability are separate dimensions. A highly confident inference is not thereby company policy; an approved document can still be outdated for a particular date. An imported statement remains attributable to its external source even when indexed or reformatted internally. Extracted text is derived from a source; a summary is an interpretation, not an identical copy of that source. AI-generated information must retain its generated/proposed provenance and must not become authoritative merely by being saved. Conflicting accounts remain distinguishable and reviewable; retrieval must not silently select the most fluent, newest or highest-confidence account as truth. Challenge, rejection, supersession and resolution change standing or operative use without erasing the original Assertion and provenance. Who may approve knowledge or resolve policy conflict is governed by Identity and Governance, not by an extraction engine.

For example, Document A reports a client has 10 employees; later Document B reports 14. Preserve both Assertions, their sources and temporal contexts. Applicable Policy/governance determines current use; the newer source does not silently overwrite the earlier claim or rewrite a past Action's evidence.

The same rule applies when sources disagree about a Business itself. For example, external or public information, or an assertion by another Business, may report that Business B has 34 employees, while information supplied through an appropriate User associated with that Business and the relevant authority relationship reports 21. Preserve both Assertions with their source, standing, scope, temporal context and causal relationships. A deterministic derivation may select the Business-authoritative information for a particular current calculation where the applicable authority and Policy allow it, but it must not destructively replace the 34-employee assertion or treat the result as a generic verified flag. Assertions by other businesses, external/public information, Idiosyncrasy-derived information and assertions by the Business remain distinguishable even when they contribute to the same derived view.

Corrections, supersession, changed authority or changed applicability may invalidate or change a derived output and require an attributable recalculation or new revision. They do not rewrite the historical evidence, erase the earlier derivation or collapse provenance into verified/unverified. The resulting conclusion remains a derivation from retained facts and evidence, not a new independent source of truth.

AI can consume knowledge and produce proposed interpretations: summaries, extracted Assertions, classifications, connections, contradictions, missing-information observations, relationship proposals and authorised answers. AI owns that assistance boundary. AI proposes -> governance/validation -> authoritative model; AI says it does not mean it is true. The same human-operated knowledge path remains available without AI.

For product presentation, knowledge and derived business information should be distinguishable as Fact, Calculated, Inferred, Suggested or Unknown where those qualifications are meaningful. These are epistemic and presentation distinctions grounded in source, provenance, authority, applicability, evidence and uncertainty; they are not a new universal Type enum or a substitute for the relevant domain lifecycle. A calculation may be deterministic without being an externally confirmed fact, an inference may be useful without being authoritative, and a suggestion or unknown must not be presented as settled business truth.

Primary views may summarize the qualification, while deeper inspection should expose its basis, supporting evidence, source, provenance, confidence or limitation and whether human confirmation is required. Views and content owns the presentation depth; this document owns the standing and provenance distinction.

Knowledge Engine Contract

Inputs include authorised human notes, documents, imported references, observations, and explicitly identified proposals. Actions include capture, extraction, classification, association, review support, and maintaining explainable source relationships. Outputs include typed knowledge objects, linked source references, stewardship information, and material available to Retrieval. Extraction/index preparation may use non-AI tools; semantic processing is optional and must not become an access prerequisite. Changes should be explainable through canonical events/history, including actor, source, and affected knowledge where appropriate. Extraction failure must not be presented as successful understanding of a document. Unavailable sources, incomplete extraction, conflicting evidence, expired applicability, and denied access are distinct conditions to surface. The document can remain available for authorised human inspection even when machine extraction is unsupported. Physical files, extraction workers, indexes, and secret handling belong to implementation decisions, not an alternate knowledge universe.

Structured Preference and Explanation

Structured example: Customer.preferred_contact_method = telephone. Knowledge example: "John prefers telephone because he is rarely at his desk and normally responds immediately when called." The property supports deterministic filtering or workflow selection; the explanation preserves context and reasoning. Neither is an adequate replacement for the other when both are useful. Repeated observations may support: "This preference has been repeatedly observed. Convert it into a structured customer property?" The path is: unstructured observation -> knowledge -> repeated pattern -> suggested structure -> structured business data. That is a proposal path, not permission to infer and write a preference without review or policy checks. Analytics and evolution owns the improvement loop; governance owns approval and Objects and Types owns new-property validity. The originating observations remain linked so a future user can inspect why the structured preference exists.

Pricing Policy PDF: Seven-Step Case

1. A user uploads the company's pricing-policy PDF; an addressable Document object represents the source under Views and content. 2. The Knowledge Engine extracts content and prepares it for indexing through Retrieval, retaining extraction/source association and any limitations. 3. An addressable knowledge item is associated with the pricing Policy and relevant products, services, or other applicability objects. 4. Source and provenance are recorded, distinguishing the uploaded document, extracted account, author/owner, and approval standing. 5. Optional AI can answer questions using authorised retrieved knowledge; users must also be able to find and read it without AI. 6. Workflow rules can reference the policy where appropriate, but prose must not silently become executable pricing logic; the applicable rule needs valid structured meaning and governance. 7. When the policy changes, the old knowledge remains historically identifiable, with applicability and changes interpreted by Time and Events rather than overwritten into an unexplained current answer.

This preserves the original seven-step case without promising a PDF parser, indexing service, or policy execution implementation. The final step requires historical explainability, not an invented immutable-storage or event-sourcing mechanism.

Positive and Negative Examples

Positive: a technician reads an approved procedure, sees its source and review date, and links a field observation to a service outcome. Positive: an authorised user finds the pricing PDF and its explanation with AI disabled, then requests review of contradictory advice. Negative: placing all business knowledge only in a provider's conversation history loses platform ownership and no-AI access. Negative: assigning a high confidence score to an AI summary and treating it as approved pricing policy conflates confidence with authority. Negative: duplicating the same policy as unrelated CRM, CMS, and automation records disconnects the shared model. Negative: converting all notes into anonymous customer fields loses knowledge identity, explanation, and source relationships.

Implementation Gates

Knowledge semantics are settled. The initial mechanism stores typed Assertions and source references with explicit scope, standing and revision history, retrieved structurally without AI. Manual source capture is sufficient for the first workflow; automated PDF extraction and semantic indexes are later implementation depth, not missing architecture. The pricing-policy case remains a broader acceptance example, not a claim of an installed parser.

Acceptance checks: capture and retrieve knowledge without AI; inspect all applicable metadata; trace a derived account to its source; refuse unauthorised access; distinguish approved policy from generated advice; demonstrate the seven-step case's historical linkage. Implementation architecture, Security and operations, and Implementation status own mechanisms and evidence, not this conceptual contract.

Source Lineage

Source map owns the section-level ledger and documentation ownership decisions govern canonical changes. Preserved sources: 01 product and principles, inherent growing knowledge; 02 technical architecture, sections 6-8; 03 engines and MVP, knowledge workflow and human-operated-first intent. 00 combined handoff carries the corresponding combined material; older UI Structure guidance contributes the typography-note example, not a fixed application sitemap.