@100xprompt/chitta 0.1.0

package/src/arango-graph-provider.ts

@@ -0,0 +1,364 @@
+// Ported from PipesHub `services/graph_db/arango/arango_http_provider.py`
+// (get_accessible_virtual_record_ids + _get_virtual_ids_for_connector +
+//  _get_kb_virtual_ids + _get_user_app_ids).
+//
+// This is the moat. The AQL is preserved verbatim from the source - the eight
+// permission paths (direct / group×2 / org×2 / record-group inheritance×2 /
+// anyone) and the two KB paths (direct / team). Do not "simplify" a path without
+// understanding which access route it represents; each one is a way a user can
+// legitimately reach a record, and dropping one silently denies access while
+// loosening one silently leaks data.
+
+import type { ArangoClient, GraphProvider } from "./provider"
+import type { AccessibleMap, MetadataFilters, RecordDoc, RetrievalFilters, UserDoc } from "./types"
+
+// Arango edge/vertex collection names, matching the source schema.
+const C = {
+  USERS: "users",
+  RECORDS: "records",
+  ANYONE: "anyone",
+  PERMISSION: "permissions",
+  BELONGS_TO: "belongsTo",
+  INHERIT_PERMISSIONS: "inheritPermissions",
+  BELONGS_TO_DEPARTMENT: "belongsToDepartment",
+  BELONGS_TO_CATEGORY: "belongsToCategory",
+  BELONGS_TO_LANGUAGE: "belongsToLanguage",
+  BELONGS_TO_TOPIC: "belongsToTopic",
+} as const
+
+const COMPLETED_STATUS = "COMPLETED"
+
+// Build the optional metadata-facet FILTER lines + their bind vars. Shared by the
+// connector and KB queries so both honor department/category/language/topic facets.
+function buildMetadataFilters(metadataFilters?: MetadataFilters): {
+  clause: string
+  bindVars: Record<string, unknown>
+} {
+  const lines: string[] = []
+  const bindVars: Record<string, unknown> = {}
+  if (metadataFilters) {
+    const facet = (
+      values: string[] | undefined,
+      edge: string,
+      field: string,
+      bindName: string,
+    ) => {
+      if (!values || values.length === 0) return
+      lines.push(`
+        FILTER LENGTH(
+            FOR x IN OUTBOUND record._id ${edge}
+            FILTER x.${field} IN @${bindName}
+            LIMIT 1
+            RETURN 1
+        ) > 0`)
+      bindVars[bindName] = values
+    }
+    facet(metadataFilters.departments, C.BELONGS_TO_DEPARTMENT, "departmentName", "departmentNames")
+    facet(metadataFilters.categories, C.BELONGS_TO_CATEGORY, "name", "categoryNames")
+    facet(metadataFilters.subcategories1, C.BELONGS_TO_CATEGORY, "name", "subcat1Names")
+    facet(metadataFilters.subcategories2, C.BELONGS_TO_CATEGORY, "name", "subcat2Names")
+    facet(metadataFilters.subcategories3, C.BELONGS_TO_CATEGORY, "name", "subcat3Names")
+    facet(metadataFilters.languages, C.BELONGS_TO_LANGUAGE, "name", "languageNames")
+    facet(metadataFilters.topics, C.BELONGS_TO_TOPIC, "name", "topicNames")
+  }
+  return { clause: lines.join("\n"), bindVars }
+}
+
+function rowsToMap(rows: any[]): AccessibleMap {
+  const map: AccessibleMap = {}
+  for (const r of rows ?? []) {
+    if (r && r.virtualRecordId && r.recordId) map[r.virtualRecordId] = r.recordId
+  }
+  return map
+}
+
+export class ArangoGraphProvider implements GraphProvider {
+  constructor(
+    private readonly client: ArangoClient,
+    private readonly log: { error: (m: string, ...a: unknown[]) => void; debug?: (m: string) => void } = {
+      error: () => {},
+    },
+  ) {}
+
+  async getUserByUserId(userId: string): Promise<UserDoc | null> {
+    const rows = await this.client.executeAql(
+      `FOR user IN @@users FILTER user.userId == @userId LIMIT 1 RETURN user`,
+      { userId, "@users": C.USERS },
+    )
+    return rows?.[0] ?? null
+  }
+
+  async getUserApps(userKey: string): Promise<Array<{ _key?: string; id?: string }>> {
+    // Apps the user can reach. Kept as a seam - wire to the source's get_user_apps
+    // traversal. Returning [] means "connectors contribute nothing"; KB paths still run.
+    const rows = await this.client.executeAql(
+      `FOR app IN 1..1 ANY @userKey @@permission
+         FILTER IS_SAME_COLLECTION("apps", app)
+         RETURN app`,
+      { userKey: `${C.USERS}/${userKey}`, "@permission": C.PERMISSION },
+    )
+    return rows ?? []
+  }
+
+  private async getUserAppIds(userId: string): Promise<string[]> {
+    const user = await this.getUserByUserId(userId)
+    if (!user) return []
+    const userKey = user._key ?? user.id
+    if (!userKey) return []
+    const apps = await this.getUserApps(userKey)
+    return apps.map((a) => a._key ?? a.id).filter((x): x is string => Boolean(x))
+  }
+
+  // --- THE moat orchestration: union of connector paths + KB path, deduped. ---
+  async getAccessibleVirtualRecordIds(args: {
+    userId: string
+    orgId: string
+    filters?: RetrievalFilters
+  }): Promise<AccessibleMap> {
+    const { userId, orgId } = args
+    const filters = args.filters ?? {}
+    try {
+      const userAppIds = await this.getUserAppIds(userId)
+      const kbIds = filters.kb
+      const connectorIdsFilter = filters.apps
+      const { kb: _kb, apps: _apps, ...metadataFilters } = filters
+
+      const hasKbFilter = Boolean(kbIds && kbIds.length)
+      const hasAppFilter = Boolean(connectorIdsFilter && connectorIdsFilter.length)
+
+      const tasks: Promise<AccessibleMap>[] = []
+      const connectors = (ids: string[]) =>
+        ids.filter((cid) => !cid.startsWith("knowledgeBase_"))
+
+      if (hasAppFilter && hasKbFilter) {
+        for (const cid of connectors(userAppIds.filter((c) => connectorIdsFilter!.includes(c))))
+          tasks.push(this.getVirtualIdsForConnector(userId, orgId, cid, metadataFilters))
+        tasks.push(this.getKbVirtualIds(userId, orgId, kbIds!, metadataFilters))
+      } else if (!hasAppFilter && hasKbFilter) {
+        tasks.push(this.getKbVirtualIds(userId, orgId, kbIds!, metadataFilters))
+      } else if (!hasAppFilter && !hasKbFilter) {
+        for (const cid of connectors(userAppIds))
+          tasks.push(this.getVirtualIdsForConnector(userId, orgId, cid, metadataFilters))
+        tasks.push(this.getKbVirtualIds(userId, orgId, undefined, metadataFilters))
+      } else {
+        for (const cid of connectors(userAppIds.filter((c) => connectorIdsFilter!.includes(c))))
+          tasks.push(this.getVirtualIdsForConnector(userId, orgId, cid, metadataFilters))
+      }
+
+      if (tasks.length === 0) return {}
+
+      const results = await Promise.allSettled(tasks)
+      const merged: AccessibleMap = {}
+      for (const r of results) {
+        if (r.status !== "fulfilled") {
+          this.log.error(`accessible-ids task failed: ${String(r.reason)}`)
+          continue
+        }
+        // First writer wins per virtualRecordId - mirrors the source's dedup so a
+        // record reachable via several paths resolves to a single recordId.
+        for (const [vid, rid] of Object.entries(r.value)) if (!(vid in merged)) merged[vid] = rid
+      }
+      return merged
+    } catch (e) {
+      this.log.error(`getAccessibleVirtualRecordIds failed: ${String(e)}`)
+      return {}
+    }
+  }
+
+  // The eight permission paths for one connector.
+  private async getVirtualIdsForConnector(
+    userId: string,
+    orgId: string,
+    connectorId: string,
+    metadataFilters?: MetadataFilters,
+  ): Promise<AccessibleMap> {
+    const { clause, bindVars: mdBind } = buildMetadataFilters(metadataFilters)
+    const query = `
+    LET userDoc = FIRST(FOR user IN @@users FILTER user.userId == @userId RETURN user)
+
+    LET directRecords = (
+        FOR record IN 1..1 ANY userDoc._id ${C.PERMISSION}
+            FILTER IS_SAME_COLLECTION("records", record)
+            FILTER record.connectorId == @connectorId
+            FILTER record.indexingStatus == @completedStatus
+            ${clause}
+            RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET groupRecords = (
+        FOR group IN 1..1 ANY userDoc._id ${C.BELONGS_TO}
+            FOR record IN 1..1 ANY group._id ${C.PERMISSION}
+                FILTER IS_SAME_COLLECTION("records", record)
+                FILTER record.connectorId == @connectorId
+                FILTER record.indexingStatus == @completedStatus
+                ${clause}
+                RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET groupRecordsPermissionEdge = (
+        FOR group IN 1..1 ANY userDoc._id ${C.PERMISSION}
+            FOR record IN 1..1 ANY group._id ${C.PERMISSION}
+                FILTER IS_SAME_COLLECTION("records", record)
+                FILTER record.connectorId == @connectorId
+                FILTER record.indexingStatus == @completedStatus
+                ${clause}
+                RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET orgRecords = (
+        FOR org IN 1..1 ANY userDoc._id ${C.BELONGS_TO}
+            FOR record IN 1..1 ANY org._id ${C.PERMISSION}
+                FILTER IS_SAME_COLLECTION("records", record)
+                FILTER record.connectorId == @connectorId
+                FILTER record.indexingStatus == @completedStatus
+                ${clause}
+                RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET orgRecordGroupRecords = (
+        FOR org IN 1..1 ANY userDoc._id ${C.BELONGS_TO}
+            FOR recordGroup IN 1..1 ANY org._id ${C.PERMISSION}
+                FILTER IS_SAME_COLLECTION("recordGroups", recordGroup)
+                FOR record IN 0..2 INBOUND recordGroup._id ${C.INHERIT_PERMISSIONS}
+                    FILTER IS_SAME_COLLECTION("records", record)
+                    FILTER record.connectorId == @connectorId
+                    FILTER record.indexingStatus == @completedStatus
+                    ${clause}
+                    RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET recordGroupRecords = (
+        FOR group IN 1..1 ANY userDoc._id ${C.PERMISSION}
+            FILTER IS_SAME_COLLECTION("groups", group) OR IS_SAME_COLLECTION("roles", group)
+            FOR recordGroup IN 1..1 ANY group._id ${C.PERMISSION}
+                FOR record IN 0..5 INBOUND recordGroup._id ${C.INHERIT_PERMISSIONS}
+                    FILTER IS_SAME_COLLECTION("records", record)
+                    FILTER record.connectorId == @connectorId
+                    FILTER record.indexingStatus == @completedStatus
+                    ${clause}
+                    RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET inheritedRecordGroupRecords = (
+        FOR recordGroup IN 1..1 ANY userDoc._id ${C.PERMISSION}
+            FILTER IS_SAME_COLLECTION("recordGroups", recordGroup)
+            FOR record IN 0..5 INBOUND recordGroup._id ${C.INHERIT_PERMISSIONS}
+                FILTER IS_SAME_COLLECTION("records", record)
+                FILTER record.connectorId == @connectorId
+                FILTER record.indexingStatus == @completedStatus
+                ${clause}
+                RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET anyoneRecords = (
+        FOR anyone IN @@anyone
+            FILTER anyone.organization == @orgId
+            FOR record IN @@records
+                FILTER record._key == anyone.file_key
+                FILTER record.connectorId == @connectorId
+                FILTER record.indexingStatus == @completedStatus
+                ${clause}
+                RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET allPairs = UNION(
+        directRecords, groupRecords, groupRecordsPermissionEdge,
+        orgRecords, orgRecordGroupRecords, recordGroupRecords,
+        inheritedRecordGroupRecords, anyoneRecords
+    )
+    FOR pair IN allPairs
+        FILTER pair != null AND pair.virtualRecordId != null AND pair.recordId != null
+        COLLECT virtualRecordId = pair.virtualRecordId INTO groups
+        LET recordId = FIRST(groups).pair.recordId
+        FILTER recordId != null
+        RETURN {virtualRecordId: virtualRecordId, recordId: recordId}`
+
+    try {
+      const rows = await this.client.executeAql(query, {
+        userId,
+        orgId,
+        connectorId,
+        completedStatus: COMPLETED_STATUS,
+        "@users": C.USERS,
+        "@records": C.RECORDS,
+        "@anyone": C.ANYONE,
+        ...mdBind,
+      })
+      return rowsToMap(rows)
+    } catch (e) {
+      this.log.error(`connector ${connectorId} acl query failed: ${String(e)}`)
+      return {}
+    }
+  }
+
+  // KB (RecordGroup) paths: direct membership + team membership.
+  private async getKbVirtualIds(
+    userId: string,
+    _orgId: string,
+    kbIds?: string[],
+    metadataFilters?: MetadataFilters,
+  ): Promise<AccessibleMap> {
+    const { clause, bindVars: mdBind } = buildMetadataFilters(metadataFilters)
+    const kbFilter = kbIds && kbIds.length ? "FILTER kb._key IN @kb_ids" : ""
+    const query = `
+    LET userDoc = FIRST(FOR user IN @@users FILTER user.userId == @userId RETURN user)
+
+    LET directKbRecords = (
+        FOR kb IN 1..1 ANY userDoc._id ${C.PERMISSION}
+            FILTER IS_SAME_COLLECTION("recordGroups", kb)
+            ${kbFilter}
+        FOR record IN 1..1 ANY kb._id ${C.BELONGS_TO}
+            FILTER IS_SAME_COLLECTION("records", record)
+            FILTER record.origin == "UPLOAD"
+            FILTER record.indexingStatus == @completedStatus
+            ${clause}
+            RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET teamKbRecords = (
+        FOR team, userTeamEdge IN 1..1 OUTBOUND userDoc._id ${C.PERMISSION}
+            FILTER IS_SAME_COLLECTION("teams", team)
+            FILTER userTeamEdge.type == "USER"
+        FOR kb, teamKbEdge IN 1..1 OUTBOUND team._id ${C.PERMISSION}
+            FILTER IS_SAME_COLLECTION("recordGroups", kb)
+            FILTER teamKbEdge.type == "TEAM"
+            ${kbFilter}
+        FOR record IN 1..1 ANY kb._id ${C.BELONGS_TO}
+            FILTER IS_SAME_COLLECTION("records", record)
+            FILTER record.origin == "UPLOAD"
+            FILTER record.indexingStatus == @completedStatus
+            ${clause}
+            RETURN {virtualRecordId: record.virtualRecordId, recordId: record._key}
+    )
+    LET allKbPairs = UNION(directKbRecords, teamKbRecords)
+    FOR pair IN allKbPairs
+        FILTER pair != null AND pair.virtualRecordId != null AND pair.recordId != null
+        COLLECT virtualRecordId = pair.virtualRecordId INTO groups
+        LET recordId = FIRST(groups).pair.recordId
+        FILTER recordId != null
+        RETURN {virtualRecordId: virtualRecordId, recordId: recordId}`
+
+    try {
+      const bind: Record<string, unknown> = {
+        userId,
+        completedStatus: COMPLETED_STATUS,
+        "@users": C.USERS,
+        ...mdBind,
+      }
+      if (kbIds && kbIds.length) bind.kb_ids = kbIds
+      const rows = await this.client.executeAql(query, bind)
+      return rowsToMap(rows)
+    } catch (e) {
+      this.log.error(`kb acl query failed: ${String(e)}`)
+      return {}
+    }
+  }
+
+  async getRecordsByRecordIds(recordIds: string[], orgId: string): Promise<RecordDoc[]> {
+    if (recordIds.length === 0) return []
+    const rows = await this.client.executeAql(
+      `FOR record IN @@records FILTER record._key IN @recordIds AND record.orgId == @orgId RETURN record`,
+      { "@records": C.RECORDS, recordIds, orgId },
+    )
+    return rows ?? []
+  }
+
+  async getDocument(recordId: string, collection: string): Promise<RecordDoc | null> {
+    const rows = await this.client.executeAql(
+      `FOR d IN @@col FILTER d._key == @recordId LIMIT 1 RETURN d`,
+      { "@col": collection, recordId },
+    )
+    return rows?.[0] ?? null
+  }
+}

package/src/bin.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+// Chitta entrypoint dispatcher. One binary, three modes:
+//   chitta                      → MCP stdio server (what MCP clients launch; the default)
+//   chitta install [...]        → wire Chitta into AI tools (MCP config + Skill)
+//   chitta ingest|query|...     → the embedded CLI
+// Sub-entrypoints self-run on import, so we route by dynamic import (no eager start).
+export {} // module marker (enables top-level await)
+
+// Arg layout differs by how we're launched:
+//   `bun run src/bin.ts <args>`  → argv = [bun, /path/bin.ts, ...args]   (args at index 2)
+//   compiled `./chitta <args>`   → argv = [/path/chitta, ...args]        (args at index 1)
+//   (the Node shim execs the compiled binary, so it hits the compiled layout too)
+// Detect via whether argv[1] is a script file, then NORMALIZE process.argv to the canonical
+// [exec, "chitta", ...args] so every downstream module's process.argv.slice(2) is correct.
+const launchedFromScript = !!process.argv[1] && /\.(ts|js|mjs|cjs)$/.test(process.argv[1])
+const userArgs = launchedFromScript ? process.argv.slice(2) : process.argv.slice(1)
+process.argv = [process.argv[0], "chitta", ...userArgs]
+
+const cmd = userArgs[0]
+
+if (!cmd || cmd.startsWith("-")) {
+  await import("./mcp/server") // bare invocation (or flags) = MCP server
+} else if (cmd === "install" || cmd === "uninstall") {
+  await import("./install/index")
+} else {
+  await import("./embedded/cli") // ingest | query | user-add | ...
+}

package/src/config-env.ts

@@ -0,0 +1,53 @@
+// Env-based config loader for the context layer. Dep-free so it stays testable.
+// v0 source of truth; later this can be superseded by the CLI config + per-session
+// identity (packages/identity) without touching the moat.
+
+import type { ContextConfig } from "./service"
+
+export interface ContextIdentity {
+  userId: string
+  orgId: string
+}
+
+type Env = Record<string, string | undefined>
+
+/** Returns null when the required backend vars aren't set (feature off). */
+export function loadContextConfigFromEnv(env: Env): ContextConfig | null {
+  const arangoUrl = env.CONTEXT_ARANGO_URL
+  const qdrantUrl = env.CONTEXT_QDRANT_URL
+  const denseEndpoint = env.CONTEXT_EMBED_URL
+  const collectionName = env.CONTEXT_COLLECTION
+  if (!arangoUrl || !qdrantUrl || !denseEndpoint || !collectionName) return null
+
+  return {
+    arango: {
+      url: arangoUrl,
+      database: env.CONTEXT_ARANGO_DB ?? "_system",
+      username: env.CONTEXT_ARANGO_USER,
+      password: env.CONTEXT_ARANGO_PASSWORD,
+    },
+    qdrant: { url: qdrantUrl, apiKey: env.CONTEXT_QDRANT_API_KEY },
+    embeddings: {
+      denseEndpoint,
+      denseModel: env.CONTEXT_EMBED_MODEL ?? "BAAI/bge-small-en-v1.5",
+      sparseEndpoint: env.CONTEXT_SPARSE_URL,
+    },
+    collectionName,
+  }
+}
+
+/** The asking user. v0 reads env; production wires this to packages/identity. */
+export function loadContextIdentityFromEnv(env: Env): ContextIdentity | null {
+  const userId = env.CONTEXT_USER_ID
+  const orgId = env.CONTEXT_ORG_ID
+  if (!userId || !orgId) return null
+  return { userId, orgId }
+}
+
+/** Names of the env vars, for help text / diagnostics. */
+export const REQUIRED_CONTEXT_ENV = [
+  "CONTEXT_ARANGO_URL",
+  "CONTEXT_QDRANT_URL",
+  "CONTEXT_EMBED_URL",
+  "CONTEXT_COLLECTION",
+] as const

package/src/embedded/authorizer.ts

@@ -0,0 +1,89 @@
+// Write-side access control - the mutation counterpart to the read ACL. Answers
+// "who can CREATE / MODIFY / DELETE / SHARE what", which read-filtering doesn't.
+//
+// Roles (per user): admin (full), editor (create + manage own), viewer (read only).
+// Ownership: the creator owns a record; only owner or admin may modify/delete it.
+// Grant validation: a non-admin can only share within their own org/groups - they
+// cannot grant access to principals or orgs outside their scope (no over-sharing).
+
+import type { SqliteStore } from "./sqlite-store"
+
+export type Role = "admin" | "editor" | "viewer"
+
+export class AuthorizationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "AuthorizationError"
+  }
+}
+
+export class Authorizer {
+  constructor(private readonly store: SqliteStore) {}
+
+  roleOf(userId: string): Role {
+    const r = this.store.db.query("SELECT data FROM nodes WHERE id = ? AND coll = 'users' LIMIT 1").get(userId) as
+      | { data: string }
+      | undefined
+    if (!r) return "viewer"
+    return ((JSON.parse(r.data) as { role?: Role }).role ?? "viewer") as Role
+  }
+
+  ownerOf(recordId: string): string | null {
+    const r = this.store.db.query("SELECT data FROM nodes WHERE id = ? AND coll = 'records' LIMIT 1").get(recordId) as
+      | { data: string }
+      | undefined
+    return r ? ((JSON.parse(r.data) as { ownerId?: string }).ownerId ?? null) : null
+  }
+
+  /** May this user create new records? (editor or admin) */
+  canCreate(userId: string): boolean {
+    return this.roleOf(userId) !== "viewer"
+  }
+
+  /** May this user modify/delete this record? (admin, or the record's owner) */
+  canModify(userId: string, recordId: string): boolean {
+    return this.roleOf(userId) === "admin" || this.ownerOf(recordId) === userId
+  }
+
+  private memberships(userId: string): Set<string> {
+    const rows = this.store.db.query("SELECT dst FROM edges WHERE src = ? AND label = 'belongsTo'").all(userId) as Array<{
+      dst: string
+    }>
+    return new Set(rows.map((r) => r.dst))
+  }
+
+  private belongsToOrg(principal: string, orgId: string): boolean {
+    return !!this.store.db
+      .query("SELECT 1 FROM edges WHERE src = ? AND dst = ? AND label = 'belongsTo' LIMIT 1")
+      .get(principal, orgId)
+  }
+
+  /** A non-admin may only grant to themselves, their own groups/teams, principals
+   *  in the same org, or share-with-own-org. Throws on any out-of-scope grant. */
+  assertCanGrant(userId: string, orgId: string, principals: string[], shareWithOrg?: string): void {
+    if (this.roleOf(userId) === "admin") return
+    if (shareWithOrg && shareWithOrg !== orgId) {
+      throw new AuthorizationError(`cannot share to org '${shareWithOrg}' - outside your org`)
+    }
+    const mine = this.memberships(userId)
+    for (const p of principals) {
+      const ok = p === userId || p === orgId || mine.has(p) || this.belongsToOrg(p, orgId)
+      if (!ok) throw new AuthorizationError(`cannot grant access to '${p}' - outside your scope`)
+    }
+  }
+
+  /** Throws unless the user may create with the requested sharing. */
+  assertCanCreate(userId: string, orgId: string, principals: string[], shareWithOrg?: string): void {
+    if (!this.canCreate(userId)) {
+      throw new AuthorizationError(`user '${userId}' (role: ${this.roleOf(userId)}) is not permitted to create records`)
+    }
+    this.assertCanGrant(userId, orgId, principals, shareWithOrg)
+  }
+
+  assertCanModify(userId: string, recordId: string): void {
+    if (!this.canModify(userId, recordId)) {
+      const owner = this.ownerOf(recordId) ?? "none"
+      throw new AuthorizationError(`user '${userId}' may not modify/delete '${recordId}' (owner: ${owner})`)
+    }
+  }
+}

package/src/embedded/cli.ts

@@ -0,0 +1,86 @@
+// Standalone context CLI - the complete system in one runnable program.
+// Persists to a real .db file, so ingest and query work across invocations.
+//
+//   bun run cli.ts user-add alice --org org1
+//   bun run cli.ts ingest --id doc1 --org org1 --name "Notes" --share-user alice --text "hello world"
+//   bun run cli.ts query "hello" --user alice --org org1
+//
+// Compile to a single binary:
+//   bun build cli.ts --compile --outfile ctx
+
+import { buildEmbeddedContext } from "./index"
+
+function arg(flag: string, fallback?: string): string | undefined {
+  const i = process.argv.indexOf(flag)
+  return i >= 0 && i + 1 < process.argv.length ? process.argv[i + 1] : fallback
+}
+function has(flag: string): boolean {
+  return process.argv.includes(flag)
+}
+
+async function main() {
+  const cmd = process.argv[2]
+  const dbPath = arg("--db", process.env.CONTEXT_DB ?? "context.db")!
+  const ctx = buildEmbeddedContext({ path: dbPath })
+
+  switch (cmd) {
+    case "user-add": {
+      const userId = process.argv[3]
+      const org = arg("--org", "org1")!
+      ctx.ingestor.registerUser(userId, org, arg("--email"))
+      console.log(`user '${userId}' added to org '${org}'`)
+      break
+    }
+    case "group-add": {
+      ctx.ingestor.registerGroup(process.argv[3])
+      console.log(`group '${process.argv[3]}' added`)
+      break
+    }
+    case "member-add": {
+      ctx.ingestor.addMembership(process.argv[3], arg("--group")!)
+      console.log(`'${process.argv[3]}' added to group '${arg("--group")}'`)
+      break
+    }
+    case "ingest": {
+      const out = await ctx.ingestor.ingest({
+        recordId: arg("--id") ?? `rec-${Date.now().toString(36)}`,
+        orgId: arg("--org", "org1")!,
+        recordName: arg("--name", "Untitled")!,
+        text: arg("--text") ?? (arg("--file") ? await Bun.file(arg("--file")!).text() : ""),
+        permittedPrincipals: [arg("--share-user"), arg("--share-group")].filter(Boolean) as string[],
+        shareWithOrg: has("--share-org") ? arg("--org", "org1") : undefined,
+      })
+      console.log(`ingested '${out.recordId}' (${out.chunks} chunks)`)
+      break
+    }
+    case "query": {
+      const res = await ctx.retrieval.searchWithFilters({
+        queries: [process.argv[3]],
+        userId: arg("--user")!,
+        orgId: arg("--org", "org1")!,
+        limit: Number(arg("--limit", "5")),
+      })
+      console.log(`status: ${res.status}`)
+      for (const r of res.searchResults) {
+        console.log(`  • [${r.metadata.recordName}] ${r.content.slice(0, 80)}`)
+      }
+      if (res.searchResults.length === 0) console.log("  (no accessible context)")
+      break
+    }
+    case "rebuild-graph": {
+      const res = await ctx.rebuildGraph()
+      console.log(`rebuilt knowledge graph: ${res.records} records → ${res.entities} concept-mentions`)
+      break
+    }
+    case "reindex-vectors": {
+      const n = await ctx.reindex()
+      console.log(`re-embedded ${n} chunks and rebuilt the vector index`)
+      break
+    }
+    default:
+      console.log("commands: user-add | group-add | member-add | ingest | query | rebuild-graph | reindex-vectors")
+  }
+  ctx.store.close()
+}
+
+main()

package/src/embedded/code-extractor.ts

@@ -0,0 +1,9 @@
+// Code → graph extractor (the Graphify capability, ported TS-native). Parses source
+// with tree-sitter (WASM grammars) into the SAME entity/edge shape every other
+// extractor produces - so code nodes get ACL, vectors, temporal edges, and graph
+// algorithms for free. STRICT SUPERSET of Graphify in one embedded store.
+//
+// Thin facade: the implementation lives in ./extractors/code and is re-exported here
+// so existing imports keep resolving unchanged. Public API is preserved exactly.
+
+export { CodeExtractor } from "./extractors/code"

package/src/embedded/demo.ts

@@ -0,0 +1,36 @@
+// Single-binary demo. Compile with:
+//   bun build src/context/embedded/demo.ts --compile --outfile ctxdemo
+// Then run ./ctxdemo - one self-contained executable, no servers, no Python.
+
+import { buildEmbeddedContext, LocalHashEmbeddings } from "./index"
+
+async function main() {
+  const ctx = buildEmbeddedContext({ path: ":memory:" })
+  const emb = new LocalHashEmbeddings()
+  const ORG = "org1"
+  const rec = (id: string, vid: string, name: string) => ({
+    _key: id, virtualRecordId: vid, orgId: ORG, indexingStatus: "COMPLETED",
+    origin: "CONNECTOR", recordName: name, mimeType: "text/plain", connectorId: "slack", connectorName: "slack",
+  })
+
+  ctx.store.addNode("org1", "organizations", { name: "Acme" })
+  ctx.store.addNode("alice", "users", { userId: "alice", email: "alice@acme.co" })
+  ctx.store.addNode("bob", "users", { userId: "bob", email: "bob@acme.co" })
+  ctx.store.addEdge("alice", "org1", "belongsTo")
+  ctx.store.addEdge("bob", "org1", "belongsTo")
+  ctx.store.addNode("recPub", "records", rec("recPub", "vPub", "Q3 Revenue Report"))
+  ctx.store.addNode("anyPub", "anyone", { organization: ORG, file_key: "recPub" })
+  ctx.store.addNode("recSec", "records", rec("recSec", "vSec", "Secret Merger Plans"))
+  ctx.store.addEdge("alice", "recSec", "permissions")
+  ctx.store.addChunk("p1", "vPub", ORG, "quarterly revenue report Q3", await emb.embedDense("quarterly revenue report"))
+  ctx.store.addChunk("p2", "vSec", ORG, "secret merger plans globex", await emb.embedDense("secret merger plans globex"))
+
+  for (const user of ["alice", "bob"]) {
+    const res = await ctx.retrieval.searchWithFilters({ queries: ["secret merger plans"], userId: user, orgId: ORG })
+    const names = res.searchResults.map((r) => r.metadata.recordName)
+    console.log(`${user} → [${names.join(", ") || "nothing"}]`)
+  }
+  console.log("(expected: alice sees the Secret doc; bob does NOT - ACL enforced in one binary)")
+}
+
+main()