chore: import upstream snapshot with attribution

examples/showcases/oracle-agent-memory/db/init/00-register-listener.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Railway remote-access fix (ORA-12514 / DPY-6001 "FREEPDB1 not registered").
+#
+# Railway's private network is dual-stack. The agent connects to the database over
+# IPv4 (10.x), but the DB's primary address -- what UTL_INADDR.GET_HOST_ADDRESS
+# returns -- is IPv6 (fd12:...). Registering the listener service on the IPv6 address
+# therefore leaves the IPv4-connecting agent with ORA-12514. This script pins
+# LOCAL_LISTENER to the container's own IPv4 address so PMON publishes both FREE (CDB)
+# and FREEPDB1 (PDB) to the TCP listener on the exact endpoint the agent reaches.
+#
+# Runs on every container boot (startup hook). SCOPE=MEMORY -- re-applied each boot.
+# The echoed IP + sqlplus output let the deploy logs confirm the fix applied, and on
+# which address, without needing shell access to the running container.
+#
+# Written to be safe whether the startup runner executes or sources it: no `set -e`
+# and no `exit` (which would abort the runner / skip 01-create-user.sql).
+
+IP4="$(hostname -I 2>/dev/null | tr ' ' '\n' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' | grep -vE '^127\.' | head -1)"
+
+if [ -z "$IP4" ]; then
+  echo "[register-listener] no non-loopback IPv4 found (hostname -I: $(hostname -I 2>/dev/null)); leaving LOCAL_LISTENER at default"
+else
+  echo "[register-listener] registering services on IPv4 ${IP4}:1521"
+  SQLPLUS="${ORACLE_HOME:+${ORACLE_HOME}/bin/}sqlplus"
+  "$SQLPLUS" -s "/ as sysdba" <<SQL
+WHENEVER SQLERROR CONTINUE
+ALTER SESSION SET CONTAINER = CDB\$ROOT;
+ALTER SYSTEM SET LOCAL_LISTENER='(ADDRESS=(PROTOCOL=TCP)(HOST=${IP4})(PORT=1521))' SCOPE=MEMORY;
+ALTER SYSTEM REGISTER;
+EXIT
+SQL
+  echo "[register-listener] done (IPv4 ${IP4})"
+fi

examples/showcases/oracle-agent-memory/db/init/01-create-user.sql

@@ -0,0 +1,88 @@
+-- Creates the `cookbook` application user inside the FREEPDB1 pluggable database
+-- with the privileges oracleagentmemory needs (tables + AI Vector Search), and a
+-- dedicated ASSM tablespace as its DEFAULT.
+--
+-- WHY THE ASSM TABLESPACE: oracleagentmemory creates tables with native JSON columns
+-- and a VECTOR column + HNSW vector index. Those segments are SecureFile LOB/BLOBs,
+-- which Oracle forbids in a Manual Segment Space Management (MSSM) tablespace
+-- (ORA-43853). On the Free `:latest-lite` image FREEPDB1 has NO USERS tablespace and
+-- its default permanent tablespace is SYSTEM (MSSM), so a user with no DEFAULT
+-- TABLESPACE lands on SYSTEM and the first JSON table fails. We therefore create an
+-- ASSM tablespace (cookbook_ts) and make it the user's default.
+--
+-- Idempotent — safe to run on every container boot (startup hook). Self-heals ONLY
+-- the genuinely broken case: a `cookbook` user stranded on the SYSTEM tablespace
+-- (MSSM), which is FREEPDB1's default permanent tablespace on :latest-lite and is what
+-- raises ORA-43853. Such a user is dropped (CASCADE) and recreated on cookbook_ts.
+-- DROP USER CASCADE is the correct self-heal because Oracle DDL auto-commits: a prior
+-- failed run can leave non-JSON tables (schema_meta, actor_profile) stranded in SYSTEM
+-- with empty metadata, and oracleagentmemory's 'create_if_necessary' policy will NOT
+-- recover from that — it raises a metadata-validation error instead of recreating into
+-- the new tablespace. CASCADE removes those stranded objects regardless of tablespace.
+--
+-- A user already on a working ASSM tablespace (e.g. USERS on the local :latest image)
+-- is LEFT UNTOUCHED, so re-running stays non-destructive on the documented local flow.
+-- The self-heal drop assumes a fresh boot with no live `cookbook` session (true for the
+-- ephemeral, no-volume demo: the DB is recreated each restart). Using a persisted volume
+-- would need session-disconnect handling before the drop (the agent reconnects as soon
+-- as the listener is up) — out of scope while the demo runs volume-less.
+ALTER SESSION SET CONTAINER = FREEPDB1;
+
+SET SERVEROUTPUT ON
+DECLARE
+  ts_count    INTEGER;
+  user_count  INTEGER;
+  default_ts  VARCHAR2(128);
+BEGIN
+  -- 1) Dedicated ASSM tablespace (guarded: CREATE TABLESPACE is NOT idempotent and
+  --    raises ORA-01543 if it already exists; REUSE only protects the datafile, not
+  --    the tablespace metadata). The datafile path is the verified PDB datafile dir
+  --    for the Free image (ORACLE_SID/db_name = FREE; OMF is off so an explicit path
+  --    is required). REUSE re-adopts an orphaned datafile left on the persisted volume.
+  SELECT COUNT(*) INTO ts_count
+    FROM dba_tablespaces
+   WHERE tablespace_name = 'COOKBOOK_TS';
+  IF ts_count = 0 THEN
+    EXECUTE IMMEDIATE
+      'CREATE TABLESPACE cookbook_ts ' ||
+      'DATAFILE ''/opt/oracle/oradata/FREE/FREEPDB1/cookbook_ts01.dbf'' ' ||
+      'SIZE 256M REUSE AUTOEXTEND ON NEXT 64M MAXSIZE 2G ' ||
+      'EXTENT MANAGEMENT LOCAL SEGMENT SPACE MANAGEMENT AUTO';
+    DBMS_OUTPUT.PUT_LINE('cookbook_ts tablespace created (ASSM)');
+  ELSE
+    DBMS_OUTPUT.PUT_LINE('cookbook_ts tablespace already exists - skipping');
+  END IF;
+
+  -- 2) Self-heal ONLY a user stranded on SYSTEM (MSSM) — the sole default that causes
+  --    ORA-43853 (only FREEPDB1's default on :latest-lite). Drop + recreate it on the
+  --    ASSM tablespace. A user already on a working ASSM tablespace (e.g. USERS on the
+  --    local :latest image, or cookbook_ts itself) is left untouched, so re-running is
+  --    non-destructive there. dba_users.default_tablespace is stored uppercase.
+  SELECT COUNT(*) INTO user_count
+    FROM dba_users WHERE username = 'COOKBOOK';
+
+  IF user_count > 0 THEN
+    SELECT default_tablespace INTO default_ts
+      FROM dba_users WHERE username = 'COOKBOOK';
+    IF default_ts = 'SYSTEM' THEN
+      DBMS_OUTPUT.PUT_LINE('cookbook is on SYSTEM (MSSM) - dropping to self-heal onto cookbook_ts');
+      EXECUTE IMMEDIATE 'DROP USER cookbook CASCADE';
+      user_count := 0;
+    ELSE
+      DBMS_OUTPUT.PUT_LINE('cookbook user default tablespace is ' || default_ts ||
+                           ' (ASSM) - leaving as-is');
+    END IF;
+  END IF;
+
+  IF user_count = 0 THEN
+    EXECUTE IMMEDIATE
+      'CREATE USER cookbook IDENTIFIED BY "cookbook_pw" ' ||
+      'DEFAULT TABLESPACE cookbook_ts TEMPORARY TABLESPACE temp';
+    EXECUTE IMMEDIATE 'GRANT DB_DEVELOPER_ROLE TO cookbook';
+    -- GRANT UNLIMITED TABLESPACE covers quota on every tablespace (incl. cookbook_ts),
+    -- so no separate QUOTA clause is needed; one privilege, no redundancy.
+    EXECUTE IMMEDIATE 'GRANT UNLIMITED TABLESPACE TO cookbook';
+    DBMS_OUTPUT.PUT_LINE('cookbook user created (DEFAULT TABLESPACE cookbook_ts)');
+  END IF;
+END;
+/