@hivelore/core 0.30.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hivelore contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+<p align="center">
+  <a href="https://github.com/Doucs91/hivelore">
+    <img src="https://raw.githubusercontent.com/Doucs91/hivelore/main/packages/vscode/media/logo.svg" alt="Hivelore logo" width="96" />
+  </a>
+</p>
+
+# @hivelore/core
+
+> Internal library — policy, memory, anchor, and enforcement primitives for Hivelore.
+
+This package is consumed by `@hivelore/cli` and `@hivelore/mcp`. You do **not** need to install it directly unless you are building a custom Hivelore integration or extending the tool.
+
+---
+
+## What this package provides
+
+### Enforcement primitives
+
+Core owns the durable types and local runtime markers used by Hivelore policy gates:
+
+- `.ai/haive.config.json` config loading/merging
+- strict enforcement settings (`requireBriefingFirst`, session recap, memory verification, stale-decision blocking)
+- briefing markers under `.ai/.runtime/enforcement/briefings/`
+- anchor verification for stale decisions and gotchas
+- path resolution for project, memory, runtime, and module directories
+
+### Memory schema (Zod)
+
+A single source of truth for the memory frontmatter format:
+
+```typescript
+import { MemoryFrontmatterSchema, MemoryTypeSchema, MemoryScopeSchema } from "@hivelore/core";
+
+// Types
+type MemoryType  = "convention" | "decision" | "gotcha" | "architecture" | "glossary" | "attempt";
+type MemoryScope = "personal" | "team" | "module";
+type MemoryStatus = "draft" | "proposed" | "validated" | "stale" | "rejected" | "deprecated";
+```
+
+Each memory file is a Markdown file with YAML frontmatter:
+
+```yaml
+---
+id: 2025-01-15-gotcha-flyway-strict
+scope: team
+type: gotcha
+status: validated
+anchor:
+  paths:
+    - src/main/resources/db/migration
+  symbols: []
+tags: [flyway, database, migration]
+domain: database
+author: dev@example.com
+created_at: "2025-01-15T10:30:00.000Z"
+verified_at: "2025-01-20T08:00:00.000Z"
+related_ids:
+  - 2025-01-15-attempt-modify-existing-migration
+expires_when: null
+stale_reason: null
+---
+
+# Flyway strict mode — never modify existing migrations
+
+...
+```
+
+### Parser / Serializer
+
+```typescript
+import { parseMemory, serializeMemory, buildFrontmatter, newMemoryId } from "@hivelore/core";
+
+// Parse a memory file
+const memory = parseMemory(rawMarkdown);
+
+// Serialize back to disk
+const markdown = serializeMemory(memory);
+
+// Build a new frontmatter object
+const frontmatter = buildFrontmatter({
+  type: "gotcha",
+  slug: "flyway-strict",
+  scope: "team",
+  paths: ["src/main/resources/db/migration"],
+  tags: ["flyway"],
+});
+
+// Generate a canonical ID
+const id = newMemoryId("gotcha", "flyway-strict"); // "2025-01-15-gotcha-flyway-strict"
+```
+
+### Anchor verification
+
+```typescript
+import { verifyAnchor } from "@hivelore/core";
+
+const result = await verifyAnchor(memory, { projectRoot: "/path/to/project" });
+// result.stale          — true if anchor paths or symbols no longer exist
+// result.reason         — human-readable explanation
+// result.possibleRenames — files with the same basename found elsewhere (rename detection)
+```
+
+### Literal search
+
+```typescript
+import { tokenizeQuery, literalMatchesAllTokens, literalMatchesAnyToken } from "@hivelore/core";
+
+const tokens = tokenizeQuery("flyway migration strict");
+const matches = memories.filter(({ memory }) => literalMatchesAllTokens(memory, tokens));
+```
+
+### Token budgeting
+
+```typescript
+import { allocateBudget, estimateTokens, truncateToTokens } from "@hivelore/core";
+
+const slices = allocateBudget(
+  [
+    { key: "context", text: projectContext, weight: 3, mode: "head" },
+    { key: "memories", text: memoriesText, weight: 4, mode: "head" },
+  ],
+  8000, // max tokens
+);
+```
+
+### Usage / confidence tracking
+
+```typescript
+import { loadUsageIndex, trackReads, deriveConfidence, isDecaying, DECAY_DAYS } from "@hivelore/core";
+
+const index = await loadUsageIndex(paths);
+const usage = getUsage(index, memoryId);
+const confidence = deriveConfidence(frontmatter, usage);
+// confidence: "authoritative" | "trusted" | "provisional" | "low" | "stale"
+
+const decaying = isDecaying(usage, frontmatter.created_at); // not read in >90 days
+```
+
+### Path helpers
+
+```typescript
+import { findProjectRoot, resolveHaivePaths, memoryFilePath } from "@hivelore/core";
+
+const root  = findProjectRoot();            // Walks up from cwd looking for .ai/ or .git/
+const paths = resolveHaivePaths(root);
+// paths.memoriesDir, paths.teamDir, paths.personalDir, paths.moduleDir, paths.projectContext, ...
+
+const file = memoryFilePath(paths, "team", "2025-01-15-gotcha-flyway", undefined);
+```
+
+---
+
+## Memory file format
+
+Memories are plain Markdown files stored in `.ai/memories/<scope>/` and committed to git:
+
+```
+.ai/
+└── memories/
+    ├── personal/     # Local only — not committed
+    ├── team/         # Committed — shared across the team
+    └── module/
+        └── payments/ # Scoped to a specific module
+```
+
+The frontmatter schema:
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | string | Canonical ID: `YYYY-MM-DD-<type>-<slug>` |
+| `scope` | enum | `personal` · `team` · `module` |
+| `type` | enum | `convention` · `decision` · `gotcha` · `architecture` · `glossary` · `attempt` |
+| `status` | enum | `draft` · `proposed` · `validated` · `stale` · `rejected` · `deprecated` |
+| `anchor.paths` | string[] | File paths this memory is anchored to (staleness detection) |
+| `anchor.symbols` | string[] | Symbol names this memory is anchored to |
+| `anchor.commit` | string? | Git commit SHA at time of creation |
+| `tags` | string[] | Free-form tags |
+| `domain` | string? | Business domain (e.g. `payments`) |
+| `related_ids` | string[] | IDs of related memories (auto-expanded in `get_briefing`) |
+| `created_at` | ISO date | Creation timestamp |
+| `verified_at` | ISO date? | Last anchor verification timestamp |
+| `stale_reason` | string? | Why the memory was marked stale |
+| `expires_when` | string? | Condition under which this memory should be deprecated |
+
+---
+
+## License
+
+MIT